# Documentação Completa de Webhooks (LURI v2)

Webhooks (HTTP Callbacks) são notificações automáticas enviadas via `HTTP POST` pela plataforma **LURI** para uma URL pública configurada no seu marketplace sempre que ocorre um evento no ciclo de vida de uma cobrança (Boleto Bancário, Boleto Híbrido ou Pix) ou de credenciais de segurança (Chaves Públicas RSA).

---

## 1. Requisitos e Boas Práticas de Integração

1. **Canal Seguro Obrigatório (HTTPS / TLS 1.2+):** A URL de destino deve utilizar obrigatoriamente o protocolo `https://` na porta padrão `443` e possuir certificado SSL/TLS válido. Endereços locais (`localhost`), IPs privados (RFC 1918) ou portas não-padrão são bloqueados contra SSRF.
2. **Confirmação Rápida (`HTTP 2xx`) e Processamento Assíncrono:** Seu endpoint deve responder com um código HTTP de sucesso (`200` a `299`) em até **10 segundos**. Recomendamos que sua aplicação valide a assinatura, enfileire a mensagem internamente e retorne `200 OK` imediatamente.
3. **Política de Retentativas (Retry):** Caso o servidor de destino não responda dentro do timeout (5s de conexão / 10s total) ou retorne erro HTTP (`4xx` ou `5xx`), a LURI realizará até **3 tentativas de entrega** automáticas.
4. **Idempotência:** Utilize o identificador único do evento (`id`) ou a combinação (`payload.boleto_id` + `type`) para garantir que seu sistema processe cada transição de estado apenas uma vez.

---

## 2. Gerenciamento de Webhooks via API (`/v2/webhooks`)

Você pode gerenciar a URL de recebimento e a chave de assinatura diretamente via API utilizando **Basic Auth** ou **JWT (Bearer Token)**:

| Método | Endpoint | Autenticação | Descrição |
| :--- | :--- | :--- | :--- |
| `POST` | `/v2/webhooks` | Basic Auth / JWT | Cadastra ou atualiza a URL pública HTTPS e gera um novo `webhook_secret` (`whsec_...`). |
| `GET` | `/v2/webhooks` | Basic Auth / JWT | Consulta a configuração ativa de webhook do marketplace (`id`, `url`, `status`, `has_secret`). |
| `DELETE` | `/v2/webhooks/{hash_marketplace}` | Basic Auth / JWT | Remove o webhook configurado e revoga o `webhook_secret` associado. |

---

## 3. Cabeçalhos HTTP e Validação de Assinatura (HMAC-SHA256)

Toda notificação de cobrança enviada pela LURI inclui os seguintes cabeçalhos HTTP:

| Cabeçalho HTTP | Descrição |
| :--- | :--- |
| `Content-Type` | `application/json` |
| `User-Agent` | `WebhookClient/1.0` (cobranças) ou `Luri-Webhook-Notifier/2.0` (chaves públicas) |
| `X-Webhook-Signature` | Assinatura hexadecimal **HMAC-SHA256** calculada sobre o corpo bruto (`raw JSON`) usando o seu `webhook_secret`. |
| `X-Webhook-Timestamp` | Timestamp Unix (segundos) do momento em que o disparo foi assinado. |

### Exemplo de Validação de Assinatura (PHP)

```php
$rawPayload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$webhookSecret = 'whsec_seu_secret_aqui';

$expectedSignature = hash_hmac('sha256', $rawPayload, $webhookSecret);

if (hash_equals($expectedSignature, $signatureHeader)) {
    // Assinatura válida: o evento é autêntico e íntegro
    $event = json_decode($rawPayload, true);
    http_response_code(200);
} else {
    http_response_code(401);
}
```

---

## 4. Tipos de Eventos de Webhook Enviados e Escopo de Credencial (Basic Auth vs. JWT)

A LURI envia três categorias de notificações para a URL cadastrada no seu marketplace, respeitando o nível de credencial configurado:

