> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Configurando a integração

> Configure o Plugin Pix Indireto (BTG): licenciamento, autenticação, Midaz, CRM, conectividade com o BTG e configuração dos workers.

O Plugin Pix Indireto (BTG) conecta a vários serviços da Lerian e a provedores externos para processar pagamentos Pix. Para configurá-lo, você define a conexão do plugin com cada serviço e prepara os dados de que esses serviços precisam.

O plugin roda em duas camadas principais. A **Application** expõe a API do Pix e processa a lógica de negócio. Os **Workers** tratam os webhooks recebidos do BTG, a entrega de eventos ao seu sistema, a conciliação do DICT com o BACEN e os pagamentos agendados. As duas camadas compartilham a mesma configuração de base (licença, Midaz, CRM, BTG), mas têm as próprias configurações específicas de serviço.

# Pré-requisitos

***

Antes de começar, confirme que você tem:

* O seu **ISPB** (Identificador do Sistema de Pagamentos Brasileiro): o identificador de 8 caracteres derivado do CNPJ da sua instituição
* Acesso às suas instâncias do Midaz e do CRM (com deploy feito e rodando)
* Acesso aos serviços do provedor BTG (o BTG fornece as credenciais)

```bash theme={null}
# Your institution's ISPB (8 characters: digits or uppercase letters)
PIX_ISPB=12345678
```

> [!NOTE]
>
> O plugin usa o `PIX_ISPB` para gerar e verificar os IDs end-to-end. Já as transferências intra-PSP (P2P) ele detecta pela conta alias do pagador: veja [Transferências intra-PSP](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-intra-psp.md).

# 1. Licença

***

O plugin exige uma licença válida para operar. A Lerian fornece a chave de licença durante o onboarding.

```bash theme={null}
# License key provided by Lerian
LICENSE_KEY=

# Authorized organization IDs (comma-separated)
ORGANIZATION_IDS=
```

