7. Conciliação do DICT (VSync)

> ## 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

> Um guia completo para configurar o Plugin Pix Indireto (BTG): do licenciamento e da autenticação ao Midaz, ao 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 e a conciliação do DICT com o BACEN. 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 dígitos 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 digits)
PIX_ISPB=12345678
```

<Note>
  `PIX_ISPB` também serve para detectar **transferências intra-PSP (P2P)**: quando o ISPB de destino de uma transferência é igual a esse valor, o plugin a liquida internamente em vez de encaminhá-la ao BTG, e continua reportando ao BACEN. Veja [Transferências intra-PSP](/pt/interfaces/pix-btg/indirect-pix-intra-psp).
</Note>

# 1. Licença

***

O plugin é uma solução enterprise e 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](/pt/start-here/evaluate-and-deploy/lerians-license)

# 2. Access Manager (opcional)

***

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

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

# Access Manager service URL
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>
  Você precisa fornecer credenciais de cliente (`CLIENT_ID` / `CLIENT_SECRET`) para os serviços Midaz, CRM e de tarifas apenas se esses serviços também tiverem a autenticação do Access Manager habilitada.
</Note>

**Documentação relacionada:** [Access Manager](/pt/platform/access-manager)

# 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 if Midaz has authentication enabled)
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 **não** aplica restrições de conta no nível de negócio, como contas bloqueadas ou suspensas. A sua aplicação deve validar o status da conta antes de chamar o plugin.

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](/pt/reference/products/midaz/v2/update-account)
* [Atualizar um saldo](/pt/reference/products/midaz/v2/update-balance)

# 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 if CRM has authentication enabled)
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 dígitos (apenas números) | `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](/pt/reference/products/midaz/v2/create-holder)

## 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 dígitos                    | `123456789`                            |
| `bankingDetails.type`        | Tipo de conta (veja a tabela abaixo) | `CACC`                                 |
| `bankingDetails.openingDate` | Formato YYYY-MM-DD                   | `2024-01-15`                           |

<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.
</Warning>

### Tipos de conta aceitos

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

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

# 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.

```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 for signature validation
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.
</Warning>

# 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 if the fee service has authentication enabled)
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](/pt/products/midaz/fees/fees-engine-overview)
* [Fees Engine - APIs](/pt/reference/products/midaz/v2/create-package)

<h1 id="7-dict-reconciliation-vsync">
  7. Conciliação do DICT (VSync)
</h1>

***

O VSync concilia seus dados locais do DICT com o BACEN processando todos os eventos do dia relacionados a chaves. Isso garante que seu estado local fique consistente com os registros oficiais do BACEN.

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

# Allowed network range for reconciliation services
RECONCILIATION_INTERNAL_CIDR=
```

<Warning>
  Durante a conciliação, o banco bloqueia temporariamente as operações de escrita para evitar inconsistências de dados com o BACEN. Planeje a janela de bloqueio de escrita para períodos de baixo tráfego.
</Warning>

<Note>
  A faixa CIDR restringe quais redes podem disparar a conciliação. O plugin rejeita automaticamente as requisições que vêm de fora dessa faixa.
</Note>

## 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 sidecar Valkey embutido, então uma instalação padrão não exige configuração extra.

```bash theme={null}
# Connection (always used)
REDIS_HOST=<release>-valkey: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
```

<Note>
  Nos deploys com Helm, o `REDIS_HOST` padrão aponta para o sidecar Valkey embutido (`<release-name>-valkey:6379`). Nenhuma configuração adicional de Redis é necessária, a menos que você conecte a uma instância externa.
</Note>

### Conexão (sempre usada)

| Var                 | Tipo                     | Padrão                               | Descrição                                                                                                                                                                 |
| ------------------- | ------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REDIS_HOST`        | string (host:porta, CSV) | `<release>-valkey:6379` (Helm chart) | Endereço(s) do Redis. O padrão aponta para o Valkey embutido (`<release-name>-valkey:6379`). 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        | `""`    | Caminho das credenciais da GCP (lido via CredentialsBase64FromEnvValue) 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.
</Warning>

# 9. Camadas de worker

***

O plugin opera com três camadas de worker, cada uma cuidando de uma parte diferente do ciclo de vida do Pix. Todos os workers rodam como serviços separados ao lado da aplicação principal.

## Worker de entrada

***

O worker de entrada recebe as notificações de webhook do BTG e as encaminha para a sua aplicação processar.

```bash theme={null}
# URL where the application receives 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_EVENT_URL=

# Refund events
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Transfer events
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=
```

<Tip>
  Você pode começar apenas com `WEBHOOK_DEFAULT_URL` para receber todos os eventos em um único endpoint e depois separar aos poucos em URLs por entidade conforme o seu sistema evolui.
</Tip>

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

## 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

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>

<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`.
</Note>

<Note>
  Os endpoints de cashout e de devolução do Pix Indireto aceitam idempotência pelo header de requisição `X-Idempotency`, com TTL configurável por `X-TTL`. Para estratégias de nova tentativa e detalhes de implementação, veja [Novas tentativas e idempotência](/pt/reference/retries-idempotency).
</Note>

# 10. Observabilidade (OpenTelemetry)

***

O plugin vem com instrumentação **OpenTelemetry** completa (traces, métricas e logs) nas camadas Application e Worker. O plugin rastreia cada fluxo 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_LIBRARY_NAME=github.com/LerianStudio/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.
</Note>

## 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>
  Exporters inseguros (texto puro) são rejeitados fora de ambientes de desenvolvimento. Em staging ou produção, use um endpoint `https://`, ou aceite o risco explicitamente pela permissão de OTEL inseguro do lib-commons apenas quando você controla totalmente o caminho de rede até o collector.
</Warning>

## 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
```

Os valores aceitos são `TRANSFER` e `INSTANT_PAYMENT_REFUND`. Veja [MED 2.0 — Funds Recovery](/pt/interfaces/pix-btg/indirect-pix-med-2-funds-recovery) para detalhes.

# Próximos passos

***

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

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