> ## 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 do Pix Direto via JD

> CloudEvents emitidos pela integração Pix Direto via JD para os ciclos de transações, chaves DICT e Pix Automático.

A integração Pix Direto via JD emite 21 fatos de negócio em JSON como CloudEvents 1.0 no modo de conteúdo binário sobre Kafka. O streaming é opcional. Quando habilitado, a integração grava o estado de negócio e o envelope do evento no outbox do PostgreSQL na mesma transação; o relay do outbox é o único publicador no broker.

## Contrato de transporte

| Campo                | Valor                                       |
| -------------------- | ------------------------------------------- |
| `ce-source`          | `plugin-br-pix-jd`                          |
| Tópico               | `lerian.streaming.plugin-br-pix-jd`         |
| Versão do schema     | `1.0.0` para todos os eventos               |
| Tipo de conteúdo     | `application/json`                          |
| Entrega              | Pelo menos uma vez pelo outbox transacional |
| Tópico de comandos   | Nenhum                                      |
| Manifesto em runtime | Não exposto                                 |

Configure `STREAMING_ENABLED=true` e `OUTBOX_ENABLED=true` juntos. Se você definir `STREAMING_CLOUDEVENTS_SOURCE`, o valor deve ser exatamente `plugin-br-pix-jd`. Quando o streaming está desabilitado, a integração não grava eventos de ciclo de vida no outbox de streaming.

<Warning>
  Esta integração ainda não expõe um endpoint de manifesto de streaming. O catálogo do bootstrap contém apenas a definição estrutural `transaction.created`, enquanto os caminhos de emissão em produção publicam os 21 fatos abaixo. Use esta página—e não o catálogo incompleto do runtime—como o inventário atual de eventos.
</Warning>

Faça a deduplicação por `(ce-source, ce-id)` e mantenha os consumidores idempotentes. A integração não provisiona um tópico de comandos.

## Catálogo de eventos

Cada `ce-type` usa `studio.lerian.plugin-br-pix-jd.<event-key>`.

### Transações

| Chave do evento        | Quando é emitido                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `transaction.created`  | Um cash-out externo é persistido como pendente, o lançamento pendente existe no Midaz e o envio ao JDPI é concluído com sucesso. |
| `transaction.executed` | Uma transferência interna é concluída de forma síncrona, um cash-in é aplicado ou a conciliação liquida um cash-out externo.     |
| `transaction.refunded` | A transação de devolução é persistida e vinculada à transação original.                                                          |
| `transaction.failed`   | A conciliação move um cash-out externo pendente para o estado terminal de erro e cancela o lançamento pendente.                  |

### Chaves e reivindicações DICT

| Chave do evento            | Quando é emitido                                                                  |
| -------------------------- | --------------------------------------------------------------------------------- |
| `key.registered`           | Uma chave é registrada no DICT e persistida como ativa.                           |
| `key.validation-requested` | A integração armazena e envia um desafio de validação de titularidade.            |
| `key.confirmed`            | O desafio enviado é verificado e a chave sai do estado de espera por confirmação. |
| `key.deleted`              | Uma chave é excluída no DICT e removida logicamente na base local.                |
| `key.claimed`              | Uma reivindicação é aberta no DICT e seu identificador é persistido.              |
| `key.claim-confirmed`      | O doador confirma a reivindicação.                                                |
| `key.claim-concluded`      | O reivindicante conclui a reivindicação.                                          |
| `key.claim-cancelled`      | A reivindicação é cancelada.                                                      |

### Autorizações do Pix Automático

| Chave do evento           | Quando é emitido                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------- |
| `authorization.requested` | O PSP recebedor solicita uma autorização e a integração a persiste como solicitada. |
| `authorization.accepted`  | O pagador aceita a autorização.                                                     |
| `authorization.rejected`  | A autorização passa para o estado rejeitado.                                        |
| `authorization.activated` | A autorização é confirmada com sucesso e passa para o estado ativo.                 |
| `authorization.cancelled` | A autorização é cancelada e removida logicamente.                                   |

### Agendamentos do Pix Automático

| Chave do evento      | Quando é emitido                                                                   |
| -------------------- | ---------------------------------------------------------------------------------- |
| `schedule.requested` | O PSP recebedor solicita um agendamento e a integração o persiste como solicitado. |
| `schedule.accepted`  | O agendamento passa para o estado aceito.                                          |
| `schedule.rejected`  | O agendamento passa para o estado rejeitado.                                       |
| `schedule.cancelled` | O agendamento é cancelado e removido logicamente.                                  |

## Contratos de payload

Todos os timestamps são strings RFC 3339 em UTC. Os valores monetários de transações e Pix Automático são centavos inteiros, não strings decimais nem números de ponto flutuante. Os campos marcados com `?` podem ser omitidos.

<Warning>
  O contrato no wire codifica `amount`, `value` e `payerMaxValue` como tokens numéricos JSON `int64`. Consumidores JavaScript que aceitam todo o intervalo de `int64` devem usar um parser JSON sem perda e compatível com BigInt ou rejeitar valores acima de `Number.MAX_SAFE_INTEGER`; o `JSON.parse` pode arredondar inteiros maiores.
</Warning>

```typescript theme={null}
interface TransactionEventData {
  id: string
  jdpiRequestId?: string
  indirectId?: string
  endToEndId?: string
  status: string
  flow: number
  type: number
  amount: number // int64 em centavos
  accountId: string
  isRefund: boolean
  isInternal: boolean
  refundType?: number
  refundAccountId?: string
  refundEndToEndId?: string
  refundCode?: string
  createdAt: string
  updatedAt: string
}

interface KeyEventData {
  id: string
  key: string
  accountId: string
  status: number
  keyType: number
  claimId?: string
  claimType?: number
  createdAt: string
  updatedAt: string
}

interface AuthorizationEventData {
  id: string
  idRecorrencia: string
  idReqJdPi?: string
  idCancelamento?: string
  tenantId?: string
  status: number
  frequency: number
  value?: number // int64 em centavos
  payerMaxValue?: number // int64 em centavos
  recipientIspb?: string
  recipientCnpj?: string
  payerCpfCnpj?: string
  contractNumber?: string
  createdAt: string
  updatedAt: string
}

interface ScheduleEventData {
  id: string
  endToEndId: string
  idRecorrencia: string
  idConciliacaoRecebedor?: string
  idCancelamento?: string
  tenantId?: string
  status: number
  finalidadeAgendamento: number
  dtVencimento?: string
  value?: number // int64 em centavos
  recipientIspb?: string
  recipientCnpj?: string
  payerCpfCnpj?: string
  createdAt: string
  updatedAt: string
}
```