**Documentação relacionada:** [Licença da Lerian](https://docs.lerian.studio/pt/start-here/evaluate-and-deploy/lerians-license.md)

# 2. Access Manager (opcional)

***

O Access Manager cuida da autenticação do plugin. Quando está habilitado, ele valida as requisições recebidas antes de elas chegarem à API do plugin.

```bash theme={null}
# Require authentication for plugin requests (true/false)
PLUGIN_AUTH_ENABLED=false

# Access Manager service URL (required: the plugin also gets its Midaz, CRM, and Fee tokens here)
PLUGIN_AUTH_ADDRESS=
```

Quando `PLUGIN_AUTH_ENABLED=true`, o plugin valida o header `Authorization` de cada requisição para garantir que:

* O token pertence a um usuário ou aplicação autorizada
* O token dá acesso ao endpoint e ao método da API solicitados

> [!NOTE]
>
> As credenciais de cliente (`CLIENT_ID` / `CLIENT_SECRET`) do Midaz e do CRM são obrigatórias mesmo quando `PLUGIN_AUTH_ENABLED=false`. As credenciais de tarifas são obrigatórias quando `CASHIN_FEE_CALCULATION_TYPE=segment`.

**Documentação relacionada:** [Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md)

# 3. Midaz

***

O Midaz é o ledger central de todas as transações Pix que o plugin processa. O plugin lança cada operação de cash-in, cash-out e devolução no Midaz como uma transação por partidas dobradas.

## Conexão

***

```bash theme={null}
# Your organization ID in Midaz
MIDAZ_ORGANIZATION_ID=

# Your ledger ID in Midaz
MIDAZ_LEDGER_ID=

# Midaz Transaction module URL
MIDAZ_TRANSACTION_URL=

# Midaz Onboarding module URL
MIDAZ_ONBOARDING_URL=

# Midaz API credentials (required)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=
```

## Requisitos de ativo

***

Configure um ativo na sua organização e no seu ledger com estas propriedades:

| Propriedade | Valor |
| - | - |
| Tipo | `currency` |
| Código | `BRL` |

Vincule todas as contas ao seu ledger usando o ativo `BRL`. O plugin rejeita operações em contas que não seguem essa configuração.

## Configuração das contas

***

Antes de usar o plugin, crie uma conta no Midaz para cada cliente sob o seu ISPB.

Use o endpoint **Create an Account** para criar as contas. Cada conta deve:

* Pertencer à organização e ao ledger que você configurou
* Usar o ativo `BRL`

## Header X-Account-Id

***

Muitas operações Pix exigem o header `X-Account-Id` para identificar qual conta executa a ação. Esse ID corresponde ao **ID da conta no ledger do Midaz**.

Quando você chama um endpoint do plugin, o valor de `X-Account-Id` diz ao plugin:

* Qual conta usar nas operações do ledger
* Quais dados de cliente buscar no CRM
* Qual saldo validar e atualizar

### Como o plugin usa o ID da conta

O plugin usa o ID da conta de formas diferentes conforme o tipo de operação:

| Tipo de fluxo | Como o plugin usa o ID da conta |
| - | - |
| **Não transacional** (por exemplo, criação de chaves ou QR codes) | Busca os dados do cliente e da conta bancária no CRM |
| **Transacional** (por exemplo, pagamentos, devoluções) | Busca os dados do cliente para iniciar o pagamento |
| | Valida os dados da conta para autorizar o pagamento recebido |
| | Executa a transação no ledger |

## Conformidade das contas

***

O plugin verifica o status da conta no Midaz. Ele recusa uma iniciação de transferência, um cash-out ou uma devolução de uma conta `BLOCKED`. Ele também recusa um Pix recebido para uma conta que não está `ACTIVE`.

Para impedir liquidações Pix em uma conta específica, bloqueie a conta direto no Midaz. O plugin recebe uma rejeição quando tenta lançar a transação.

**Documentação relacionada:**

* [Atualizar uma conta](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-account.md)
* [Atualizar um saldo](https://docs.lerian.studio/pt/reference/products/midaz/v2/update-balance.md)

# 4. CRM

***

O CRM guarda as informações do cliente (titular) e as contas bancárias associadas a ele. Cada conta do Midaz deve ter um **titular** e uma **conta alias** correspondentes no CRM para executar operações Pix.

O plugin consulta os dados do CRM para:

* Registrar e validar chaves Pix
* Montar as mensagens de pagamento para o BACEN
* Autorizar as transações recebidas
* Processar os workflows de devolução e de disputa

## Conexão

***

```bash theme={null}
# CRM base URL
PLUGIN_CRM_BASE_URL=

# CRM API credentials (required)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=
```

## Titulares

***

Os dados do titular representam o cliente dono da conta. Crie cada titular no CRM antes de executar qualquer operação Pix para esse cliente.

### Campos obrigatórios

| Campo | Requisito | Exemplo |
| - | - | - |
| `name` | No máximo 120 caracteres | `Maria Silva Santos` |
| `document` | Para `NATURAL_PERSON`, um CPF com 11 dígitos; para `LEGAL_PERSON`, um CNPJ com 14 caracteres, numérico ou alfanumérico | `12345678900` |
| `type` | Tipo de pessoa (valores de enum do CRM) | `NATURAL_PERSON` |

### Campos opcionais

| Campo | Quando usar |
| - | - |
| `legalPerson.tradeName` | Quando você associa um nome fantasia aos dados da chave |
| `addresses.primary` | Obrigatório para criar uma cobrança com vencimento |

**Documentação relacionada:** [Criar um titular](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-holder.md)

## Contas alias

***

As contas alias ligam uma conta do Midaz aos dados bancários dela. Cada conta alias deve incluir as informações bancárias que o ecossistema Pix exige para processar transações.

### Campos obrigatórios

| Campo | Requisito | Exemplo |
| - | - | - |
| `accountId` | ID da conta no Midaz (UUID) | `3c90c3cc-0d44-4b50-8888-8dd25736052a` |
| `bankingDetails.branch` | Exatamente 4 dígitos | `0001` |
| `bankingDetails.account` | De 1 a 20 letras maiúsculas ou dígitos, com o dígito verificador | `123456789` |
| `bankingDetails.type` | Tipo de conta (veja a tabela abaixo) | `CACC` |
| `bankingDetails.openingDate` | Formato YYYY-MM-DD | `2024-01-15` |
| `bankingDetails.bankId` | O ISPB da instituição que mantém a conta. Obrigatório para enviar um Pix | `12345678` |

> [!WARNING]
>
> O campo `bankingDetails.branch` deve conter exatamente 4 dígitos. Complete com zeros à esquerda se necessário. Por exemplo, se o número da agência é `1`, registre como `0001`. O plugin consegue validar a conta no CRM apenas quando o código da agência segue esse formato.

Quando o dígito verificador é uma letra, o DICT o recebe como `0`: uma conta guardada como `AB1234567X` é registrada no DICT como `AB12345670`. Mantenha o valor original no CRM.

### Tipos de conta aceitos

| Código | Descrição |
| - | - |
| `CACC` | Conta corrente |
| `SLRY` | Conta salário |
| `SVGS` | Conta poupança |
| `TRAN` | Conta transacional |
| `OTHR` | Outra |

Você não pode registrar nem reivindicar uma chave Pix para uma conta `SLRY`. O plugin retorna `PIX-0129`.

**Documentação relacionada:** [Criar uma conta alias](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-instrument.md)

# 5. Provedor BTG

***

O BTG é o participante direto que conecta sua instituição à infraestrutura do Pix no BACEN. O BTG fornece as credenciais diretamente quando sua instituição contrata a integração indireta com o BACEN.

## Conexão

***

```bash theme={null}
# BTG API base URL
BTG_BASE_URL=

# BTG API credentials
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=
```

## mTLS (segurança dos webhooks)

***

O TLS mútuo (mTLS) valida o certificado do BTG nas requisições de webhook. Ele confirma que os webhooks recebidos vêm do BTG. O seu ingress repassa o certificado que o BTG apresenta no header `MTLS_CERTIFICATE_HEADER` (padrão `X-Client-Cert`).

```bash theme={null}
# Enable mTLS validation (true/false)
# Use 'true' in production, 'false' for local development
MTLS_ENABLED=false

# How long to cache the certificate before refreshing
# Format: Go duration (e.g., 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# BTG endpoint that provides the public certificate (required when MTLS_ENABLED=true)
BTG_CERTIFICATE_URL=

# Timeout for certificate fetch requests
# Format: Go duration (e.g., 10s, 30s)
MTLS_HTTP_TIMEOUT=10s
```

> [!WARNING]
>
> Sempre habilite o mTLS em ambientes de produção. Desabilite apenas durante o desenvolvimento local.

Para apresentar um certificado de cliente nas chamadas do próprio plugin ao BTG, defina `BTG_OUTBOUND_MTLS_ENABLED=true` com `CLIENT_TLS_CERT_FILE` e `CLIENT_TLS_KEY_FILE`. Veja [Variáveis de ambiente](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-environment-variables.md).

# 6. Serviço de tarifas (opcional)

***

Habilite o cálculo de tarifas para cobrar e distribuir tarifas automaticamente nos pagamentos recebidos. Isso é opcional. Se você não configurar, o plugin processa as transações sem cálculo de tarifas.

## Conexão

***

```bash theme={null}
# Fee calculation method (currently only 'segment' is supported)
CASHIN_FEE_CALCULATION_TYPE=

# Fee service URL
FEE_SERVICE_URL=

# Request timeout in milliseconds
FEE_SERVICE_TIMEOUT=5000

# Fee service API credentials (required when CASHIN_FEE_CALCULATION_TYPE=segment)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=
```

## Como funciona

***

Quando você define `CASHIN_FEE_CALCULATION_TYPE=segment`, o plugin:

1. **Busca o segmento** associado à conta que recebe
2. **Calcula as tarifas aplicáveis** antes de processar a transação no Midaz
3. **Distribui o pagamento recebido** conforme as regras de pacote ligadas a esse segmento

## Passos de configuração

***

1. **Crie segmentos no Midaz**: defina os segmentos de conta que determinam as regras de tarifa
2. **Configure pacotes no Fees Engine**: ligue cada segmento às regras de cálculo de tarifa dele
3. **Atribua segmentos às contas**: crie ou atualize contas do Midaz com o ID de segmento adequado

**Documentação relacionada:**

* [Fees Engine - Guias](https://docs.lerian.studio/pt/products/midaz/fees/fees-engine-overview.md)
* [Fees Engine - APIs](https://docs.lerian.studio/pt/reference/products/midaz/v2/create-package.md)

# Conciliação do DICT (VSync)

***

O VSync concilia seus dados locais do DICT com o BACEN processando todos os eventos do dia relacionados a chaves. Ele mantém seu estado local consistente com os registros oficiais do BACEN.

```bash theme={null}
# Write block window (24-hour format, America/Sao_Paulo time)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Network allowed to write Pix keys during the window
RECONCILIATION_INTERNAL_CIDR=
```

> [!WARNING]
>
> Durante a janela, a API rejeita as requisições de criação, atualização e exclusão de chaves Pix para evitar inconsistências de dados com o BACEN. Planeje a janela de bloqueio de escrita para períodos de baixo tráfego.

## Configuração do cache Redis

***

O VSync usa o Redis para fazer cache dos vínculos do BTG/DICT e dos titulares do CRM durante a conciliação. Nos deploys com Helm, o `REDIS_HOST` padrão aponta para o Valkey embutido, então uma instalação padrão não exige configuração extra.

```bash theme={null}
# Connection (always used)
REDIS_HOST=<valkey-host>:6379
REDIS_MASTER_NAME=
REDIS_DB=0
REDIS_PROTOCOL=3

# Connection pool and retries (always used)
REDIS_POOL_SIZE=10
REDIS_MIN_IDLE_CONNS=0
REDIS_READ_TIMEOUT=3
REDIS_WRITE_TIMEOUT=3
REDIS_DIAL_TIMEOUT=5
REDIS_POOL_TIMEOUT=2
REDIS_MAX_RETRIES=3
REDIS_MIN_RETRY_BACKOFF=8
REDIS_MAX_RETRY_BACKOFF=512

# Authentication (optional — only used if set)
REDIS_PASSWORD=

# TLS (optional — only used if REDIS_TLS=true)
REDIS_TLS=false
REDIS_CA_CERT=

# GCP IAM authentication (optional — only used if REDIS_USE_GCP_IAM=true)
REDIS_USE_GCP_IAM=false
REDIS_SERVICE_ACCOUNT=
GOOGLE_APPLICATION_CREDENTIALS=
REDIS_TOKEN_LIFETIME=60
REDIS_TOKEN_REFRESH_DURATION=45

# VSync cache TTLs (always used)
CACHE_BTG_ENTRY_TTL=30m
CACHE_CRM_HOLDER_TTL=30m
```

### Conexão (sempre usada)

| Var | Tipo | Padrão | Descrição |
| - | - | - | - |
| `REDIS_HOST` | string (host:porta, CSV) | Valkey embutido (Helm chart) | Endereço(s) do Redis. Vários endereços separados por vírgula definem a topologia Sentinel/Cluster. |
| `REDIS_MASTER_NAME` | string | `""` | Nome do master no Sentinel. Vazio = standalone (conexão direta). |
| `REDIS_DB` | int | `0` | Número do banco lógico do Redis. |
| `REDIS_PROTOCOL` | int | `3` | Versão do protocolo RESP (2 ou 3). |

### Pool de conexões e novas tentativas (sempre usados)

| Var | Tipo | Padrão | Descrição |
| - | - | - | - |
| `REDIS_POOL_SIZE` | int | `10` | Número máximo de conexões no pool. |
| `REDIS_MIN_IDLE_CONNS` | int | `0` | Número mínimo de conexões ociosas mantidas prontas. |
| `REDIS_READ_TIMEOUT` | int (segundos) | `3` | Timeout da operação de leitura. |
| `REDIS_WRITE_TIMEOUT` | int (segundos) | `3` | Timeout da operação de escrita. |
| `REDIS_DIAL_TIMEOUT` | int (segundos) | `5` | Timeout para estabelecer a conexão inicial. |
| `REDIS_POOL_TIMEOUT` | int (segundos) | `2` | Timeout de espera por uma conexão livre do pool. |
| `REDIS_MAX_RETRIES` | int | `3` | Número máximo de novas tentativas para um comando com falha. |
| `REDIS_MIN_RETRY_BACKOFF` | int (milissegundos) | `8` | Atraso mínimo entre as novas tentativas. |
| `REDIS_MAX_RETRY_BACKOFF` | int (segundos) | `512` | Atraso máximo entre as novas tentativas. Nota: armazenado em segundos no código (unidade diferente da do mínimo). |

### Autenticação (opcional, usada apenas se definida)

| Var | Tipo | Padrão | Descrição |
| - | - | - | - |
| `REDIS_PASSWORD` | string (segredo) | `""` | Senha do Redis. Vazio = sem autenticação por senha. |

### TLS (opcional, usado apenas se `REDIS_TLS=true`)

| Var | Tipo | Padrão | Descrição |
| - | - | - | - |
| `REDIS_TLS` | bool | `false` | Habilita o TLS. Obrigatório `true` em `DEPLOYMENT_MODE=saas` (validado na inicialização). |
| `REDIS_CA_CERT` | string (PEM base64) | `""` | Certificado da CA (base64) para validar o servidor quando o TLS está ativo. |

### Autenticação IAM da GCP (opcional, usada apenas se `REDIS_USE_GCP_IAM=true`)

| Var | Tipo | Padrão | Descrição |
| - | - | - | - |
| `REDIS_USE_GCP_IAM` | bool | `false` | Habilita a autenticação IAM da GCP (Memorystore) em vez de senha. |
| `REDIS_SERVICE_ACCOUNT` | string | `""` | Conta de serviço da GCP que gera o token de acesso. |
| `GOOGLE_APPLICATION_CREDENTIALS` | string | `""` | Credenciais da GCP (um caminho de arquivo ou o conteúdo JSON) para gerar o token. |
| `REDIS_TOKEN_LIFETIME` | int (minutos) | `60` | Tempo de vida do token IAM gerado. |
| `REDIS_TOKEN_REFRESH_DURATION` | int (minutos) | `45` | Intervalo de renovação do token (deve ser menor que o tempo de vida). |

### TTLs do cache do VSync (sempre usados)

| Var | Tipo | Padrão | Descrição |
| - | - | - | - |
| `CACHE_BTG_ENTRY_TTL` | duração Go | `30m` | TTL de cache dos vínculos do BTG/DICT no Redis. Valor negativo volta ao padrão. |
| `CACHE_CRM_HOLDER_TTL` | duração Go | `30m` | TTL de cache dos titulares do CRM no Redis. Valor negativo volta ao padrão. |

# 8. Segurança dos webhooks internos

***

O plugin usa um canal de comunicação interno entre os serviços Worker e Application. As assinaturas HMAC-SHA256 protegem esse canal contra adulteração e ataques de replay.

```bash theme={null}
# Shared secret for signing internal requests (Worker -> Application)
# Must be at least 32 characters
# Generate one with: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validate signatures on incoming internal webhooks (true/false)
# Always use 'true' in production
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Maximum age (in seconds) for request timestamps before rejection
# Default: 300 (5 minutes)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300
```

> [!WARNING]
>
> Use exatamente o mesmo valor de `INTERNAL_WEBHOOK_SECRET` nos serviços Application e Worker. Uma divergência faz o plugin rejeitar todos os webhooks internos.

# 9. Camadas de worker

***

O plugin opera com quatro workers, cada um cuidando de uma parte diferente do ciclo de vida do Pix. Cada worker roda como um serviço separado ao lado da aplicação principal.

## Worker de entrada

***

A Application recebe as notificações de webhook do BTG e as armazena. Depois, o worker de entrada entrega cada notificação aos endpoints internos da Application para processamento.

```bash theme={null}
# Application URL for internal webhooks
WEBHOOK_INBOUND_BASE_URL=

# Shared secret for signing requests (must match the application's INTERNAL_WEBHOOK_SECRET)
INTERNAL_WEBHOOK_SECRET=
```

## Worker de saída

***

O worker de saída envia as notificações de evento do plugin para a sua aplicação por webhooks. É assim que o seu sistema fica informado sobre os eventos Pix (transferências, devoluções, reivindicações, disputas).

### Prioridade de resolução de URL

O plugin resolve as URLs de webhook nesta ordem, usando a primeira que corresponder:

1. **URL de entidade**: uma URL específica do tipo de evento (por exemplo, `WEBHOOK_DICT_CLAIM_URL`)
2. **URL de fluxo**: uma URL para a categoria mais ampla (por exemplo, `WEBHOOK_DICT_URL`)
3. **URL padrão**: a URL de fallback (`WEBHOOK_DEFAULT_URL`)

```bash theme={null}
# Default fallback URL
WEBHOOK_DEFAULT_URL=

# DICT-related events
WEBHOOK_DICT_URL=
WEBHOOK_DICT_CLAIM_URL=
WEBHOOK_DICT_INFRACTION_REPORT_URL=
WEBHOOK_DICT_REFUND_URL=

# MED 2.0 Funds Recovery events (DICT flow)
# These route under the DICT flow and fall back to WEBHOOK_DICT_URL,
# then WEBHOOK_DEFAULT_URL, if no entity-specific URL is set.
WEBHOOK_DICT_FUNDS_RECOVERY_URL=
WEBHOOK_DICT_FUNDS_RECOVERY_EVENTS_URL=

# Refund events
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Transfer events
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=
```

Cada entidade precisa da própria variável `WEBHOOK_<FLOW>_<ENTITY>_*`. Veja [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md).

Para tipos de evento de webhook, payloads, comportamento de novas tentativas e boas práticas, veja o [guia de Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md).

## Worker de conciliação

***

O worker de conciliação precisa das mesmas credenciais da camada Application para estes serviços:

* **CRM**: URL e credenciais
* **BTG**: URL e credenciais
* **Midaz**: ID da organização

Ele também chama a API da Application com as próprias credenciais de cliente: `PLUGIN_PIX_BTG_BASE_URL`, `PLUGIN_PIX_BTG_CLIENT_ID` e `PLUGIN_PIX_BTG_CLIENT_SECRET`, com o endpoint de token em `PLUGIN_AUTH_URL`.

Veja as seções correspondentes acima para detalhes de cada configuração.

Você pode restringir quando o worker opera configurando uma janela de horário específica. Isso ajuda a agendar as tarefas de conciliação fora do horário de pico. O plugin aceita janelas de horário que atravessam a meia-noite.

```bash theme={null}
# Start time in HH:MM format (24-hour, BRT). Example: "23:00" for 11 PM BRT
RECONCILIATION_START_TIME=

# End time in HH:MM format (24-hour, BRT). Example: "05:00" for 5 AM BRT
RECONCILIATION_END_TIME=
```

> [!NOTE]
>
> Se você deixar os dois campos vazios, o worker roda sem restrição de horário (24/7).

> [!NOTE]
>
> O worker sempre interpreta a janela de conciliação no fuso **`America/Sao_Paulo`** (BRT), qualquer que seja o relógio do contêiner ou a variável `TZ`. O worker embute os dados de fuso horário da IANA. A janela continua alinhada com o bloqueio de escrita do DICT do BACEN, mesmo em imagens mínimas ou distroless. Você não precisa definir `TZ`.

## Worker de agendamento

***

O worker de agendamento executa os pagamentos Pix agendados quando vencem. Ele vem desligado por padrão. Ele chama a API da Application com as mesmas variáveis de credenciais de cliente do worker de conciliação.

```bash theme={null}
# Turn the worker on (default false)
SCHEDULE_WORKER_ENABLED=true

# Application API URL
SCHEDULE_APP_BASE_URL=

# Token endpoint and the worker's client credentials
PLUGIN_AUTH_URL=
PLUGIN_PIX_BTG_CLIENT_ID=
PLUGIN_PIX_BTG_CLIENT_SECRET=
```

> [!NOTE]
>
> Os endpoints de cashout e de devolução do Pix Indireto aceitam idempotência pelo header de requisição `X-Idempotency`. O plugin guarda uma resposta reutilizável por `IDEMPOTENCY_RESPONSE_TTL` segundos (padrão `86400`, 24 horas). Para estratégias de nova tentativa e detalhes de implementação, veja [Novas tentativas e idempotência](https://docs.lerian.studio/pt/reference/retries-idempotency.md).

# 10. Observabilidade (OpenTelemetry)

***

O plugin vem com instrumentação OpenTelemetry (traces, métricas e logs) nas camadas Application e Worker. O plugin rastreia os fluxos Pix de ponta a ponta: transferências (cash-in e cash-out), devoluções, webhooks de entrada e de saída, conciliação do DICT e liquidação intra-PSP. Você pode seguir um único pagamento pelas chamadas ao plugin, ao Midaz, ao CRM e ao BTG.

A telemetria vem desabilitada por padrão. Habilite e aponte o exporter OTLP para o seu collector:

```bash theme={null}
# Master switch — telemetry is off until this is true
ENABLE_TELEMETRY=true

# Resource attributes that identify this service in your backend
OTEL_RESOURCE_SERVICE_NAME=plugin-br-pix-indirect-btg
OTEL_RESOURCE_SERVICE_VERSION=${VERSION}
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=${ENV_NAME}

# OTLP collector endpoint (gRPC, default port 4317)
OTEL_EXPORTER_OTLP_ENDPOINT_PORT=4317
OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:${OTEL_EXPORTER_OTLP_ENDPOINT_PORT}
```

> [!NOTE]
>
> Quando `ENABLE_TELEMETRY=true`, `OTEL_EXPORTER_OTLP_ENDPOINT` é obrigatório. Defina as mesmas variáveis do OTel na Application e em cada Worker para os traces se correlacionarem entre os serviços.

## Exporter: gRPC e TLS

***

O plugin exporta traces, métricas e logs por OTLP/gRPC. O esquema do endpoint controla a segurança do transporte:

| Valor do endpoint | Transporte | Segurança |
| - | - | - |
| `https://collector:4317` | gRPC sobre TLS | Seguro (recomendado para produção) |
| `http://collector:4317` | gRPC, texto puro | Inseguro (inferido automaticamente) |
| `collector:4317` (`host:port` puro) | gRPC, texto puro | Inseguro (inferido automaticamente) |

> [!WARNING]
>
> Quando `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` é `production` ou `prod`, o plugin se recusa a iniciar com um exporter inseguro. Use um endpoint `https://`, ou defina `ALLOW_INSECURE_OTEL` com uma justificativa curta apenas quando você controla totalmente o caminho de rede até o collector.

## Exemplo: endpoint do collector

***

Aponte o plugin para qualquer collector compatível com OTLP (o OpenTelemetry Collector, Grafana LGTM/Alloy etc.) que escute na porta gRPC:

```bash theme={null}
# Local / development (plaintext gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Production (TLS gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4317
```

O collector então distribui a telemetria para os seus backends de tracing, métricas e logs.

# 11. Health e readiness

***

A Application e os Workers expõem uma probe de readiness em **`/readyz`** (ao lado das verificações padrão de liveness). Aponte a probe de readiness do seu orquestrador para esse endpoint para o tráfego ser roteado apenas quando o serviço e as dependências dele estiverem prontos.

# Propósito da transferência (MED 2.0)

***

O endpoint de cashout aceita um header opcional `X-Purpose` que identifica o propósito da transação, usado nas transferências de devolução do MED 2.0. Quando omitido, o padrão é `TRANSFER`.

```bash theme={null}
# Example: a MED 2.0 refund transfer
POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND
```

Para os valores aceitos, veja [Transferências](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-transfers.md).

# Próximos passos

***

Com o plugin configurado, você pode começar a operar o Pix.

* [Webhooks](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-webhooks.md): tipos de evento, payloads, novas tentativas e boas práticas
* [MED 2.0: Recuperação de Fundos](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-med-2-funds-recovery.md): recuperação de fraude entre contas e o header X-Purpose
* [Operações de devolução](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-refund-operations.md): devoluções parciais distribuídas e desbloqueio
* [Transferências intra-PSP](https://docs.lerian.studio/pt/interfaces/pix-btg/indirect-pix-intra-psp.md): liquidação P2P interna e reporte TRCK002
* [Domínios principais: DICT](https://docs.lerian.studio/pt/interfaces/pix/main-domains-dict.md): entender a gestão de chaves Pix
* [Domínios principais: transações](https://docs.lerian.studio/pt/interfaces/pix/main-domains-transactions.md): fluxos e ciclo de vida das transações
* [Domínios principais: QR Codes](https://docs.lerian.studio/pt/interfaces/pix/main-domains-qrcodes.md): geração de QR code estático e dinâmico
* [Referência da API](https://docs.lerian.studio/pt/reference/interfaces/pix-btg/create-entry.md): documentação completa da API para as operações de DICT, reivindicações, transações, QR Codes e MED


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.