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

# Eventos de Pix Indirect via BTG

> CloudEvents que Pix Indirect via BTG publica para cobranzas, claves y reclamaciones DICT, disputas MED, recuperación de fondos, pagos, programaciones y Pix Automático.

Pix Indirect via BTG publica 63 hechos de negocio JSON como CloudEvents 1.0 en modo de contenido binario sobre Kafka. Estos eventos están disponibles en despliegues BYOC. El streaming es opcional y está desactivado por defecto. Para activarlo, define `STREAMING_ENABLED=true` y las demás [variables de eventos de negocio](https://docs.lerian.studio/es/interfaces/pix-btg/indirect-pix-environment-variables.md#business-events) en el componente de la API. La [visión general del streaming de eventos](https://docs.lerian.studio/es/reference/events/overview.md) describe el envelope común.

## Contrato de transporte

| Campo | Valor |
| - | - |
| `ce-source` | El valor de `STREAMING_CLOUDEVENTS_SOURCE`. El valor predeterminado es `plugin-br-pix-indirect-btg`. |
| Tema | `lerian.streaming.<ce-source>` |
| `ce-type` | `studio.lerian.<ce-source>.<event-key>` |
| `ce-tenantid` | El valor de `STREAMING_TENANT_ID`. El valor predeterminado es `default`. |
| Versión del esquema | `1.0.0` para cada evento |
| Tipo de contenido | `application/json` |
| Entrega | Definida por evento. Consulta [Entrega](#delivery). |
| Tema de comandos | Ninguno |
| Manifest en tiempo de ejecución | `GET /v1/streaming/manifest` |

Si cambias `STREAMING_CLOUDEVENTS_SOURCE`, el tema y cada `ce-type` cambian con él. Cuando el streaming está activado, la API sirve el catálogo de eventos en `GET /v1/streaming/manifest`. La ruta requiere el recurso `streaming` del Access Manager con la acción `get`.

## Entrega

Cada evento tiene uno de estos tres modos de entrega:

* **Outbox**: la API escribe el evento en su outbox de PostgreSQL, y un relay lo publica en Kafka.
* **Directa, con fallback al outbox**: la API publica el evento en Kafka. Si los brokers no están disponibles o responden lento, la API escribe el evento en el outbox.
* **Mejor esfuerzo**: la API publica el evento en Kafka, sin outbox.

Publicar un evento nunca hace fallar la operación de negocio que lo produjo. Un evento puede llegar más de una vez: deduplica según `(ce-source, ce-id)` y mantén los consumidores idempotentes. No dependas del orden de llegada.

## Catálogo de eventos

### Cobranzas

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `collection.created` | BTG registra una cobranza Pix, y la API la guarda como `ACTIVE`. Se dispara para cobranzas inmediatas y con vencimiento. El campo `type` las distingue. | Directa, con fallback al outbox |
| `collection.updated` | BTG acepta un cambio en una cobranza `ACTIVE`, y la API guarda la cobranza con una nueva revisión. | Directa, con fallback al outbox |
| `collection.deleted` | BTG acepta la eliminación de una cobranza inmediata `ACTIVE`, y la API la guarda como `DELETED`. | Directa, con fallback al outbox |
| `collection.completed` | Una cobranza pasa de `ACTIVE` a `COMPLETED`: su pago se liquida, o el endpoint de operador la completa. | Outbox |

### Claves DICT y reclamaciones

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `dict_entry.created` | Una clave Pix se guarda como `ACTIVE` para una de tus cuentas: por la API, por la conciliación, o cuando una reclamación se completa a tu favor. | Directa, con fallback al outbox |
| `dict_entry.updated` | El DICT acepta un cambio en los datos de la cuenta o del dueño de una clave, y la API lo guarda. | Directa, con fallback al outbox |
| `dict_entry.deleted` | Una clave sale de tu cuenta: la eliminas, la conciliación la quita, o el donante confirma una reclamación sobre ella. | Directa, con fallback al outbox |
| `claim.created` | Existe una reclamación de portabilidad o de titularidad para una clave: la abres como reclamante, o BTG informa una reclamación que otro participante abrió sobre tu clave. | Outbox |
| `claim.acknowledged` | El donante da acuse de la reclamación, y la reclamación pasa a `WAITING_RESOLUTION`. | Directa, con fallback al outbox |
| `claim.confirmed` | El donante confirma la reclamación. | Outbox |
| `claim.completed` | La reclamación llega a `COMPLETED`, y la clave pertenece al reclamante en el DICT. | Outbox |
| `claim.cancelled` | La reclamación llega a `CANCELLED`, y la clave queda con el donante. | Outbox |

### Recuperación de fondos de MED 2.0

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `funds_recovery.created` | Existe una recuperación de fondos: la creas, o BTG informa una que la API no tenía. | Outbox |
| `funds_recovery.tracked` | La recuperación de fondos pasa a `TRACKED`, y su grafo de rastreo está disponible. | Directa, con fallback al outbox |
| `funds_recovery.awaiting_analysis` | La recuperación de fondos pasa a `AWAITING_ANALYSIS`. | Outbox |
| `funds_recovery.analysed` | La recuperación de fondos pasa a `ANALYSED`. | Outbox |
| `funds_recovery.refund_requested` | La recuperación de fondos pasa a `REFUNDING`. | Outbox |
| `funds_recovery.completed` | BTG informa la recuperación de fondos como `COMPLETED`. | Outbox |
| `funds_recovery.cancelled` | La recuperación de fondos pasa a `CANCELLED`. | Outbox |

### Informes de infracción y solicitudes de devolución de MED

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `infraction.created` | Existe un informe de infracción: lo abres, o BTG entrega uno que una contraparte abrió contra tu cliente. | Outbox |
| `infraction.acknowledged` | Un informe de infracción pasa de `OPEN` a `ACKNOWLEDGED`. | Directa, con fallback al outbox |
| `infraction.closed` | Un informe de infracción llega a `CLOSED` con su resultado de análisis. | Outbox |
| `infraction.cancelled` | Un informe de infracción llega a `CANCELLED`. | Outbox |
| `refund_request.created` | Existe una solicitud de devolución de MED: la creas, o BTG entrega una que creó una contraparte. | Outbox |
| `refund_request.closed` | Una solicitud de devolución llega a `CLOSED` con su resultado y el monto devuelto. | Outbox |
| `refund_request.cancelled` | Una solicitud de devolución llega a `CANCELLED`. | Outbox |

### Cash-in y devoluciones

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `cashin.received` | La API acepta un Pix entrante y lo guarda como `CREATED`. Ningún crédito ocurre en este paso. | Directa, con fallback al outbox |
| `cashin.completed` | Un Pix entrante se liquida, y la API lo acredita en la cuenta en Midaz. | Outbox |
| `cashin.failed` | BTG informa un error para un Pix entrante aceptado, y la API lo guarda como `REJECTED`. No se acredita nada. | Outbox |
| `refund.created` | Existe una devolución para una de tus cuentas. El campo `type` (`CASHOUT` o `CASHIN`) da su dirección. | Directa, con fallback al outbox |
| `refund.processing` | Una devolución que envías (`CASHOUT`) pasa a `PROCESSING`. | Directa, con fallback al outbox |
| `refund.completed` | Una devolución se liquida y pasa a `COMPLETED`. | Outbox |
| `refund.rejected` | BTG o la liquidación intra-PSP rechaza una devolución en curso, y la API la guarda como `REJECTED`. | Outbox |
| `refund.failed` | Una devolución que envías (`CASHOUT`) no se puede ejecutar, y la API la guarda como `FAILED`. | Outbox |

### Cash-out, iniciación de pago y programaciones

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `payment_initiation.created` | Una iniciación de pago (`MANUAL`, `KEY` o `QR_CODE`) pasa la validación, y la API la guarda como `PENDING`. | Directa, con fallback al outbox |
| `cashout.created` | La API guarda un cash-out como `CREATED`. | Directa, con fallback al outbox |
| `cashout.processing` | El proveedor acepta el cash-out, y la API lo guarda como `PROCESSING`. | Directa, con fallback al outbox |
| `cashout.completed` | El cash-out se liquida, y la API lo guarda como `COMPLETED`. | Outbox |
| `cashout.rejected` | BTG o la liquidación intra-PSP rechaza un cash-out que llegó al proveedor, y la API lo guarda como `REJECTED`. | Outbox |
| `cashout.failed` | El cash-out falla antes de que el proveedor lo acepte, y la API lo guarda como `FAILED`. | Outbox |
| `schedule.created` | La API guarda un Pix programado como `SCHEDULED`. | Directa, con fallback al outbox |
| `schedule.cancelled` | Se cancela una programación `SCHEDULED`. | Directa, con fallback al outbox |
| `schedule.attempt_failed` | Un intento falla por saldo insuficiente, y la programación espera un nuevo intento el mismo día. | Mejor esfuerzo |
| `schedule.executed` | Un Pix programado se ejecuta y se liquida. | Outbox |
| `schedule.failed` | Un Pix programado llega a `FAILED` después de su último intento. | Outbox |

### Autorizaciones de Pix Automático

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `authorization_request.created` | La API guarda una solicitud de autorización para una cuenta pagadora: BTG la entrega, o confirmas un código QR de Pix Automático para el pagador. | Directa, con fallback al outbox |
| `authorization_request.approved` | BTG da acuse de la aprobación del pagador, y la solicitud pasa a `APPROVING`. El mandato no existe en este paso. | Directa, con fallback al outbox |
| `authorization_request.confirmed` | BTG confirma la aprobación, y la solicitud llega a `CONFIRMED`. | Outbox |
| `authorization_request.rejected` | La solicitud llega a `REJECTED`: el pagador la rechaza, o BTG informa un rechazo. | Outbox |
| `authorization_request.cancelled` | BTG informa la cancelación de una solicitud antes de su confirmación. | Outbox |
| `authorization_request.expired` | La solicitud llega a `EXPIRED` sin una decisión. | Outbox |
| `authorization_request.reply_failed` | La API no puede entregar la decisión del pagador a BTG, y la solicitud llega a `REPLY_FAILED`. | Directa, con fallback al outbox |
| `authorization_request.payment_failed` | El Pix inmediato de una solicitud de pay-and-confirm no se liquida, y la solicitud llega a `PAYMENT_FAILED`. No se crea ningún mandato. | Outbox |
| `recurring_authorization.authorized` | Un mandato de Pix Automático entra en vigor para una cuenta pagadora. | Outbox |
| `recurring_authorization.cancelled` | Se cancela un mandato por la API, y sus cobros programados futuros se cancelan con él. | Outbox |
| `recurrence.completed` | Se ejecuta el último cobro permitido de una recurrencia, y la recurrencia termina. | Outbox |
| `recurrence.expired` | Una recurrencia llega a su fecha final, y termina. | Outbox |

### Cobros de Pix Automático

| Clave del evento | Se dispara cuando | Entrega |
| - | - | - |
| `recurring_charge.received` | Un cobro de Pix Automático llega desde BTG, y la API lo guarda como `RECEIVED`. | Directa, con fallback al outbox |
| `recurring_charge.scheduled` | La API programa un intento de débito para un cobro: el cobro pasa las verificaciones de aceptación, o un intento fallido tiene reintentos restantes. | Directa, con fallback al outbox |
| `recurring_charge.rejected` | Las verificaciones de aceptación rechazan un cobro recibido. No se debita al pagador. | Outbox |
| `recurring_charge.executed` | Se debita al pagador por un cobro. | Outbox |
| `recurring_charge.failed` | El último intento de débito permitido falla. No se debita al pagador. | Outbox |
| `recurring_charge.cancelled` | Se cancela un cobro programado: se cancela su mandato, o se cancela su programación. | Directa, con fallback al outbox |


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