1. **Eventos de Cobrança (`boleto.*` e `pix.*` — Escopo Basic Auth + JWT):** Enviados para **qualquer** marketplace que possua `url_webhook` ativa.
2. **Eventos de Movimentação e Operações em Conta (`account.*` — Escopo Exclusivo JWT):** Enviados **somente** para marketplaces que possuam `url_webhook` ativa **E** pelo menos uma chave pública RSA (credencial JWT RS256) ativa configurada em `/v2/auth/public-keys`.
3. **Eventos de Segurança / Chaves Públicas (`public_key.*`):** Enviados no ciclo de vida das chaves públicas RSA.

### 4.1. Eventos de Cobrança (`resource: "event"` — Escopo Basic Auth + JWT)

| Tipo (`type`) | Ação Bancária / Origem | Status da Cobrança | Quando é Disparado |
| :--- | :--- | :--- | :--- |
| `boleto.created` | `CriarBoleto` | `created` | Quando o boleto ou boleto híbrido é criado e emitido no liquidante (`POST /v2/charge`). |
| `boleto.registered` | `RegistroBoleto` | `registered` | Quando o banco emissor confirma o registro do boleto na CIP/DDA e disponibiliza o código de barras e QR Code Pix (EMV). |
| `boleto.failed` | `CriarBoletoFalha` / Retorno CNAB | `failed` | Quando ocorre uma falha ou rejeição bancária na emissão ou no registro do boleto. |
| `boleto.updated` | `AlteracaoBoleto` | `registered` | Quando uma alteração nos dados do boleto (`PATCH /v2/charge/{id}`) é processada no banco. |
| `boleto.canceled` | `CancelamentoBoleto` / `CancelarBoleto` | `canceled` | Quando o cancelamento ou baixa do boleto é confirmado pelo banco (`POST /v2/charge/{id}/cancel` ou baixa automática). |
| `boleto.paid` | `BoletoCredito` (`payment_method: "boleto"`) | `paid` | Quando o pagamento via código de barras de boleto bancário é compensado e creditado. |
| `boleto.paid` | `RecebePix` (`payment_method: "pix"`) | `paid` | Quando um **Boleto Híbrido** (criado em `POST /v2/charge`) é liquidado instantaneamente via seu QR Code Pix. |
| `pix.created` | `CriarPix` | `registered` | Quando uma cobrança Pix pura (`static`, `cob` ou `cobv`) é criada e registrada na instituição liquidante (`POST /v2/charge/pix`). |
| `pix.paid` | `RecebePix` (`payment_method: "pix"`) | `paid` | Quando uma **cobrança Pix pura** (criada em `POST /v2/charge/pix` — `static`, `cob` ou `cobv`, sem boleto vinculado) é liquidada via Pix. |
| `boleto.assign` | `CessaoBoleto` | — | Quando ocorre evento de cessão fiduciária/carteira do título. |

### 4.2. Eventos de Movimentação e Operações em Conta (`resource: "event"` — Exclusivo Marketplaces com JWT)

Quando a conta bancária de um `seller` vinculado a um marketplace com **credencial JWT ativa** sofre qualquer movimentação financeira, tarifa, transferência, pagamento ou evento operacional na instituição liquidante, o **Roteador de Webhooks** identifica automaticamente a conta do titular e encaminha o evento com prefixo `account.*`:

