El Plugin Pix Indirecto (BTG) se conecta a múltiples servicios de Lerian y proveedores externos para procesar pagos Pix. Configurarlo implica establecer la conexión del plugin a cada servicio y preparar los datos que esos servicios necesitan para operar. El plugin se ejecuta como dos capas principales — una Aplicación que expone la API de Pix y procesa la lógica de negocio, y un conjunto de Workers que manejan los webhooks entrantes de BTG, la entrega saliente de eventos 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 por servicio.

Requisitos previos

Antes de comenzar, asegúrate de tener:

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 proporciona las credenciales)

# El ISPB de su institución (8 dígitos)
PIX_ISPB=12345678

PIX_ISPB también se usa para detectar 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, sin dejar de reportarla a BACEN. Consulta Transferencias intra-PSP.

1. Licencia

El plugin es una solución empresarial y requiere una licencia válida para operar. Lerian proporciona la clave de licencia durante el onboarding.

# Clave de licencia proporcionada por Lerian
LICENSE_KEY=

# IDs de organización autorizados (separados por comas)
ORGANIZATION_IDS=

Documentación relacionada: Licencia de Lerian

2. Access Manager (opcional)

Access Manager gestiona la autenticación del plugin. Cuando está habilitado, valida todas las solicitudes entrantes antes de que lleguen a la API del plugin.

# Requerir autenticación para todas las solicitudes del plugin (true/false)
PLUGIN_AUTH_ENABLED=false

# URL del servicio Access Manager
PLUGIN_AUTH_ADDRESS=

Cuando PLUGIN_AUTH_ENABLED=true, el plugin valida el encabezado Authorization de cada solicitud para asegurar que:

El token pertenece a un usuario o aplicación autorizados
El token otorga acceso al endpoint y método de API solicitados

Solo necesitas proporcionar credenciales de cliente (CLIENT_ID / CLIENT_SECRET) para los servicios de Midaz, CRM y Fee si esos servicios también tienen habilitada la autenticación con Access Manager.

Documentación relacionada: Access Manager

3. Midaz

Midaz es el libro mayor central de todas las transacciones Pix que procesa el plugin. El plugin registra cada operación de cash-in, cash-out y reembolso en Midaz como una transacción de partida doble.

Conexión

# El ID de su organización en Midaz
MIDAZ_ORGANIZATION_ID=

# El ID de su ledger en Midaz
MIDAZ_LEDGER_ID=

# URL del módulo Transaction de Midaz
MIDAZ_TRANSACTION_URL=

# URL del módulo Onboarding de Midaz
MIDAZ_ONBOARDING_URL=

# Credenciales de la API de Midaz (requeridas si Midaz tiene la autenticación habilitada)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=

Requisitos de activos

Configura un activo en tu organización y libro mayor con estas propiedades:

Propiedad	Valor
Type	`currency`
Code	`BRL`

Vincula todas las cuentas a tu libro mayor usando el activo BRL. El plugin rechaza las operaciones sobre cuentas que no coincidan con 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 libro mayor que configuraste
Usar el activo BRL

Encabezado X-Account-Id

Muchas operaciones de Pix requieren el encabezado X-Account-Id para identificar qué cuenta realiza la acción. Este ID corresponde al ID de la cuenta del libro mayor 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 libro mayor
Qué datos del cliente obtener del CRM
Qué saldo validar y actualizar

Cómo usa el plugin el ID de cuenta

El plugin usa el ID de cuenta de manera diferente según el tipo de operación:

Tipo de flujo	Cómo usa el plugin el ID de cuenta
No transaccional (p. ej., crear claves o códigos QR)	Obtiene los datos del cliente y de la cuenta bancaria desde el CRM
Transaccional (p. ej., pagos, reembolsos)	Obtiene los datos del cliente para la iniciación del pago
	Valida los datos de la cuenta para la autorización de pagos entrantes
	Ejecuta la transacción en el libro mayor

Cumplimiento de cuentas

