> ## 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.
# Configuración de la integración
> Una guía completa para configurar el Plugin Pix Indirecto (BTG): desde el licenciamiento y la autenticación hasta Midaz, CRM, la conectividad con BTG y la puesta a punto de los workers.
El Plugin Pix Indirecto (BTG) se conecta con varios servicios de Lerian y proveedores externos para procesar pagos Pix. Para configurarlo, defines la conexión del plugin con cada servicio y preparas los datos que esos servicios necesitan.
El plugin se ejecuta en dos capas principales. La **Aplicación** expone la API de Pix y procesa la lógica de negocio. Los **Workers** atienden los webhooks entrantes de BTG, la entrega de eventos salientes a tu sistema y la conciliación de DICT con BACEN. Ambas capas comparten la misma configuración base (licencia, Midaz, CRM, BTG), pero tienen sus propios ajustes específicos de servicio.
# Prerrequisitos
***
Antes de empezar, confirma que tienes:
* Tu **ISPB** (Identificador do Sistema de Pagamentos Brasileiro): el identificador de 8 dígitos derivado del CNPJ de tu institución
* Acceso a tus instancias de **Midaz** y **CRM** (desplegadas y en ejecución)
* Acceso a los servicios del proveedor **BTG** (BTG entrega las credenciales)
```bash theme={null}
# Your institution's ISPB (8 digits)
PIX_ISPB=12345678
```
`PIX_ISPB` también se usa para detectar las **transferencias intra-PSP (P2P)**: cuando el ISPB de destino de una transferencia coincide con este valor, el plugin la liquida internamente en lugar de enrutarla a BTG, y de todos modos la reporta a BACEN. Consulta [Transferencias intra-PSP](/es/interfaces/pix-btg/indirect-pix-intra-psp).
# 1. Licencia
***
El plugin es una solución enterprise y requiere una licencia válida para operar. Lerian entrega la clave de licencia durante el onboarding.
```bash theme={null}
# License key provided by Lerian
LICENSE_KEY=
# Authorized organization IDs (comma-separated)
ORGANIZATION_IDS=
```
**Documentación relacionada:** [La licencia de Lerian](/es/start-here/evaluate-and-deploy/lerians-license)
# 2. Access Manager (opcional)
***
Access Manager atiende la autenticación del plugin. Cuando está habilitado, valida todas las solicitudes entrantes antes de que lleguen a la API del plugin.
```bash theme={null}
# Require authentication for all plugin requests (true/false)
PLUGIN_AUTH_ENABLED=false
# Access Manager service URL
PLUGIN_AUTH_ADDRESS=
```
Cuando `PLUGIN_AUTH_ENABLED=true`, el plugin valida el header `Authorization` de cada solicitud para confirmar que:
* El token pertenece a un usuario o una aplicación autorizados
* El token concede acceso al endpoint y al método de la API solicitados
Solo necesitas entregar credenciales de cliente (`CLIENT_ID` / `CLIENT_SECRET`) para los servicios de Midaz, CRM y comisiones si esos servicios también tienen habilitada la autenticación con Access Manager.
**Documentación relacionada:** [Access Manager](/es/platform/access-manager)
# 3. Midaz
***
Midaz es el ledger central de todas las transacciones Pix que procesa el plugin. El plugin registra cada operación de cash-in, cash-out y devolución en Midaz como una transacción de partida doble.
## Conexión
***
```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 del activo
***
Configura un activo en tu organización y ledger con estas propiedades:
| Propiedad | Valor |
| --------- | ---------- |
| Tipo | `currency` |
| Código | `BRL` |
Vincula todas las cuentas a tu ledger con el activo `BRL`. El plugin rechaza las operaciones sobre cuentas que no cumplen esta configuración.
## Configuración de cuentas
***
Antes de usar el plugin, crea una cuenta en Midaz para cada cliente bajo tu ISPB.
Usa el endpoint **Create an Account** para configurar las cuentas. Cada cuenta debe:
* Pertenecer a la organización y al ledger que configuraste
* Usar el activo `BRL`
## Header X-Account-Id
***
Muchas operaciones Pix requieren el header `X-Account-Id` para identificar qué cuenta ejecuta la acción. Este ID corresponde al **ID de la cuenta del ledger de Midaz**.
Cuando llamas a un endpoint del plugin, el valor de `X-Account-Id` le indica al plugin:
* Qué cuenta usar para las operaciones del ledger
* Qué datos de cliente obtener del CRM
* Qué saldo validar y actualizar
### Cómo el plugin usa el ID de cuenta
El plugin usa el ID de cuenta de forma distinta según el tipo de operación:
| Tipo de flujo | Cómo el plugin usa el ID de cuenta |
| ------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **No transaccional** (por ejemplo, la creación de claves o de códigos QR) | Obtiene del CRM los datos del cliente y de la cuenta bancaria |
| **Transaccional** (por ejemplo, pagos, devoluciones) | Obtiene los datos del cliente para iniciar el pago |
| | Valida los datos de la cuenta para autorizar el pago entrante |
| | Ejecuta la transacción en el ledger |
## Cumplimiento de la cuenta
***
El plugin **no** aplica restricciones de cuenta en el nivel de negocio, como cuentas bloqueadas o suspendidas. Tu aplicación debe validar el estado de la cuenta antes de llamar al plugin.
Para impedir liquidaciones Pix en una cuenta específica, bloquéala directamente en Midaz. El plugin recibe un rechazo cuando intenta registrar la transacción.
**Documentación relacionada:**
* [Update an Account](/es/reference/products/midaz/v2/update-account)
* [Update a Balance](/es/reference/products/midaz/v2/update-balance)
# 4. CRM
***
El CRM guarda la información del cliente (titular) y sus cuentas bancarias asociadas. Cada cuenta de Midaz debe tener un **titular** y una **cuenta alias** correspondientes en el CRM para ejecutar operaciones Pix.
El plugin consulta los datos del CRM para:
* Registrar y validar las claves Pix
* Construir los mensajes de pago para BACEN
* Autorizar las transacciones entrantes
* Procesar los workflows de devolución y de disputa
## Conexión
***
```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
***
Los datos del titular representan al cliente dueño de la cuenta. Crea cada titular en el CRM antes de ejecutar cualquier operación Pix para ese cliente.
### Campos obligatorios
| Campo | Requisito | Ejemplo |
| ---------- | ------------------------------------------------------------------------------------------------------ | -------------------- |
| `name` | Máximo 120 caracteres | `Maria Silva Santos` |
| `document` | Para `NATURAL_PERSON`, un CPF de 11 dígitos; para `LEGAL_PERSON`, un CNPJ de 14 dígitos (solo números) | `12345678900` |
| `type` | Tipo de persona (valores enum del CRM) | `NATURAL_PERSON` |
### Campos opcionales
| Campo | Cuándo usarlo |
| ----------------------- | ---------------------------------------------------------- |
| `legalPerson.tradeName` | Cuando asocias un nombre comercial a los datos de la clave |
| `addresses.primary` | Obligatorio para crear una cobranza con vencimiento |
**Documentación relacionada:** [Create a Holder](/es/reference/products/midaz/v2/create-holder)
## Cuentas alias
***
Las cuentas alias vinculan una cuenta de Midaz con sus datos bancarios. Cada cuenta alias debe incluir la información bancaria que el ecosistema Pix requiere para procesar transacciones.
### Campos obligatorios
| Campo | Requisito | Ejemplo |
| ---------------------------- | -------------------------------------------- | -------------------------------------- |
| `accountId` | ID de la cuenta de Midaz (UUID) | `3c90c3cc-0d44-4b50-8888-8dd25736052a` |
| `bankingDetails.branch` | Exactamente 4 dígitos | `0001` |
| `bankingDetails.account` | De 1 a 20 dígitos | `123456789` |
| `bankingDetails.type` | Tipo de cuenta (consulta la tabla siguiente) | `CACC` |
| `bankingDetails.openingDate` | Formato YYYY-MM-DD | `2024-01-15` |
El campo `bankingDetails.branch` debe contener exactamente **4 dígitos**. Rellena con ceros a la izquierda si hace falta. Por ejemplo, si el número de sucursal es `1`, regístralo como `0001`. El plugin solo puede validar la cuenta en el CRM cuando el código de sucursal sigue este formato.
### Tipos de cuenta admitidos
| Código | Descripción |
| ------ | -------------------- |
| `CACC` | Cuenta corriente |
| `SLRY` | Cuenta de nómina |
| `SVGS` | Cuenta de ahorro |
| `TRAN` | Cuenta transaccional |
**Documentación relacionada:** [Create an Alias Account](/es/reference/products/midaz/v2/create-instrument)
# 5. Proveedor BTG
***
BTG es el participante directo que conecta tu institución con la infraestructura Pix de BACEN. BTG entrega las credenciales directamente cuando tu institución se suscribe a la integración indirecta con BACEN.
## Conexión
***
```bash theme={null}
# BTG API base URL
BTG_BASE_URL=
# BTG API credentials
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=
```
## mTLS (seguridad de los webhooks)
***
El TLS mutuo (mTLS) valida el certificado de BTG en las solicitudes de webhook. Confirma que los webhooks entrantes se originan en 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
```
Habilita siempre mTLS en los entornos de producción. Deshabilítalo solo durante el desarrollo local.
# 6. Servicio de comisiones (opcional)
***
Habilita el cálculo de comisiones para cobrar y distribuir comisiones de forma automática sobre los pagos entrantes. Es opcional. Si no lo configuras, el plugin procesa las transacciones sin cálculo de comisiones.
## Conexión
***
```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=
```
## Cómo funciona
***
Cuando defines `CASHIN_FEE_CALCULATION_TYPE=segment`, el plugin:
1. **Obtiene el segmento** asociado a la cuenta receptora
2. **Calcula las comisiones aplicables** antes de procesar la transacción en Midaz
3. **Distribuye el pago entrante** según las reglas de paquete vinculadas a ese segmento
## Pasos de configuración
***
1. **Crea segmentos en Midaz**: define los segmentos de cuenta que determinan las reglas de comisión
2. **Configura paquetes en Fees Engine**: vincula cada segmento con sus reglas de cálculo de comisiones
3. **Asigna segmentos a las cuentas**: crea o actualiza cuentas de Midaz con el ID de segmento correspondiente
**Documentación relacionada:**
* [Fees Engine - Guías](/es/products/midaz/fees/fees-engine-overview)
* [Fees Engine - APIs](/es/reference/products/midaz/v2/create-package)
7. Conciliación de DICT (VSync)
***
VSync concilia tus datos locales de DICT con BACEN al procesar todos los eventos del día relacionados con claves. Así tu estado local se mantiene consistente con los registros de referencia de 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=
```
Durante la conciliación, la base de datos bloquea temporalmente las operaciones de escritura para evitar inconsistencias de datos con BACEN. Planifica la ventana de bloqueo de escritura en periodos de bajo tráfico.
El rango CIDR restringe qué redes pueden disparar la conciliación. El plugin rechaza de forma automática las solicitudes que vienen de fuera de ese rango.
## Configuración del cache de Redis
***
VSync usa Redis para guardar en cache las entradas de BTG/DICT y los titulares del CRM durante la conciliación. En los despliegues con Helm, el `REDIS_HOST` predeterminado apunta al sidecar de Valkey incluido, así que una instalación estándar no requiere configuración adicional.
```bash theme={null}
# Connection (always used)
REDIS_HOST=-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
```
En los despliegues con Helm, el `REDIS_HOST` predeterminado apunta al sidecar de Valkey incluido (`-valkey:6379`). No hace falta configuración adicional de Redis a menos que te conectes a una instancia externa.
### Conexión (siempre se usa)
| Var | Tipo | Predeterminado | Descripción |
| ------------------- | ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `REDIS_HOST` | string (host:port, CSV) | `-valkey:6379` (Helm chart) | Dirección o direcciones de Redis. El valor predeterminado apunta al Valkey incluido (`-valkey:6379`). Varias direcciones separadas por coma definen una topología Sentinel o Cluster. |
| `REDIS_MASTER_NAME` | string | `""` | Nombre del master de Sentinel. Vacío = standalone (conexión directa). |
| `REDIS_DB` | int | `0` | Número de la base de datos lógica de Redis. |
| `REDIS_PROTOCOL` | int | `3` | Versión del protocolo RESP (2 o 3). |
### Pool de conexiones y reintentos (siempre se usa)
| Var | Tipo | Predeterminado | Descripción |
| ------------------------- | ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------ |
| `REDIS_POOL_SIZE` | int | `10` | Máximo de conexiones en el pool. |
| `REDIS_MIN_IDLE_CONNS` | int | `0` | Mínimo de conexiones inactivas que se mantienen listas. |
| `REDIS_READ_TIMEOUT` | int (segundos) | `3` | Timeout de la operación de lectura. |
| `REDIS_WRITE_TIMEOUT` | int (segundos) | `3` | Timeout de la operación de escritura. |
| `REDIS_DIAL_TIMEOUT` | int (segundos) | `5` | Timeout para establecer la conexión inicial. |
| `REDIS_POOL_TIMEOUT` | int (segundos) | `2` | Timeout de espera por una conexión libre del pool. |
| `REDIS_MAX_RETRIES` | int | `3` | Máximo de reintentos de un comando fallido. |
| `REDIS_MIN_RETRY_BACKOFF` | int (milisegundos) | `8` | Espera mínima entre reintentos. |
| `REDIS_MAX_RETRY_BACKOFF` | int (segundos) | `512` | Espera máxima entre reintentos. Nota: en el código se guarda en segundos (unidad distinta de la del mínimo). |
### Autenticación (opcional, solo se usa si se define)
| Var | Tipo | Predeterminado | Descripción |
| ---------------- | ---------------- | -------------- | -------------------------------------------------------------- |
| `REDIS_PASSWORD` | string (secreto) | `""` | Contraseña de Redis. Vacío = sin autenticación por contraseña. |
### TLS (opcional, solo se usa si `REDIS_TLS=true`)
| Var | Tipo | Predeterminado | Descripción |
| --------------- | ------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `REDIS_TLS` | bool | `false` | Habilita TLS. Obligatorio en `true` con `DEPLOYMENT_MODE=saas` (se valida en el arranque). |
| `REDIS_CA_CERT` | string (PEM base64) | `""` | Certificado de CA (base64) para validar el servidor cuando TLS está activo. |
### Autenticación IAM de GCP (opcional, solo se usa si `REDIS_USE_GCP_IAM=true`)
| Var | Tipo | Predeterminado | Descripción |
| -------------------------------- | ------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| `REDIS_USE_GCP_IAM` | bool | `false` | Habilita la autenticación IAM de GCP (Memorystore) en lugar de la contraseña. |
| `REDIS_SERVICE_ACCOUNT` | string | `""` | Cuenta de servicio de GCP que genera el token de acceso. |
| `GOOGLE_APPLICATION_CREDENTIALS` | string | `""` | Ruta de las credenciales de GCP (se lee con CredentialsBase64FromEnvValue) para generar el token. |
| `REDIS_TOKEN_LIFETIME` | int (minutos) | `60` | Duración del token IAM generado. |
| `REDIS_TOKEN_REFRESH_DURATION` | int (minutos) | `45` | Intervalo de actualización del token (debe ser menor que la duración). |
### TTL del cache de VSync (siempre se usa)
| Var | Tipo | Predeterminado | Descripción |
| ---------------------- | ----------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `CACHE_BTG_ENTRY_TTL` | Go duration | `30m` | TTL del cache de las entradas de BTG/DICT en Redis. Un valor negativo vuelve al predeterminado. |
| `CACHE_CRM_HOLDER_TTL` | Go duration | `30m` | TTL del cache de los titulares del CRM en Redis. Un valor negativo vuelve al predeterminado. |
# 8. Seguridad de los webhooks internos
***
El plugin usa un canal de comunicación interno entre los servicios Worker y Aplicación. Las **firmas HMAC-SHA256** protegen este canal para evitar manipulaciones y ataques de repetición.
```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
```
Usa exactamente el mismo valor de `INTERNAL_WEBHOOK_SECRET` en los servicios Aplicación y Worker. Una discrepancia hace que el plugin rechace todos los webhooks internos.
# 9. Capas de workers
***
El plugin opera con tres capas de workers, y cada una atiende una parte distinta del ciclo de vida de Pix. Todos los workers se ejecutan como servicios separados junto a la aplicación principal.
## Worker de entrada
***
El worker de entrada recibe las notificaciones de webhook de BTG y las reenvía a tu aplicación para su procesamiento.
```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 salida
***
El worker de salida envía notificaciones de evento desde el plugin hacia tu aplicación por webhooks. Así tu sistema se mantiene informado sobre los eventos Pix (transferencias, devoluciones, reclamaciones, disputas).
### Prioridad de resolución de URL
El plugin resuelve las URL de webhook en este orden, y usa la primera que coincide:
1. **URL de entidad**: una URL específica del tipo de evento (por ejemplo, `WEBHOOK_DICT_CLAIM_URL`)
2. **URL de flujo**: una URL para la categoría más amplia (por ejemplo, `WEBHOOK_DICT_URL`)
3. **URL predeterminada**: la URL de respaldo (`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=
```
Puedes empezar solo con `WEBHOOK_DEFAULT_URL` para recibir todos los eventos en un único endpoint, y después separar de a poco en URL específicas por entidad a medida que tu sistema evoluciona.
Para los tipos de evento de webhook, los payloads, el comportamiento de reintento y las mejores prácticas, consulta la [guía de Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks).
## Worker de conciliación
***
El worker de conciliación necesita las mismas credenciales que la capa Aplicación para estos servicios:
* **CRM**: URL y credenciales
* **BTG**: URL y credenciales
* **Midaz**: ID de organización
Consulta las secciones correspondientes de más arriba para conocer los detalles de cada configuración.
Puedes restringir cuándo opera el worker si configuras una ventana de tiempo específica. Sirve para programar las tareas de conciliación en horas de baja demanda. El plugin admite ventanas de tiempo que cruzan la medianoche.
```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=
```
Si dejas ambos campos vacíos, el worker se ejecuta sin restricciones de horario (24/7).
El worker siempre interpreta la ventana de conciliación en la zona horaria **`America/Sao_Paulo`** (BRT), sea cual sea el reloj del contenedor o la variable `TZ`. El worker incluye los datos de zonas horarias de IANA. La ventana se mantiene alineada con el bloqueo de escritura de DICT de BACEN, incluso en imágenes mínimas o distroless. No necesitas definir `TZ`.
Los endpoints de cashout y de devolución de Pix Indirecto admiten idempotencia con el header de solicitud `X-Idempotency`, con TTL configurable mediante `X-TTL`. Para estrategias de reintento y detalles de implementación, consulta [Reintentos e idempotencia](/es/reference/retries-idempotency).
# 10. Observabilidad (OpenTelemetry)
***
El plugin viene con instrumentación completa de **OpenTelemetry** (trazas, métricas y logs) en las capas Aplicación y Worker. El plugin traza cada flujo Pix de extremo a extremo: **transferencias** (cash-in y cash-out), **devoluciones**, **webhooks** entrantes y salientes, **conciliación** de DICT y liquidación **intra-PSP**. Puedes seguir un solo pago a través del plugin y de las llamadas a Midaz, al CRM y a BTG.
La telemetría está deshabilitada de forma predeterminada. Habilítala y apunta el exportador OTLP a tu 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}
```
Cuando `ENABLE_TELEMETRY=true`, `OTEL_EXPORTER_OTLP_ENDPOINT` es obligatorio. Define las mismas variables de OTel en la Aplicación y en cada Worker para que las trazas se correlacionen entre servicios.
## Exportador: gRPC y TLS
***
El plugin exporta trazas, métricas y logs por **OTLP/gRPC**. El esquema del endpoint controla la seguridad del transporte:
| Valor del endpoint | Transporte | Seguridad |
| ------------------------------------- | ----------------- | ----------------------------------------- |
| `https://collector:4317` | gRPC sobre TLS | Seguro (recomendado para producción) |
| `http://collector:4317` | gRPC, texto plano | Inseguro — se infiere de forma automática |
| `collector:4317` (`host:port` simple) | gRPC, texto plano | Inseguro — se infiere de forma automática |
Los exportadores inseguros (en texto plano) se rechazan fuera de los entornos de desarrollo. En staging o producción, usa un endpoint `https://`, o acepta el riesgo de forma explícita con el permiso de OTEL inseguro de lib-commons solo cuando controlas por completo la ruta de red hacia el collector.
## Ejemplo: endpoint del collector
***
Apunta el plugin a cualquier collector compatible con OTLP (el OpenTelemetry Collector, Grafana LGTM/Alloy, etc.) que escuche en el puerto 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
```
Después el collector distribuye la telemetría a tus backends de trazas, métricas y logs.
# 11. Health y readiness
***
La Aplicación y los Workers exponen una sonda de readiness en **`/readyz`** (junto con las verificaciones estándar de liveness). Apunta la sonda de readiness de tu orquestador a este endpoint para que el tráfico se enrute solo cuando el servicio y sus dependencias están listos.
# Propósito de la transferencia (MED 2.0)
***
El endpoint de cashout acepta un header opcional `X-Purpose` que identifica el propósito de la transacción, usado en las transferencias de devolución de MED 2.0. Cuando se omite, el valor predeterminado es `TRANSFER`.
```bash theme={null}
# Example: a MED 2.0 refund transfer
POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND
```
Los valores admitidos son `TRANSFER` e `INSTANT_PAYMENT_REFUND`. Consulta [MED 2.0 — Recuperación de fondos](/es/interfaces/pix-btg/indirect-pix-med-2-funds-recovery) para los detalles.
# Próximos pasos
***
Con el plugin configurado, puedes empezar a operar Pix.
* [Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks): tipos de evento, payloads, reintentos y mejores prácticas
* [MED 2.0 — Recuperación de fondos](/es/interfaces/pix-btg/indirect-pix-med-2-funds-recovery): recuperación de fraude entre cuentas y el header X-Purpose
* [Operaciones de devolución](/es/interfaces/pix-btg/indirect-pix-refund-operations): devoluciones parciales distribuidas y desbloqueo
* [Transferencias intra-PSP](/es/interfaces/pix-btg/indirect-pix-intra-psp): liquidación P2P interna y reporte TRCK002
* [Dominios principales: DICT](/es/interfaces/pix/main-domains-dict): entender la gestión de claves Pix
* [Dominios principales: transacciones](/es/interfaces/pix/main-domains-transactions): flujos y ciclo de vida de las transacciones
* [Dominios principales: QR Codes](/es/interfaces/pix/main-domains-qrcodes): generación de códigos QR estáticos y dinámicos
* [Referencia de API](/es/reference/interfaces/pix-btg/create-entry): documentación completa de la API para DICT, reclamaciones, transacciones, QR Codes y operaciones MED