| Tipo (`type`) | Ação Bancária (`event_code`) | Operação (`operation`) | Quando é Disparado |
| :--- | :--- | :--- | :--- |
| `account.pix.received` | `RecebePix` (sem cobrança em `api_boleto`) | `credit` | Quando a conta recebe um **Pix avulso / transferência direta via Chave Pix** (sem vínculo com cobrança emitida em `/v2/charge` ou `/v2/charge/pix`). |
| `account.pix.sent` | `EnvioPix` | `debit` | Quando um envio/transferência Pix (cash-out) é debitado da conta do seller. |
| `account.pix.failed` | `RejeicaoEnvioPix` | `credit` / `info` | Quando um envio Pix é rejeitado no SPI e estornado/cancelado na conta. |
| `account.pix.refunded` | `DevolucaoPix` | `debit` / `credit` | Quando uma devolução de Pix é processada na conta. |
| `account.pix.reversed` | `EstornoPix` | `credit` | Quando um estorno/devolução de Pix enviado anteriormente é creditado a favor da conta. |
| `account.pix.refund_failed` | `RejeicaoDevolucaoPix` | `info` | Quando uma solicitação de devolução Pix é rejeitada pelo SPI. |
| `account.ted.received` | `RecebTED` | `credit` | Quando a conta recebe uma transferência TED (cash-in). |
| `account.ted.sent` | `EnvioTED` | `debit` | Quando uma transferência TED (cash-out) é debitada da conta. |
| `account.ted.refunded` | `DevolucaoTED` | `credit` | Quando uma TED enviada é devolvida pelo banco destinatário e recreditada na conta. |
| `account.transfer.received` | `RecebTransf` | `credit` | Quando a conta recebe uma transferência interna entre contas da instituição. |
| `account.transfer.sent` | `EnvioTransf` | `debit` | Quando a conta envia uma transferência interna entre contas da instituição. |
| `account.bill_payment.paid` | `PagamentoBoleto` | `debit` | Quando um pagamento de título/boleto de terceiros é debitado na conta. |
| `account.bill_payment.refunded` | `DevolucaoTitulo` | `credit` | Quando um pagamento de título/boleto é devolvido e estornado na conta. |
| `account.utility_payment.paid` | `PagamentoTituloConcessionaria` | `debit` | Quando um pagamento de conta de consumo/concessionária ou tributo é debitado na conta. |
| `account.utility_payment.refunded` | `DevolucaoPagamentoTituloConcessionaria` | `credit` | Quando um pagamento de concessionária é devolvido/estornado na conta. |
| `account.service_fee` | `movimentoServico` | `debit` | Quando uma tarifa bancária de serviço (custo de envio/recebimento Pix, registro/baixa/protesto de boleto, TED, etc.) é debitada na conta. |
| `account.split` | `MovimentoSplit` | `credit` / `debit` | Quando ocorre lançamento de split financeiro na conta. |
| `account.movement.other` | `OutrosMovimentos` | `credit` / `debit` | Quando ocorre outro lançamento financeiro avulso na conta. |
| `account.boleto.credit_preview` | `PreviaBoletoCredito` | `info` | Quando o banco informa a prévia de liquidação/crédito de boleto na conta. |
| `account.boleto.protested` | `ProtestoBoleto` | `info` | Quando ocorre confirmação/atualização de protesto de título vinculado à conta. |
| `account.boleto.unified_credit` | `BoletoCreditoUnificado` | `credit` | Quando ocorre crédito unificado de liquidação de boletos em conta. |
| `account.card.purchase` / `account.card.purchase_refunded` / `account.card.withdrawal` / `account.card.withdrawal_refunded` | `CompraCartao` / `DevolucaoCompraCartao` / `SaqueCartao` / `DevolucaoSaqueCartao` | `debit` / `credit` | Eventos de movimentação de cartão vinculado à conta. |
| `account.cnab.*` | `CNAB_REG`, `CNAB_PGT`, `CNAB_CAN`, `CNAB_ALT`, `CNABRemessa`, `CNABRetorno` | `info` | Eventos de processamento de arquivos CNAB vinculados à conta. |
| `account.<evento_snake_case>` | `<QualquerOutroRegistro>` | `credit` / `debit` / `info` | Fallback dinâmico: qualquer outro evento presente ou futuro emitido pelo liquidante para a conta do seller. |

### 4.3. Eventos de Segurança / Chaves Públicas (`event: "public_key.*"`)

| Evento (`event`) | Cabeçalho `X-Event` | Quando é Disparado |
| :--- | :--- | :--- |
| `public_key.created` | `public_key.created` | Imediatamente após o cadastro de uma nova chave pública RSA via `POST /v2/auth/public-keys`. |
| `public_key.revoked` | `public_key.revoked` | Imediatamente após a revogação de uma chave pública via `DELETE /v2/auth/public-keys/{kid}`. |

---

