# Eventos de Webhook

Esta pagina documenta todos os tipos de eventos enviados via webhook pela plataforma FluxiQ NPC.

## Formato do Payload

Todos os webhooks seguem o mesmo formato base:

```json
{
  "event": "tipo_do_evento",
  "timestamp": "2026-02-03T14:30:00Z",
  "data": {
    // Dados especificos do evento
  }
}
```

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `event` | string | Tipo do evento (ex: `boleto_paid`) |
| `timestamp` | string | Data/hora do evento em formato ISO 8601 (UTC) |
| `data` | object | Dados especificos do evento |

## Eventos de Boleto

### boleto_created

Enviado quando um novo boleto e criado no sistema.

```json
{
  "event": "boleto_created",
  "timestamp": "2026-02-03T14:30:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "linha_digitavel": "23793381286000000000300000004061846600000100 00",
    "valor": 10000,
    "vencimento": "2026-03-15",
    "status": "draft",
    "pagador": {
      "nome": "Joao Silva",
      "documento": "12345678901",
      "tipo_documento": "cpf"
    },
    "beneficiario": {
      "nome": "Empresa LTDA",
      "documento": "12345678000190"
    },
    "created_at": "2026-02-03T14:30:00Z"
  }
}
```

**Campos do evento:**

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `nosso_numero` | string | Identificador unico do boleto |
| `codigo_barras` | string | Codigo de barras de 44 digitos |
| `linha_digitavel` | string | Linha digitavel de 47 digitos |
| `valor` | integer | Valor em centavos |
| `vencimento` | string | Data de vencimento (YYYY-MM-DD) |
| `status` | string | Status do boleto (`draft`) |
| `pagador` | object | Dados do pagador |
| `beneficiario` | object | Dados do beneficiario |
| `created_at` | string | Data/hora de criacao |

### boleto_registered

Enviado quando o boleto e registrado com sucesso na Nuclea (PCR).

```json
{
  "event": "boleto_registered",
  "timestamp": "2026-02-03T14:35:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "linha_digitavel": "23793381286000000000300000004061846600000100 00",
    "valor": 10000,
    "vencimento": "2026-03-15",
    "status": "registered",
    "pcr_protocol": "PCR2026020312345678",
    "registered_at": "2026-02-03T14:35:00Z",
    "pagador": {
      "nome": "Joao Silva",
      "documento": "12345678901",
      "tipo_documento": "cpf"
    },
    "beneficiario": {
      "nome": "Empresa LTDA",
      "documento": "12345678000190"
    }
  }
}
```

**Campos adicionais:**

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `status` | string | Status atualizado (`registered`) |
| `pcr_protocol` | string | Protocolo de registro na Nuclea |
| `registered_at` | string | Data/hora do registro |

### boleto_paid

Enviado quando um pagamento e confirmado para o boleto.

```json
{
  "event": "boleto_paid",
  "timestamp": "2026-02-04T09:15:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "valor_original": 10000,
    "valor_pago": 10000,
    "valor_desconto": 0,
    "valor_juros": 0,
    "valor_multa": 0,
    "status": "paid",
    "data_pagamento": "2026-02-04",
    "data_credito": "2026-02-05",
    "canal_pagamento": "internet_banking",
    "banco_pagador": "001",
    "agencia_pagador": "1234",
    "settlement_id": "stl_abc123def456",
    "paid_at": "2026-02-04T09:15:00Z"
  }
}
```

**Campos especificos:**

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `valor_original` | integer | Valor original do boleto (centavos) |
| `valor_pago` | integer | Valor efetivamente pago (centavos) |
| `valor_desconto` | integer | Desconto aplicado (centavos) |
| `valor_juros` | integer | Juros cobrados (centavos) |
| `valor_multa` | integer | Multa cobrada (centavos) |
| `data_pagamento` | string | Data do pagamento (YYYY-MM-DD) |
| `data_credito` | string | Data prevista para credito (YYYY-MM-DD) |
| `canal_pagamento` | string | Canal utilizado para pagamento |
| `banco_pagador` | string | Codigo do banco pagador (COMPE) |
| `agencia_pagador` | string | Agencia do pagador |
| `settlement_id` | string | ID do ciclo de liquidacao |