El plugin no aplica restricciones de cuenta a nivel de negocio, como cuentas bloqueadas o suspendidas. Tu aplicación es responsable de validar el estado de la cuenta antes de llamar al plugin. Para impedir las 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:

4. CRM

El CRM almacena 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 realizar operaciones de Pix. El plugin consulta los datos del CRM para:

Registrar y validar claves Pix
Construir los mensajes de pago para BACEN
Autorizar transacciones entrantes
Procesar los flujos de reembolso y disputa

Conexión

# URL base del CRM
PLUGIN_CRM_BASE_URL=

# Credenciales de la API del CRM (requeridas si el CRM tiene la autenticación habilitada)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=

Titulares

Los datos del titular representan al cliente que es dueño de la cuenta. Crea cada titular en el CRM antes de ejecutar cualquier operación de Pix para ese cliente.

Campos obligatorios

Campo	Requisito	Ejemplo
`name`	Máximo 120 caracteres	`Maria Silva Santos`
`document`	Para `NATURAL_PERSON`, un CPF con 11 dígitos; para `LEGAL_PERSON`, un CNPJ con 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`	Al asociar un nombre comercial con los datos de la clave
`addresses.primary`	Obligatorio para la creación de cobros con fecha de vencimiento

Documentación relacionada: Create a 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 el procesamiento de transacciones.

Campos obligatorios

Campo	Requisito	Ejemplo
`accountId`	ID de 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 (ver la tabla a continuación)	`CACC`
`bankingDetails.openingDate`	Formato YYYY-MM-DD	`2024-01-15`

El campo bankingDetails.branch debe contener exactamente 4 dígitos. Completa con ceros a la izquierda si es necesario. Por ejemplo, si el número de agencia es 1, regístralo como 0001. El plugin solo puede validar la cuenta en el CRM cuando el código de agencia sigue este formato.

Tipos de cuenta admitidos

Código	Descripción
`CACC`	Cuenta corriente
`SLRY`	Cuenta salario
`SVGS`	Cuenta de ahorros
`TRAN`	Cuenta transaccional

Documentación relacionada: Create an Alias Account

5. Proveedor BTG

BTG es el participante directo que conecta tu institución con la infraestructura Pix de BACEN. BTG proporciona las credenciales directamente cuando tu institución se registra para la integración indirecta con BACEN.

Conexión

# URL base de la API de BTG
BTG_BASE_URL=

# Credenciales de la API de BTG
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=

mTLS (seguridad de webhooks)

El TLS mutuo (mTLS) agrega una capa adicional de seguridad al validar el certificado de BTG en las solicitudes de webhook. Esto garantiza que los webhooks entrantes provengan genuinamente de BTG.

# Habilitar la validación mTLS (true/false)
# Use 'true' en producción, 'false' para desarrollo local
MTLS_ENABLED=false

# Cuánto tiempo almacenar en caché el certificado antes de actualizarlo
# Formato: duración de Go (p. ej., 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# Endpoint de BTG que provee el certificado público para la validación de firmas
BTG_CERTIFICATE_URL=

# Tiempo de espera para las solicitudes de obtención del certificado
# Formato: duración de Go (p. ej., 10s, 30s)
MTLS_HTTP_TIMEOUT=10s

Habilita siempre mTLS en los entornos de producción. Desactívalo únicamente durante el desarrollo local.

6. Servicio de tarifas (opcional)

Habilita el cálculo de tarifas para cobrar y distribuir automáticamente las tarifas sobre los pagos entrantes. Esto es opcional — si no lo configuras, el plugin procesa las transacciones sin cálculo de tarifas.

Conexión

# Método de cálculo de tarifas (actualmente solo se admite 'segment')
CASHIN_FEE_CALCULATION_TYPE=

# URL del servicio de tarifas
FEE_SERVICE_URL=

# Tiempo de espera de la solicitud en milisegundos
FEE_SERVICE_TIMEOUT=5000

# Credenciales de la API del servicio de tarifas (requeridas si el servicio de tarifas tiene la autenticación habilitada)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=

Cómo funciona

Cuando configuras CASHIN_FEE_CALCULATION_TYPE=segment, el plugin:

Recupera el segmento asociado a la cuenta receptora
Calcula las tarifas aplicables antes de procesar la transacción en Midaz
Distribuye el pago entrante según las reglas de paquete vinculadas a ese segmento

Pasos de configuración

Crea segmentos en Midaz — Define los segmentos de cuenta que determinan las reglas de tarifas
Configura paquetes en Fee Engine — Vincula cada segmento a sus reglas de cálculo de tarifas
Asigna segmentos a las cuentas — Crea o actualiza las cuentas de Midaz con el ID de segmento adecuado

Documentación relacionada:

7. Conciliación de DICT (VSync)

VSync concilia tus datos locales de DICT con BACEN procesando todos los eventos del día relacionados con claves. Esto garantiza que tu estado local se mantenga consistente con los registros autoritativos de BACEN.

# Ventana de bloqueo de escritura (formato de 24 horas, UTC)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Rango de red permitido para los servicios de conciliación
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 durante períodos de bajo tráfico.

El rango CIDR restringe qué redes pueden activar la conciliación. El plugin rechaza automáticamente las solicitudes provenientes de fuera de este rango.

Configuración de la caché de Redis

VSync usa Redis para cachear las entradas de BTG/DICT y los titulares del CRM durante la conciliación. En los despliegues con Helm, el valor por defecto de REDIS_HOST apunta al sidecar Valkey integrado, por lo que no se requiere configuración adicional para una instalación estándar.

# Conexión (siempre se usa)
REDIS_HOST=<release>-valkey:6379
REDIS_MASTER_NAME=
REDIS_DB=0
REDIS_PROTOCOL=3

# Pool de conexiones y reintentos (siempre se usa)
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

# Autenticación (opcional — solo se usa si se define)
REDIS_PASSWORD=

# TLS (opcional — solo se usa si REDIS_TLS=true)
REDIS_TLS=false
REDIS_CA_CERT=

# Autenticación GCP IAM (opcional — solo se usa si 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

# TTLs de la caché de VSync (siempre se usa)
CACHE_BTG_ENTRY_TTL=30m
CACHE_CRM_HOLDER_TTL=30m

En los despliegues con Helm, el valor por defecto de REDIS_HOST apunta al sidecar Valkey integrado (<release-name>-valkey:6379) — no se necesita configuración adicional de Redis a menos que te conectes a una instancia externa.

Conexión (siempre se usa)

Var	Tipo	Valor por defecto	Descripción
`REDIS_HOST`	string (host:port, CSV)	`<release>-valkey:6379` (chart de Helm)	Dirección(es) de Redis. El valor por defecto apunta al Valkey integrado (`<release-name>-valkey:6379`). Múltiples direcciones separadas por coma definen una topología Sentinel/Cluster.
`REDIS_MASTER_NAME`	string	`""`	Nombre del master de Sentinel. Vacío = standalone (conexión directa).
`REDIS_DB`	int	`0`	Número de 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	Valor por defecto	Descripción
`REDIS_POOL_SIZE`	int	`10`	Cantidad máxima de conexiones en el pool.
`REDIS_MIN_IDLE_CONNS`	int	`0`	Cantidad mínima de conexiones inactivas mantenidas listas.
`REDIS_READ_TIMEOUT`	int (segundos)	`3`	Timeout de las operaciones de lectura.
`REDIS_WRITE_TIMEOUT`	int (segundos)	`3`	Timeout de las operaciones 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`	Cantidad máxima de reintentos para un comando fallido.
`REDIS_MIN_RETRY_BACKOFF`	int (milisegundos)	`8`	Retraso mínimo entre reintentos.
`REDIS_MAX_RETRY_BACKOFF`	int (segundos)	`512`	Retraso máximo entre reintentos. Nota: se almacena en segundos en el código (unidad distinta a la del mínimo).