## 5. Estrutura e Exemplos de Payloads por Tipo de Webhook

### 5.1. `boleto.created` — Cobrança Criada
Disparado após a criação inicial do título na instituição financeira.

```json
{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "resource": "event",
  "type": "boleto.created",
  "payload": {
    "boleto_id": "41b466ec2de5b02178f1bf8a2e123133",
    "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133",
    "status": "created",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "reference_id": "PEDIDO-2026-001",
    "tags": [
      "mensalidade",
      "parcela-1"
    ],
    "id_customer": "41b466ec2de5b02178f1bf8a2e123133",
    "payment_method": {
      "expiration_date": "2026-11-20",
      "payment_limit_date": "2027-02-18",
      "billing_instructions": {
        "late_fee_amount": 200,
        "interest_amount": 100,
        "discount_percentage": 500,
        "discount_limit_date": "2026-11-15"
      },
      "body_instructions": {
        "line1": "Não receber após a data limite",
        "line2": "Cobrar multa e juros após o vencimento",
        "line3": ""
      }
    },
    "linha_cod_barras": "27494149000001500000012221000037029606506000",
    "linha_digitavel": "27490.00129 22100.003704 29606.506000 4 14900000150000",
    "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...",
    "imagem": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA..."
  },
  "created_at": "2026-11-08 14:30:00"
}
```

---

### 5.2. `boleto.registered` — Boleto Registrado no Banco / DDA
Disparado quando o banco confirma o registro do boleto na CIP/DDA, consolidando o `nosso_numero`, código de barras, linha digitável e o QR Code Pix (`emv` e `imagem` Base64).

```json
{
  "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "resource": "event",
  "type": "boleto.registered",
  "payload": {
    "boleto_id": "41b466ec2de5b02178f1bf8a2e123133",
    "nosso_numero": "0000370296065",
    "status": "registered",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "reference_id": "PEDIDO-2026-001",
    "tags": [
      "mensalidade",
      "parcela-1"
    ],
    "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "updated_at": "2026-11-08T17:31:10+00:00",
    "linha_cod_barras": "27494149000001500000012221000037029606506000",
    "linha_digitavel": "27490.00129 22100.003704 29606.506000 4 14900000150000",
    "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...",
    "imagem": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA..."
  },
  "created_at": "2026-11-08 14:31:12"
}
```

---

### 5.3. `boleto.failed` — Falha na Emissão ou Rejeição Bancária
Disparado quando o banco emissor recusa o registro ou a emissão do boleto, informando o motivo no campo `error` (ou `rejection_reason` / `rejection_codes` quando originado via lote CNAB).

```json
{
  "id": "c3d4e5f6-a7b8-4c9d-0e1f-2a3b4c5d6e7f",
  "resource": "event",
  "type": "boleto.failed",
  "payload": {
    "boleto_id": "41b466ec2de5b02178f1bf8a2e123133",
    "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133",
    "status": "failed",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "reference_id": "PEDIDO-2026-001",
    "tags": [
      "mensalidade",
      "parcela-1"
    ],
    "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "error": "Falha na emissão do boleto junto ao banco",
    "updated_at": "2026-11-08T14:30:05-03:00"
  },
  "created_at": "2026-11-08 14:30:05"
}
```

---

### 5.4. `boleto.updated` — Alteração de Dados do Boleto
Disparado quando uma instrução de alteração (`PATCH /v2/charge/{id}` — vencimento, valor, multa, juros, descontos ou abatimento) é confirmada.

```json
{
  "id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
  "resource": "event",
  "type": "boleto.updated",
  "payload": {
    "boleto_id": "41b466ec2de5b02178f1bf8a2e123133",
    "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133",
    "status": "registered",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 16000,
    "reference_id": "PEDIDO-2026-001",
    "tags": [
      "mensalidade",
      "parcela-1"
    ],
    "id_customer": "41b466ec2de5b02178f1bf8a2e123133",
    "payment_method": {
      "expiration_date": "2026-12-10",
      "payment_limit_date": "2027-03-10",
      "billing_instructions": {
        "late_fee_amount": 200,
        "interest_amount": 100,
        "discount_percentage": 0,
        "discount_limit_date": null
      },
      "body_instructions": {
        "line1": "Não receber após a data limite",
        "line2": "",
        "line3": ""
      }
    },
    "linha_cod_barras": "27494151000001600000012221000037029606506000",
    "linha_digitavel": "27490.00129 22100.003704 29606.506000 4 15100000160000",
    "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...",
    "imagem": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA..."
  },
  "created_at": "2026-11-08 15:10:00"
}
```

