Pular para o conteúdo principal

Notificações

Nesta página, você encontrará uma explicação das notificações assíncronas enviadas pelo Koncili.

O Koncili envia notificações automáticas através de requisições HTTP POST para a URL de callback previamente cadastrada pelo integrador. Todas as notificações seguem rigorosamente o seguinte formato JSON:

Importante

O endpoint de notificação precisa ser público para permitir o recebimento das mensagens.

{
  "notificationType": "TIPO_EVENTO",
  "timestamp": "ISO8601",
  "payload": {
    // Dados específicos do evento
  }
}

Tipos de notificação​

Abaixo estão listados todos os tipos de notificação que o Koncili pode enviar, a resposta esperada para ambos é:

HTTP/1.1 200 OK
Content-Type: application/json

{"status": "success"}

1. Teste da URL de notificação​

{
  "notificationType": "TEST_NOTIFICATION",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": null
}

2. Conta criada​

Disparado quando uma nova conta é ativada:

{
  "notificationType": "ACCOUNT_CREATED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "accountId": 1234,
    "status": "ACTIVE"
  }
}

3. Conciliação finalizada​

Enviado quando um processo de conciliação é concluído:

Informação

Aqui existem dois cenários possíveis de notificação, conciliação finalizada com sucesso e com erro.

{
  "notificationType": "RECONCILIATION_COMPLETED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "accountId": 1234,
    "reconciliationId": 4321,
    "resolvedEndDate": "2025-06-13T16:00:00Z",
    "situation": "CONCILIED"
  }
}
{
  "notificationType": "RECONCILIATION_COMPLETED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "accountId": 1234,
    "reconciliationId": 4321,
    "resolvedEndDate": null,
    "situation": "ERROR"
  }
}

4. Bloqueio temporário​

Disparado quando a API é bloqueada temporariamente:

{
  "notificationType": "BLOCKED_TEMPORARY",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "integratorName": "INTEGRATOR NAME",
    "durationMinutes": 60
  }
}

5. Bloqueio permanente​

Enviado em casos de tentativas recorrentes após bloqueio temporário:

{
  "notificationType": "BLOCKED_PERMANENT",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "integratorName": "INTEGRATOR NAME",
  }
}

6. Desbloqueio​

Notificação de liberação do acesso:

{
  "notificationType": "UNLOCKED",
  "timestamp": "2025-06-13T15:00:00Z",
  "payload": {
    "integratorName": "INTEGRATOR NAME",
  }
}