Autenticación (opcional — solo se usa si se define)

Var	Tipo	Valor por defecto	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	Valor por defecto	Descripción
`REDIS_TLS`	bool	`false`	Habilita TLS. Obligatorio `true` en `DEPLOYMENT_MODE=saas` (validado al arrancar).
`REDIS_CA_CERT`	string (PEM base64)	`""`	Certificado CA (base64) para validar el servidor cuando TLS está activo.

Autenticación GCP IAM (opcional — solo se usa si `REDIS_USE_GCP_IAM=true`)

Var	Tipo	Valor por defecto	Descripción
`REDIS_USE_GCP_IAM`	bool	`false`	Habilita la autenticación GCP IAM (Memorystore) en lugar de 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 (leída mediante CredentialsBase64FromEnvValue) para generar el token.
`REDIS_TOKEN_LIFETIME`	int (minutos)	`60`	Tiempo de vida del token IAM generado.
`REDIS_TOKEN_REFRESH_DURATION`	int (minutos)	`45`	Intervalo de renovación del token (debe ser menor que el tiempo de vida).

TTLs de la caché de VSync (siempre se usa)

Var	Tipo	Valor por defecto	Descripción
`CACHE_BTG_ENTRY_TTL`	Go duration	`30m`	TTL de la caché para las entradas de BTG/DICT en Redis. Un valor negativo revierte al valor por defecto.
`CACHE_CRM_HOLDER_TTL`	Go duration	`30m`	TTL de la caché para los titulares del CRM en Redis. Un valor negativo revierte al valor por defecto.

