Ir para o conteúdo

3.0. Visão Geral

🧾 Descrição

A plataforma VeFlow envia notificações via WebHook para informar o cliente sobre eventos que acontecem de forma assíncrona no fluxo de recebíveis de cartão: a chegada das URs consultadas nas registradoras, a evolução do contrato e o resultado da conciliação de cada UR.

Todas as notificações são entregues por uma requisição POST para a URL de callback informada pelo cliente na implantação. O corpo é sempre JSON em UTF-8, e o campo tipoNotificacao, presente na raiz do payload, identifica qual notificação chegou — use-o para rotear o processamento.

Uma notificação pode ser reenviada (por retentativa ou porque a posição do recurso mudou de novo), sempre carregando a última posição conhecida. Por isso o endpoint do cliente precisa ser idempotente.

🔔 Tipos de Notificação

tipoNotificacao Notificação Página Quando é disparada
1 Listagem de URs 3.1. Listagem de URs A consulta da agenda foi concluída e as URs recebidas da registradora já estão disponíveis para uso
2 Atualizações do contrato 3.2. Atualizações do contrato O contrato mudou de status, teve URs incluídas/removidas ou teve seus totais recalculados
3 Atualizações da UR 3.3. Atualizações da UR A conciliação identificou mudança de valor, de prioridade ou liquidação de uma UR do contrato

Todas as notificações chegam na mesma URL de callback. Não existe URL por tipo: o roteamento é responsabilidade do cliente, a partir de tipoNotificacao.

📦 Envelope Padrão

O payload não tem envelope aninhado: tipoNotificacao fica na raiz, ao lado dos blocos específicos daquele tipo.

{
  "tipoNotificacao": 1,
  "...": "blocos específicos do tipo de notificação"
}
Campo Tipo Descrição
tipoNotificacao integer Identifica o tipo da notificação (1, 2 ou 3). Sempre presente na raiz do payload.

Convenções dos payloads

  • Nomes de campos em camelCase.
  • Datas no formato YYYY-MM-DD; data e hora no formato ISO 8601.
  • Valores monetários como number com 2 casas decimais.
  • O array titulos transporta as URs envolvidas na notificação; o endpoint deve estar apto a processar várias URs por envio.

📨 Headers do Disparo

Toda requisição enviada pela plataforma inclui:

Header Exemplo Descrição
Content-Type application/json; charset=utf-8 Sempre JSON em UTF-8
Authorization Bearer {seu_token} Credencial do callback, conforme combinado na implantação
Idempotency-Key 9f2c1b7e-5d84-4f3a-9c21-77bde1a4c5f0 GUID único do disparo. Use para deduplicação. Retentativas do mesmo disparo repetem este valor. 
POST /webhook/veflow HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Bearer {seu_token}
Idempotency-Key: 9f2c1b7e-5d84-4f3a-9c21-77bde1a4c5f0

{
  "tipoNotificacao": 2,
  "...": "..."
}

🔐 Autenticação do Callback

A URL de callback e a forma de autenticação são definidas junto ao time de implantação. Regras:

  • A URL precisa ser HTTPS. URLs em http:// não são aceitas.
  • A plataforma envia a credencial acordada no header Authorization (padrão: Bearer token fixo).
  • O cliente deve validar o header Authorization em toda requisição e responder 401 quando a credencial não conferir.
  • A rotação da credencial e a alteração da URL de callback são solicitadas ao time de implantação — contato: contato@vertrau.capital.

Não use a credencial da API VeFlow como credencial do callback: são segredos distintos e com ciclos de vida independentes.

✅ Como o Endpoint do Cliente Deve Responder

Resposta do cliente Interpretação da plataforma
200 OK ou 204 No Content Entrega confirmada. O disparo é encerrado.
408, 429 ou 5xx Falha transitória. O disparo entra em retentativa (ver abaixo).
Timeout, DNS, conexão recusada Falha transitória. O disparo entra em retentativa.
Demais 4xx (400, 401, 403, 404, 422) Falha definitiva. Não há retentativa — o disparo é registrado como falho.
3xx (redirect) Tratado como falha. A plataforma não segue redirecionamentos.

Regras de implementação:

  • Responda 2xx assim que receber a mensagem, idealmente em menos de 5 segundos, e processe o conteúdo de forma assíncrona (fila interna). Processamento longo dentro do request causa timeout e retentativa desnecessária.
  • O corpo da resposta é ignorado pela plataforma. Só o status HTTP importa.
  • Não responda 2xx para descartar mensagem que você não conseguiu processar: nesse caso deixe a plataforma retentar (5xx).

🔁 Retentativa e Backoff

A entrega é considerada bem-sucedida quando o cliente responde 2xx. Em falha transitória, há retentativa com backoff exponencial e jitter, repetindo o mesmo Idempotency-Key:

Tentativa Delay aproximado
1 imediato
2 ~1s + jitter
3 ~2s + jitter
4 ~4s + jitter
5 ~8s + jitter

Após 5 tentativas sem sucesso, o disparo é registrado como falho e não é mais retentado automaticamente. A posição atual do recurso continua disponível por consulta ativa:

🪞 Deduplicação por Chave de Idempotência

Como uma retentativa pode entregar a mesma notificação mais de uma vez, o cliente deve deduplicar pelo header Idempotency-Key.

Padrão recomendado:

  1. Ao receber a notificação, persista o Idempotency-Key em uma tabela com unique constraint.
  2. Se o INSERT falhar por violação de unicidade, responda 200 OK sem reprocessar.
  3. Caso contrário, enfileire o processamento e responda 200 OK.

♻️ Por Que o Endpoint Precisa Ser Idempotente

Deduplicar pelo Idempotency-Key resolve a retentativa, mas não é o único motivo de reenvio. A mesma notificação é reenviada com um novo disparo sempre que a posição do recurso muda de novo — por exemplo, um contrato que passa por Registrando, Aguardando liquidação, Em liquidação e Liquidado gera quatro notificações de tipoNotificacao = 2 para o mesmo contrato.identificador.

Portanto:

  • Trate cada notificação como "última posição conhecida", e não como um delta a ser somado ao seu estado local. Sobrescreva, não acumule.
  • Não presuma ordem de entrega. Duas notificações do mesmo recurso podem chegar fora de ordem. Compare com o estado que você já tem e descarte o retrocesso, ou reconsulte o recurso pelo endpoint de detalhes.
  • Reprocessar a mesma posição não pode gerar efeito colateral duplicado (lançamento contábil repetido, e-mail reenviado, baixa duplicada).

🕒 Observações

  • As notificações são assíncronas: não existe garantia de que cheguem dentro da mesma requisição HTTP que originou o processamento.
  • A consulta da agenda é processada apenas entre 09:00 e 18:00 em dias úteis. Solicitações recebidas fora dessa janela são agendadas para o próximo dia útil, e a notificação tipoNotificacao = 1 só é disparada quando o processamento efetivamente ocorre — ver 4.1. Solicitar agenda.
  • A conciliação roda em vários ciclos ao longo do dia; o evento de UR não liquidada é apurado somente no último processamento do dia (19h) — ver 3.3. Atualizações da UR.
  • Credenciais da API, headers obrigatórios e ambientes: 1.1. Primeiros Passos.