**Canais de pagamento:**

| Valor | Descricao |
|-------|-----------|
| `internet_banking` | Internet Banking |
| `mobile_banking` | App do banco |
| `atm` | Caixa eletronico |
| `branch` | Agencia bancaria |
| `lottery` | Casa loterica |
| `correspondent` | Correspondente bancario |

### boleto_cancelled

Enviado quando um boleto e cancelado.

```json
{
  "event": "boleto_cancelled",
  "timestamp": "2026-02-03T16:00:00Z",
  "data": {
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "valor": 10000,
    "vencimento": "2026-03-15",
    "status": "cancelled",
    "motivo_cancelamento": "solicitacao_cliente",
    "cancelled_at": "2026-02-03T16:00:00Z",
    "cancelled_by": "admin@empresa.com.br"
  }
}
```

**Campos especificos:**

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `motivo_cancelamento` | string | Motivo do cancelamento |
| `cancelled_at` | string | Data/hora do cancelamento |
| `cancelled_by` | string | Usuario que solicitou o cancelamento |

**Motivos de cancelamento:**

| Valor | Descricao |
|-------|-----------|
| `solicitacao_cliente` | Solicitado pelo cliente |
| `erro_emissao` | Erro na emissao |
| `duplicidade` | Boleto duplicado |
| `acordo` | Negociacao/acordo |
| `outros` | Outros motivos |

## Eventos de Liquidacao

### settlement_completed

Enviado quando um ciclo de liquidacao e processado com sucesso.

```json
{
  "event": "settlement_completed",
  "timestamp": "2026-02-04T08:45:00Z",
  "data": {
    "settlement_id": "stl_abc123def456",
    "cycle_date": "2026-02-04",
    "cycle_type": "morning",
    "total_boletos": 47,
    "total_valor": 1523450,
    "arquivo_acmp615": "ACMP615.20260204.083000",
    "status": "completed",
    "started_at": "2026-02-04T08:35:00Z",
    "completed_at": "2026-02-04T08:45:00Z",
    "summary": {
      "pagos": 45,
      "valor_pagos": 1485000,
      "rejeitados": 2,
      "valor_rejeitados": 38450
    }
  }
}
```

**Campos do evento:**

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `settlement_id` | string | ID unico do ciclo de liquidacao |
| `cycle_date` | string | Data do ciclo (YYYY-MM-DD) |
| `cycle_type` | string | Tipo do ciclo (`morning` ou `afternoon`) |
| `total_boletos` | integer | Total de boletos processados |
| `total_valor` | integer | Valor total processado (centavos) |
| `arquivo_acmp615` | string | Nome do arquivo ACMP615 processado |
| `summary` | object | Resumo por status |

**Tipos de ciclo:**

| Valor | Horario | Descricao |
|-------|---------|-----------|
| `morning` | 08:30 | Ciclo da manha |
| `afternoon` | 16:30 | Ciclo da tarde |

### payment_received

Enviado para cada pagamento individual recebido durante o processamento de liquidacao. Este evento e complementar ao `boleto_paid` e fornece informacoes adicionais do arquivo ACMP615.

```json
{
  "event": "payment_received",
  "timestamp": "2026-02-04T08:40:00Z",
  "data": {
    "settlement_id": "stl_abc123def456",
    "nosso_numero": "00000000000000001",
    "codigo_barras": "23793.38128 60000.000003 00000.000406 1 84660000010000",
    "valor_pago": 10000,
    "data_pagamento": "2026-02-04",
    "data_credito": "2026-02-05",
    "banco_recebedor": "237",
    "agencia_recebedora": "1234",
    "tipo_liquidacao": "normal",
    "sequencial_arquivo": 15,
    "acmp615_record": {
      "tipo_registro": "20",
      "codigo_movimento": "06"
    }
  }
}
```