8. Seguridad de webhooks internos

El plugin usa un canal de comunicación interno entre los servicios Worker y Aplicación. Las firmas HMAC-SHA256 aseguran este canal para prevenir manipulaciones y ataques de repetición.

# Secreto compartido para firmar las solicitudes internas (Worker -> Application)
# Debe tener al menos 32 caracteres
# Genere uno con: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validar las firmas de los webhooks internos entrantes (true/false)
# Use siempre 'true' en producción
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Antigüedad máxima (en segundos) de las marcas de tiempo de las solicitudes antes de rechazarlas
# Predeterminado: 300 (5 minutos)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300

Usa exactamente el mismo valor de INTERNAL_WEBHOOK_SECRET en ambos 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, cada una encargada de una parte distinta del ciclo de vida de Pix. Todos los workers se ejecutan como servicios separados junto a la aplicación principal.

Worker entrante

El worker entrante recibe las notificaciones de webhook de BTG y las reenvía a tu aplicación para su procesamiento.

# URL donde la aplicación recibe los webhooks internos
WEBHOOK_INBOUND_BASE_URL=

# Secreto compartido para firmar las solicitudes (debe coincidir con el INTERNAL_WEBHOOK_SECRET de la aplicación)
INTERNAL_WEBHOOK_SECRET=

Worker saliente

El worker saliente envía notificaciones de eventos desde el plugin a tu aplicación mediante webhooks. Así es como tu sistema se mantiene informado sobre los eventos de Pix (transferencias, reembolsos, reclamos, disputas).

Prioridad de resolución de URL

El plugin resuelve las URL de webhook en este orden, usando la primera coincidencia:

URL de entidad — Una URL específica del tipo de evento (p. ej., WEBHOOK_DICT_CLAIM_URL)
URL de flujo — Una URL para la categoría más amplia (p. ej., WEBHOOK_DICT_URL)
URL por defecto — La URL de respaldo (WEBHOOK_DEFAULT_URL)

# URL de reserva predeterminada
WEBHOOK_DEFAULT_URL=

# Eventos relacionados con DICT
WEBHOOK_DICT_URL=
WEBHOOK_DICT_CLAIM_URL=
WEBHOOK_DICT_INFRACTION_REPORT_URL=
WEBHOOK_DICT_REFUND_URL=

# Eventos de Recuperación de Fondos MED 2.0 (flujo DICT)
# Estos se enrutan bajo el flujo DICT y recurren a WEBHOOK_DICT_URL,
# y luego a WEBHOOK_DEFAULT_URL, si no se define una URL específica de la entidad.
WEBHOOK_DICT_FUNDS_RECOVERY_URL=
WEBHOOK_DICT_FUNDS_RECOVERY_EVENT_URL=