---

### 5.5. `boleto.canceled` — Boleto Cancelado / Baixado
Disparado quando o cancelamento ou baixa do boleto é efetivado no banco emissor.

```json
{
  "id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b",
  "resource": "event",
  "type": "boleto.canceled",
  "payload": {
    "boleto_id": "41b466ec2de5b02178f1bf8a2e123133",
    "nosso_numero": "41b466ec2de5b02178f1bf8a2e123133",
    "status": "canceled",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "reference_id": "PEDIDO-2026-001",
    "tags": [
      "mensalidade",
      "parcela-1"
    ],
    "id_customer": "41b466ec2de5b02178f1bf8a2e123133",
    "updated_at": "2026-11-08T18:00:00+00:00"
  },
  "created_at": "2026-11-08 15:00:02"
}
```

---

### 5.6. `boleto.paid` — Boleto ou Boleto Híbrido Pago / Liquidado
Disparado quando uma cobrança emitida via `POST /v2/charge` (Boleto ou Boleto Híbrido) é liquidada. O atributo `payload.payment_method` diferencia se a liquidação ocorreu por compensação de **Boleto (`"boleto"`)** ou via **QR Code Pix do Boleto Híbrido (`"pix"`)**:

#### Exemplo A: Liquidado via Compensação de Boleto (`payment_method: "boleto"`)
```json
{
  "id": "3f9e1b5d-fbef-4b8a-a8ae-3c16565e0454",
  "resource": "event",
  "type": "boleto.paid",
  "payload": {
    "boleto_id": "41b466ec2de5b02178f1bf8a2e123133",
    "nosso_numero": "0000370296065",
    "status": "paid",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "total_amount": 15300,
    "interest": 300,
    "discount": 0,
    "payment_date": "2026-11-08T12:15:00+00:00",
    "credit_date": "2026-11-08T12:15:00+00:00",
    "expiration_date": "2026-11-05",
    "payment_method": "boleto"
  },
  "created_at": "2026-11-08 09:15:05"
}
```

#### Exemplo B: Boleto Híbrido Liquidado via QR Code Pix (`payment_method: "pix"`)
```json
{
  "id": "7a8b9c0d-1e2f-4a3b-5c6d-7e8f9a0b1c2d",
  "resource": "event",
  "type": "boleto.paid",
  "payload": {
    "boleto_id": "41b466ec2de5b02178f1bf8a2e123133",
    "nosso_numero": "0000370296065",
    "status": "paid",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "total_amount": 15000,
    "interest": 0,
    "discount": 0,
    "payment_date": "2026-11-08T17:20:30+00:00",
    "credit_date": "2026-11-08T17:20:30+00:00",
    "expiration_date": "2026-11-20",
    "payment_method": "pix"
  },
  "created_at": "2026-11-08 14:20:32"
}
```

---

### 5.7. `pix.created` — Cobrança Pix Criada / Registrada (`POST /v2/charge/pix`)
Disparado assim que uma cobrança Pix (`static`, `cob` ou `cobv`) é gerada e registrada com sucesso em `POST /v2/charge/pix`, entregando o `emv` (Pix Copia e Cola) e `qrcode` (Base64).

