> ## Documentation Index
> Fetch the complete documentation index at: https://bmpdocs.moneyp.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Eventos de Callback

> Envelope comum e payload de cada evento de callback enviado ao parceiro no fluxo de retenção de portabilidade.

> Todo callback é um JSON plano: os campos do evento entram no mesmo nível dos campos do envelope comum. O envio é feito para a URL cadastrada em [Cadastrar Callback](/e-consignado/portabilidade/cadastrar-callback).

## Envelope comum

Todos os eventos compartilham estes campos, com os campos específicos de cada evento achatados no mesmo nível:

| Campo             | Tipo   | Obrigatório | Descrição                                                                                                                |
| ----------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `evento`          | string | sim         | Código do evento, em `SCREAMING_SNAKE_CASE` (ex.: `PORTABILIDADE_SOLICITADA`).                                           |
| `dataHoraEvento`  | string | sim         | Data/hora do evento, formato `yyyy-MM-dd HH:mm:ss`, horário de Brasília.                                                 |
| `nuPortabilidade` | string | sim         | Número da portabilidade na CTC — chave de correlação com a consulta gerencial.                                           |
| `detalhe`         | string | condicional | Mensagem descritiva. Obrigatório nos eventos de erro/recusa; **omitido do JSON** (não enviado como `null`) quando vazio. |

**Convenções de formato:**

* Datas sempre como string no formato `yyyy-MM-dd HH:mm:ss`, no horário de Brasília.
* Campos opcionais sem valor são enviados como `null` — exceto `detalhe`, que é omitido do JSON quando vazio.
* Acentuação é enviada crua, em UTF-8, sem escaping (ex.: `"João Conceição"`).

***

## `PORTABILIDADE_SOLICITADA`

Disparado depois que a solicitação de portabilidade passa por todas as validações automáticas de recepção.

| Campo                   | Tipo     | Descrição                                    |
| ----------------------- | -------- | -------------------------------------------- |
| `numeroCCB`             | string?  | Número da CCB do contrato.                   |
| `codigoProposta`        | guid?    | Código da proposta.                          |
| `nomeCliente`           | string?  | Nome do cliente.                             |
| `telefoneCliente`       | string?  | Telefone do cliente.                         |
| `emailCliente`          | string?  | E-mail do cliente.                           |
| `instituicaoProponente` | string?  | Instituição proponente da portabilidade.     |
| `valorParcela`          | decimal? | Valor da parcela.                            |
| `dataLimiteRetencao`    | string   | Prazo para retenção (`yyyy-MM-dd HH:mm:ss`). |

```json PORTABILIDADE_SOLICITADA theme={null} theme={null}
{
  "evento": "PORTABILIDADE_SOLICITADA",
  "dataHoraEvento": "2026-08-27 15:13:04",
  "nuPortabilidade": "90012345678",
  "numeroCCB": "CCB-4471902",
  "codigoProposta": "7c1e2f30-8a4b-4c9d-b2e1-0d5f6a7b8c90",
  "nomeCliente": "João Conceição",
  "telefoneCliente": "11996399161",
  "emailCliente": "joao@exemplo.com",
  "instituicaoProponente": "BMP",
  "valorParcela": 350.00,
  "dataLimiteRetencao": "2026-08-29 08:00:00"
}
```

***

## `DOCUMENTO_ENVIADO`

Disparado quando o Termo de Retenção é enviado ao cliente (etapa que segue a chamada de [Retenção — Incluir Assinante](/e-consignado/portabilidade/retencao-incluir-assinante)).

| Campo              | Tipo      | Descrição                                                                    |
| ------------------ | --------- | ---------------------------------------------------------------------------- |
| `numeroCCB`        | string?   | Número da CCB.                                                               |
| `canaisUtilizados` | string\[] | Canais em que o termo foi efetivamente enviado (`Email`, `SMS`, `WhatsApp`). |
| `linkAssinatura`   | string    | URL de assinatura do cliente (`{UrlBase}/assinatura/{assinaturaId}`).        |

```json DOCUMENTO_ENVIADO theme={null} theme={null}
{
  "evento": "DOCUMENTO_ENVIADO",
  "dataHoraEvento": "2026-08-27 15:20:11",
  "nuPortabilidade": "90012345678",
  "numeroCCB": "CCB-4471902",
  "canaisUtilizados": ["Email", "WhatsApp"],
  "linkAssinatura": "https://urlassinatura.com.br/3f9a..."
}
```

<Note>
  O `assinaturaId` retornado por [Retenção — Incluir Assinante](/e-consignado/portabilidade/retencao/incluir-assinante) não vem como campo separado no envelope — ele aparece embutido na URL de `linkAssinatura`. A correlação entre os eventos e a chamada de inclusão do assinante é feita por `nuPortabilidade`.
</Note>

***

## `ASSINATURA_COLETADA`

Disparado quando o cliente assina o Termo de Retenção.

| Campo                | Tipo    | Descrição                                        |
| -------------------- | ------- | ------------------------------------------------ |
| `numeroCCB`          | string? | Número da CCB.                                   |
| `dataHoraAssinatura` | string  | Data/hora da assinatura (`yyyy-MM-dd HH:mm:ss`). |

```json ASSINATURA_COLETADA theme={null} theme={null}
{
  "evento": "ASSINATURA_COLETADA",
  "dataHoraEvento": "2026-08-27 16:02:47",
  "nuPortabilidade": "90012345678",
  "numeroCCB": "A00014D9",
  "dataHoraAssinatura": "2026-08-27 16:02:45"
}
```

***

## `TIMEOUT_ASSINATURA`

Disparado quando o link de assinatura expira (fim do prazo D+1) sem que o cliente tenha assinado.

| Campo       | Tipo    | Descrição                                                       |
| ----------- | ------- | --------------------------------------------------------------- |
| `numeroCCB` | string? | Número da CCB.                                                  |
| `detalhe`   | string  | Obrigatório. Ex.: `"Prazo encerrado em <data> sem assinatura."` |

```json TIMEOUT_ASSINATURA theme={null} theme={null}
{
  "evento": "TIMEOUT_ASSINATURA",
  "dataHoraEvento": "2026-09-10 08:00:01",
  "nuPortabilidade": "90012345678",
  "numeroCCB": "A000AF1M",
  "detalhe": "Prazo encerrado em 2026-09-10 08:00:00 sem assinatura."
}
```