# Eventos de devolución
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Eventos de transferencia
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=

Puedes empezar con solo WEBHOOK_DEFAULT_URL para recibir todos los eventos en un único endpoint, y luego dividirlos gradualmente en URL específicas por entidad a medida que tu sistema evoluciona.

Para profundizar en los tipos de eventos de webhook, los payloads, el comportamiento de reintentos y las mejores prácticas, consulta la guía de Webhooks.

Worker de conciliación

El worker de conciliación necesita las mismas credenciales que la capa de Aplicación para estos servicios:

CRM — URL y credenciales
BTG — URL y credenciales
Midaz — ID de organización

Consulta las secciones correspondientes anteriores para conocer los detalles de cada configuración. Puedes restringir cuándo opera el worker configurando una ventana de tiempo específica. Esto es especialmente útil para programar las tareas de conciliación durante las horas de menor actividad. El plugin admite ventanas de tiempo que cruzan la medianoche.

# Hora de inicio en formato HH:MM (24 horas). Ejemplo: "23:00" para las 11 PM
RECONCILIATION_START_TIME=

# Hora de fin en formato HH:MM (24 horas). Ejemplo: "05:00" para las 5 AM
RECONCILIATION_END_TIME=

Si dejas ambos campos vacíos, el worker se ejecuta sin restricciones de tiempo — 24/7.

La ventana operativa de conciliación está anclada a la zona horaria America/Sao_Paulo. En imágenes de contenedor minimal/distroless que se distribuyen sin datos de zona horaria, el runtime recurre a UTC y la ventana configurada puede desfasarse hasta 3 horas respecto al bloqueo de escritura de DICT. Configura TZ=America/Sao_Paulo (y asegúrate de que tzdata esté disponible) en el contenedor del worker de conciliación para mantener la ventana alineada con BACEN.

Los endpoints de cashout y reembolso de PIX Indirecto admiten idempotencia mediante el encabezado de solicitud X-Idempotency, con un TTL configurable a través de X-TTL. Para conocer las estrategias de reintento y los detalles de implementación, consulta Reintentos e idempotencia.

10. Observabilidad (OpenTelemetry)

El plugin incluye instrumentación completa de OpenTelemetry (trazas, métricas y logs) en las capas de Aplicación y Worker. Cada flujo de Pix se traza de extremo a extremo — transferencias (cash-in y cash-out), reembolsos, webhooks entrantes y salientes, conciliación de DICT y liquidación intra-PSP — para que puedas seguir un único pago a través del plugin y de las llamadas a Midaz, CRM y BTG. La telemetría está desactivada por defecto. Habilítala y apunta el exportador OTLP a tu collector:

# Interruptor principal — la telemetría está desactivada hasta que esto sea true
ENABLE_TELEMETRY=true

# Atributos de recurso que identifican este servicio en su 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}

# Endpoint del collector OTLP (gRPC, puerto predeterminado 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. Configura las mismas variables de OTel en la Aplicación y en cada Worker para que las trazas se correlacionen entre los servicios.

Exportador: gRPC y TLS

El plugin exporta trazas, métricas y logs mediante 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 automáticamente
`collector:4317` (`host:port` sin esquema)	gRPC, texto plano	Inseguro — se infiere automáticamente

Los exportadores inseguros (texto plano) se rechazan fuera de los entornos de desarrollo. En staging o producción, usa un endpoint https://, o reconoce explícitamente el riesgo mediante la autorización de OTEL inseguro de lib-commons únicamente cuando controles 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:

# Local / desarrollo (gRPC en texto plano)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Producción (gRPC con TLS)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4317

El collector luego distribuye la telemetría a tus backends de trazas, métricas y logs.

11. Salud y disponibilidad

La Aplicación y los Workers exponen una sonda de disponibilidad en /readyz (junto a las verificaciones estándar de liveness). Apunta la sonda de disponibilidad 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 encabezado opcional X-Purpose que identifica el propósito de la transacción, usado para las transferencias de reembolso de MED 2.0. Cuando se omite, su valor por defecto es TRANSFER.