```json
{
  "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
  "resource": "event",
  "type": "pix.created",
  "payload": {
    "id_pix": "e4d5c6b7a8f90123456789abcdef0123",
    "boleto_id": "e4d5c6b7a8f90123456789abcdef0123",
    "txid": "LURI20261108142030ABCDEF123456",
    "modality": "cobv",
    "status": "registered",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "reference_id": "PEDIDO-PIX-2026-099",
    "installment": {
      "number": 1,
      "total": 12
    },
    "tags": [
      "mensalidade",
      "parcela-1"
    ],
    "id_customer": "c8f9a1b2-3d4e-5f6a-7b8c-9d0e1f2a3b4c",
    "emv": "00020101021226870014br.gov.bcb.pix2565pix.moneyp.com.br/qr/v2/cobv/...",
    "qrcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADICAYAAACtWK6eAAA...",
    "payment_method": {
      "expiration_date": "2026-11-20",
      "payment_limit_date": "2027-02-18",
      "billing_instructions": {
        "late_fee_percentage": 200,
        "interest_percentage": 100,
        "interest_mode": "percentage_monthly",
        "discount": [
          {
            "limit_date": "2026-11-15",
            "mode": "percentage",
            "amount": 500
          }
        ]
      }
    },
    "created_at": "2026-11-08T14:15:00-03:00"
  },
  "created_at": "2026-11-08 14:15:01"
}
```

---

### 5.8. `pix.paid` — Cobrança Pix Pura Liquidada (`/v2/charge/pix`)
Disparado quando uma cobrança Pix emitida diretamente pelo endpoint `POST /v2/charge/pix` (Estático `static`, Dinâmico `cob` ou Cobrança com Vencimento `cobv`, que não possui boleto bancário associado) é liquidada. Inclui os identificadores de liquidação na rede SPI (`e2e_id`, `movement_id`, `transaction_id`) e os dados do pagador (`payer`) quando retornados pela instituição liquidante.

```json
{
  "id": "9c8d7e6f-5a4b-4c3d-8e2f-1a0b9c8d7e6f",
  "resource": "event",
  "type": "pix.paid",
  "payload": {
    "id_pix": "e4d5c6b7a8f90123456789abcdef0123",
    "boleto_id": "e4d5c6b7a8f90123456789abcdef0123",
    "txid": "LURI20261108142030ABCDEF123456",
    "e2e_id": "E1337083520261108172030123456789",
    "movement_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "transaction_id": "f1e2d3c4-b5a6-4987-8c9d-0e1f2a3b4c5d",
    "reference_id": "PEDIDO-PIX-2026-099",
    "status": "paid",
    "seller": "4e12dad6b58d4f83a9a12312312bd3757b",
    "amount": 15000,
    "total_amount": 15000,
    "interest": 0,
    "discount": 0,
    "payment_date": "2026-11-08T17:20:30+00:00",
    "credit_date": "2026-11-08T17:20:30+00:00",
    "expiration_date": "2026-11-20",
    "payment_method": "pix",
    "payer": {
      "name": "Maria Oliveira",
      "taxpayer_id": "36160560042",
      "bank_ispb": "00000000",
      "branch": "0001"
    }
  },
  "created_at": "2026-11-08 14:20:32"
}
```

---

### 5.9. `account.*` — Eventos de Movimentação e Operações em Conta (Exclusivo JWT)
Disparados exclusivamente para marketplaces que possuem **credencial JWT ativa** quando ocorre uma movimentação na conta bancária do seller (como `account.pix.received` avulso, `account.pix.sent`, `account.ted.received`, `account.service_fee`, etc.).

