> ## 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 la conectividad con Midaz, CRM, BTG y la configuración de los workers.

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)

```bash theme={null}
# El ISPB de su institución (8 dígitos)
PIX_ISPB=12345678
```

<Note>
  `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](/es/midaz/plugins/pix/indirect/indirect-pix-intra-psp).
</Note>

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

```bash theme={null}
# Clave de licencia proporcionada por Lerian
LICENSE_KEY=

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

**Documentación relacionada:** [Licencia de Lerian](/es/reference/lerians-license)

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

```bash theme={null}
# 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

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

**Documentación relacionada:** [Access Manager](/es/platform/access-manager/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

***

```bash theme={null}
# 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:**

* [Update an Account](/es/reference/midaz/update-an-account)
* [Update a Balance](/es/reference/midaz/update-a-balance)

# 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

***

```bash theme={null}
# 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](/es/reference/midaz/crm/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 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`                           |

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

### 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](/es/reference/midaz/crm/create-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

***

```bash theme={null}
# 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.

```bash theme={null}
# 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
```

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

# 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

***

```bash theme={null}
# 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:

1. **Recupera el segmento** asociado a la cuenta receptora
2. **Calcula las tarifas 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 tarifas
2. **Configura paquetes en Fee Engine** — Vincula cada segmento a sus reglas de cálculo de tarifas
3. **Asigna segmentos a las cuentas** — Crea o actualiza las cuentas de Midaz con el ID de segmento adecuado

**Documentación relacionada:**

* [Fee Engine - Guides](/es/midaz/plugins/fees-engine/fees-engine-overview)
* [Fee Engine - APIs](/es/reference/midaz/plugins/fees-engine/create-package)

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

```bash theme={null}
# 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=
```

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

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

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

```bash theme={null}
# 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
```

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

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

```bash theme={null}
# 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
```

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

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

```bash theme={null}
# 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:

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

```bash theme={null}
# 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=
```

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

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](/es/midaz/plugins/pix/indirect/indirect-pix-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.

```bash theme={null}
# 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=
```

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

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

<Note>
  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](/es/reference/retries-idempotency).
</Note>

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

```bash theme={null}
# 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}
```

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

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

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

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

```bash theme={null}
# 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](/es/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery) 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](/es/midaz/plugins/pix/indirect/indirect-pix-webhooks) — Tipos de eventos, payloads, reintentos y mejores prácticas
* [MED 2.0 — Recuperación de fondos](/es/midaz/plugins/pix/indirect/indirect-pix-med-2-funds-recovery) — Recuperación de fraude entre cuentas y el encabezado X-Purpose
* [Operaciones de reembolso](/es/midaz/plugins/pix/indirect/indirect-pix-refund-operations) — Reembolsos parciales distribuidos y desbloqueo
* [Transferencias intra-PSP](/es/midaz/plugins/pix/indirect/indirect-pix-intra-psp) — Liquidación P2P interna y reporte TRCK002
* [Dominios principales: DICT](/es/midaz/plugins/pix/main-domains-dict) — Comprensión de la gestión de claves Pix
* [Dominios principales: transacciones](/es/midaz/plugins/pix/main-domains-transactions) — Flujos y ciclo de vida de las transacciones
* [Dominios principales: códigos QR](/es/midaz/plugins/pix/main-domains-qrcodes) — Generación de códigos QR estáticos y dinámicos
* [Referencia de API](/es/reference/midaz/plugins/indirect-pix/create-entry) — Documentación completa de la API para operaciones de DICT, Reclamos, Transacciones, Códigos QR y MED