# Ejemplo: una transferencia de devolución MED 2.0
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 para más detalles.

Próximos pasos

Con el plugin completamente configurado, estás listo para empezar a operar Pix. Explora estos temas para profundizar:

Webhooks — Tipos de eventos, payloads, reintentos y mejores prácticas
MED 2.0 — Recuperación de fondos — Recuperación de fraude entre cuentas y el encabezado X-Purpose
Operaciones de reembolso — Reembolsos parciales distribuidos y desbloqueo
Transferencias intra-PSP — Liquidación P2P interna y reporte TRCK002
Dominios principales: DICT — Comprensión de la gestión de claves Pix
Dominios principales: transacciones — Flujos y ciclo de vida de las transacciones
Dominios principales: códigos QR — Generación de códigos QR estáticos y dinámicos
Referencia de API — Documentación completa de la API para operaciones de DICT, Reclamos, Transacciones, Códigos QR y MED

​Requisitos previos

​1. Licencia

​2. Access Manager (opcional)

​3. Midaz

​Conexión

​Requisitos de activos

​Configuración de cuentas

​Encabezado X-Account-Id

​Cómo usa el plugin el ID de cuenta

​Cumplimiento de cuentas

​4. CRM

​Conexión

​Titulares

​Campos obligatorios

​Campos opcionales

​Cuentas alias

​Campos obligatorios

​Tipos de cuenta admitidos

​5. Proveedor BTG

​Conexión

​mTLS (seguridad de webhooks)

​6. Servicio de tarifas (opcional)

​Conexión

​Cómo funciona

​Pasos de configuración

​7. Conciliación de DICT (VSync)

​Configuración de la caché de Redis

​Conexión (siempre se usa)

​Pool de conexiones y reintentos (siempre se usa)

​Autenticación (opcional — solo se usa si se define)

​TLS (opcional — solo se usa si REDIS_TLS=true)

​Autenticación GCP IAM (opcional — solo se usa si REDIS_USE_GCP_IAM=true)

​TTLs de la caché de VSync (siempre se usa)

​8. Seguridad de webhooks internos

​9. Capas de workers

​Worker entrante

​Worker saliente

​Prioridad de resolución de URL

​Worker de conciliación

​10. Observabilidad (OpenTelemetry)

​Exportador: gRPC y TLS

​Ejemplo: endpoint del collector

​11. Salud y disponibilidad

​Propósito de la transferencia (MED 2.0)

​Próximos pasos

Requisitos previos

1. Licencia

2. Access Manager (opcional)

3. Midaz

Conexión

Requisitos de activos

Configuración de cuentas

Encabezado X-Account-Id

Cómo usa el plugin el ID de cuenta

Cumplimiento de cuentas

4. CRM

Conexión

Titulares

Campos obligatorios

Campos opcionales

Cuentas alias

Campos obligatorios

Tipos de cuenta admitidos

5. Proveedor BTG

Conexión

mTLS (seguridad de webhooks)

6. Servicio de tarifas (opcional)

Conexión

Cómo funciona

Pasos de configuración

7. Conciliación de DICT (VSync)

Configuración de la caché de Redis

Conexión (siempre se usa)

Pool de conexiones y reintentos (siempre se usa)

Autenticación (opcional — solo se usa si se define)

TLS (opcional — solo se usa si `REDIS_TLS=true`)

Autenticación GCP IAM (opcional — solo se usa si `REDIS_USE_GCP_IAM=true`)

TTLs de la caché de VSync (siempre se usa)

8. Seguridad de webhooks internos

9. Capas de workers

Worker entrante

Worker saliente

Prioridad de resolución de URL

Worker de conciliación

10. Observabilidad (OpenTelemetry)

Exportador: gRPC y TLS

Ejemplo: endpoint del collector

11. Salud y disponibilidad

Propósito de la transferencia (MED 2.0)

Próximos pasos