#### Exemplo A: `account.pix.sent` — Envio de Pix (Cash-out)
```json
{
  "id": "6f8a9b0c-1d2e-4f3a-8b9c-0d1e2f3a4b5c",
  "resource": "event",
  "type": "account.pix.sent",
  "payload": {
    "seller": {
      "id": "4e12dad6b58d4f83a9a12312312bd3757b",
      "name": "ABR PISCINAS COMPACTAS LTDA",
      "document": "66405113000185",
      "agency": "0001",
      "account": "986067-7"
    },
    "event_code": "EnvioPix",
    "operation": "debit",
    "type_lancto": "D",
    "amount": "80.00",
    "amount_cents": 8000,
    "transaction_date": "2026-11-05T21:05:10.683",
    "movement_id": "e15075bf-fe5a-457c-a81b-b8366b0a01d3",
    "transaction_id": "3ed17a4c-75f6-4b66-a9e0-3a679c2edae5",
    "e2e_id": "E11581339202611060004A093F3805DD",
    "nsu": 289316327,
    "description": null,
    "counterparty": {
      "role": "beneficiary",
      "name": "Leticia Minotto Ravanholi",
      "document": "03979389006",
      "pix_key": "03979389006",
      "bank_ispb": "10573521",
      "agency": "0001"
    },
    "details": {
      "Identificador": "27400010986067766405113000185",
      "CodigoMovimento": "e15075bf-fe5a-457c-a81b-b8366b0a01d3",
      "NumeroOperacao": "E11581339202611060004A093F3805DD",
      "VlrTransacao": 80,
      "TipoLancto": "D"
    }
  },
  "created_at": "2026-11-06 00:05:11"
}
```

#### Exemplo B: `account.pix.received` — Recebimento de Pix Avulso na Chave da Conta
```json
{
  "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "resource": "event",
  "type": "account.pix.received",
  "payload": {
    "seller": {
      "id": "4e12dad6b58d4f83a9a12312312bd3757b",
      "name": "FUNDACAO PAULISTA DE TECNOLOGIA E EDUCACAO",
      "document": "51665727000129",
      "agency": "0001",
      "account": "288558-0"
    },
    "event_code": "RecebePix",
    "operation": "credit",
    "type_lancto": "C",
    "amount": "100.00",
    "amount_cents": 10000,
    "transaction_date": "2026-11-05T21:24:15.607",
    "movement_id": "5e2d546e-f0b0-4633-af7b-8bf8a14c699b",
    "transaction_id": "0f9382c9-a8ee-43d1-b6f5-5bfdd1279f20",
    "e2e_id": "E228964312026110600231T6WC7F9PPD",
    "nsu": 289322193,
    "description": null,
    "counterparty": {
      "role": "payer",
      "name": "MARCO AURELIO RODRIGUES DIAS",
      "document": "38876716866",
      "bank_ispb": "22896431",
      "agency": "0001"
    },
    "details": {
      "Identificador": "27400010288558051665727000129",
      "RecebedorChave": "51665727000129",
      "CodigoMovimento": "5e2d546e-f0b0-4633-af7b-8bf8a14c699b",
      "NumeroOperacao": "E228964312026110600231T6WC7F9PPD",
      "VlrTransacao": 100,
      "TipoLancto": "C"
    }
  },
  "created_at": "2026-11-06 00:24:16"
}
```

---

### 5.10. `public_key.created` e `public_key.revoked` — Ciclo de Vida de Chaves Públicas
Disparados quando uma chave pública assimétrica (RS256) é adicionada ou revogada em `/v2/auth/public-keys`.

#### Exemplo: `public_key.created`
```json
{
  "event": "public_key.created",
  "request_id": "req_a1b2c3d4e5f67890",
  "timestamp": "2026-11-08T14:30:00-03:00",
  "data": {
    "hash_marketplace": "4b7e010c54a048efab973279355dbc51",
    "kid": "prod-key-2026-v1",
    "algorithm": "RS256",
    "key_size": 2048,
    "fingerprint_sha256": "4b68e982d6fc5732c4d622955f269389e1b2123d24268e3b5df51a84f506ee4f",
    "status": "active",
    "created_at": "2026-11-08T14:30:00-03:00",
    "ip_address": "177.18.25.10"
  }
}
```

#### Exemplo: `public_key.revoked`
```json
{
  "event": "public_key.revoked",
  "request_id": "req_9f8e7d6c5b4a3210",
  "timestamp": "2026-11-08T15:00:00-03:00",
  "data": {
    "hash_marketplace": "4b7e010c54a048efab973279355dbc51",
    "kid": "prod-key-2026-v1",
    "status": "revoked",
    "revoked_at": "2026-11-08T15:00:00-03:00",
    "ip_address": "177.18.25.10"
  }
}
```

---