**Campos especificos:**

| Campo | Tipo | Descricao |
|-------|------|-----------|
| `settlement_id` | string | ID do ciclo de liquidacao |
| `banco_recebedor` | string | Banco que recebeu o pagamento |
| `agencia_recebedora` | string | Agencia que recebeu |
| `tipo_liquidacao` | string | Tipo de liquidacao |
| `sequencial_arquivo` | integer | Posicao no arquivo ACMP615 |
| `acmp615_record` | object | Dados brutos do registro ACMP615 |

**Tipos de liquidacao:**

| Valor | Descricao |
|-------|-----------|
| `normal` | Liquidacao padrao D+1 |
| `express` | Liquidacao expressa D+0 |
| `dda` | Via Debito Direto Autorizado |

## Resumo de Eventos

| Evento | Trigger | Campos Chave |
|--------|---------|--------------|
| `boleto_created` | Boleto criado no sistema | `nosso_numero`, `valor`, `status` |
| `boleto_registered` | Registro confirmado na Nuclea | `nosso_numero`, `pcr_protocol`, `status` |
| `boleto_paid` | Pagamento confirmado | `nosso_numero`, `valor_pago`, `settlement_id` |
| `boleto_cancelled` | Boleto cancelado | `nosso_numero`, `motivo_cancelamento` |
| `settlement_completed` | Ciclo de liquidacao finalizado | `settlement_id`, `total_boletos`, `summary` |
| `payment_received` | Pagamento individual processado | `settlement_id`, `nosso_numero`, `valor_pago` |

## Testando Eventos

### Ambiente Sandbox

No sandbox, voce pode disparar eventos de teste para validar sua integracao:

```bash
# Disparar evento de boleto pago
curl -X POST "https://sandbox.monetarie_npc.com.br/api/v1/central/webhooks/test" \
  -H "X-API-Key: pk_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "boleto_paid",
    "nosso_numero": "00000000000000001"
  }'
```

**Tipos de eventos disponiveis para teste:**

| event_type | Descricao |
|------------|-----------|
| `boleto_created` | Simula criacao de boleto |
| `boleto_registered` | Simula registro na Nuclea |
| `boleto_paid` | Simula pagamento |
| `boleto_cancelled` | Simula cancelamento |
| `settlement_completed` | Simula ciclo de liquidacao |
| `payment_received` | Simula pagamento individual |

### Usando webhook.site

Para desenvolvimento e debug, recomendamos usar [webhook.site](https://webhook.site):

1. Acesse [webhook.site](https://webhook.site)
2. Copie a URL unica gerada
3. Configure como `webhook_url` no portal (sandbox)
4. Execute acoes ou dispare eventos de teste
5. Visualize os payloads em tempo real

::: tip Inspecionando Payloads
O webhook.site permite ver todos os headers, corpo da requisicao e metadata. Isso e util para depurar problemas de assinatura ou formato.
:::

### Simulador Local

Para desenvolvimento local, voce pode usar o [ngrok](https://ngrok.com) para expor sua maquina:

```bash
# Iniciar ngrok
ngrok http 3000

# Output:
# Forwarding: https://abc123.ngrok.io -> http://localhost:3000

# Configurar URL no portal
curl -X PUT "https://sandbox.monetarie_npc.com.br/api/v1/central/config/central" \
  -H "X-API-Key: pk_test_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook_url": "https://abc123.ngrok.io/webhooks/monetarie_npc"
  }'
```

## Proximos Passos

- [Implementacao](/webhooks/handling) - Guia completo de implementacao
- [Seguranca](/webhooks/#seguranca) - Validacao de assinatura
- [Fluxo de Liquidacao](/guides/settlement-flow) - Entenda o processo de liquidacao