## 6. Dicionário de Campos do `payload` (Eventos `boleto.*` e `pix.*`)

| Campo | Tipo | Presente nos Eventos | Descrição |
| :--- | :--- | :--- | :--- |
| `boleto_id` | `string` | Todos (`boleto.*` e `pix.*`) | Identificador único da cobrança na LURI. |
| `id_pix` | `string` | `pix.created`, `pix.paid` | Identificador único da cobrança Pix na LURI. |
| `txid` | `string` | `pix.created`, `pix.paid` | Identificador da transação/conciliação Pix (`txid`). |
| `modality` | `string` | `pix.created` | Modalidade da cobrança Pix: `"static"`, `"cob"` ou `"cobv"`. |
| `e2e_id` | `string` | `pix.paid`, `boleto.paid` (via Pix) | EndToEndId (`NumeroOperacao` `E...`) da liquidação Pix no SPI/BACEN. |
| `movement_id` | `string` | `pix.paid`, `boleto.paid` (via Pix) | UUID do movimento (`CodigoMovimento`) no liquidante. |
| `transaction_id` | `string` | `pix.paid` | UUID da transação (`CodigoTransacao`) no liquidante. |
| `payer` | `object` | `pix.paid` | Dados do pagador informados pelo SPI (`name`, `taxpayer_id`, `bank_ispb`, `branch`). |
| `nosso_numero` | `string` | Todos (`boleto.*`) | Nosso número bancário (ou identificador do título enquanto aguarda confirmação). |
| `status` | `string` | Todos (`boleto.*` e `pix.*`) | Estado atual da cobrança: `created`, `registered`, `failed`, `canceled` ou `paid`. |
| `seller` | `string` | Todos (`boleto.*` e `pix.*`) | Identificador (`hash_seller`) do estabelecimento recebedor. |
| `amount` | `integer` | Todos (`boleto.*` e `pix.*`) | Valor nominal original da cobrança em centavos (ex: `15000` = R$ 150,00). |
| `total_amount` | `integer` | `boleto.paid`, `pix.paid` | Valor total efetivamente pago pelo sacado em centavos. |
| `interest` | `integer` | `boleto.paid`, `pix.paid` | Soma de juros e multa cobrados na liquidação em centavos. |
| `discount` | `integer` | `boleto.paid`, `pix.paid` | Valor total de desconto concedido na liquidação em centavos. |
| `payment_date` | `string` | `boleto.paid`, `pix.paid` | Data/hora do pagamento no formato ISO 8601. |
| `credit_date` | `string` | `boleto.paid`, `pix.paid` | Data/hora da efetivação do crédito na conta no formato ISO 8601. |
| `payment_method` | `string` / `object` | `boleto.paid`, `pix.paid` (string) / `created`, `pix.created`, `updated`, `assign` (object) | Em `boleto.paid` e `pix.paid`, informa `"boleto"` ou `"pix"`. Nos demais eventos, contém o objeto com datas e instruções de cobrança. |
| `reference_id` | `string` | `created`, `pix.created`, `registered`, `failed`, `updated`, `canceled`, `pix.paid` | Identificador externo de conciliação enviado pelo parceiro. |
| `tags` | `array` | `created`, `pix.created`, `registered`, `failed`, `updated`, `canceled` | Lista de etiquetas associadas à cobrança. |
| `linha_cod_barras` | `string` | `created`, `registered`, `updated` | Código de barras numérico de 44 dígitos. |
| `linha_digitavel` | `string` | `created`, `registered`, `updated` | Linha digitável formatada do boleto. |
| `emv` | `string` | `created`, `pix.created`, `registered`, `updated` | Código Pix Copia e Cola (EMV). |
| `qrcode` / `imagem` | `string` | `pix.created` (`qrcode`) / `boleto.*` (`imagem`) | Imagem do QR Code Pix em formato Base64. |
| `error` | `string` | `boleto.failed` | Mensagem descritiva do erro ou motivo de rejeição bancária. |
| `updated_at` | `string` | `registered`, `failed`, `canceled` | Data/hora da última atualização de status (ISO 8601). |