API e Integrações

1. Credencial de integração (Client ID e Client Secret), para sistemas externos (ERP, e-commerce). Vale nas rotas /integration/* e usa HTTP Basic: o Client ID é o usuário e o Client Secret é a senha.

2. Login de usuário (token JWT), para o que a tela também faz: listar e baixar documentos, relatórios e cadastros, com as permissões do usuário. Chame POST /auth/login com e-mail e senha e envie o token recebido:

Eventos

• document.received: Um documento novo (NF-e, CT-e ou NFS-e) entrou no acervo da empresa.
• manifestation.registered: A SEFAZ registrou uma manifestação do destinatário ou um desacordo de CT-e.
• emission.authorized: Uma NF-e, NFC-e, CT-e ou MDF-e emitida foi autorizada pela SEFAZ.
• emission.canceled: Uma NF-e ou NFC-e emitida foi cancelada.
• emission.corrected: Uma carta de correção foi registrada.
• emission.command.succeeded: Um comando de emissão assíncrona chegou ao resultado fiscal.
• emission.command.failed: Um comando esgotou as tentativas sem resposta da SEFAZ.

Corpo

O corpo traz só ids, chave de acesso, códigos e datas. XML e DANFE saem pela API autenticada, pelo link em data.links. Campo novo pode aparecer a qualquer momento: ignore o que não conhecer. Mudança de significado sai numa versão nova do evento (eventVersion).

{
  "id": "5f0c6c1e-8a4e-4c4b-9a53-1f1f3a0d2b77",
  "eventType": "document.received",
  "eventVersion": 1,
  "occurredAt": "2026-09-28T12:00:00.000Z",
  "tenantId": "…",
  "companyId": "…",
  "companyCnpj": "11222333000181",
  "aggregate": { "type": "received-document", "id": "3526…6785" },
  "data": {
    "documentId": "…",
    "documentKind": "NFE",
    "accessKey": "3526…6785",
    "issuedAt": "2026-09-27T18:20:00.000Z",
    "links": { "self": "/fiscal-documents/nfe/…" }
  }
}

Cabeçalhos e verificação

• X-Finzio-Event-Id: id do evento, igual ao id do corpo e o mesmo em toda reentrega. Guarde e descarte o que já processou.
• X-Finzio-Event-Type: o tipo do evento.
• X-Finzio-Timestamp: segundos Unix do envio. Recuse o que estiver a mais de 5 minutos do seu relógio: é o que impede alguém de reenviar uma requisição capturada.
• X-Finzio-Signature: v1= seguido do HMAC-SHA256, em hexadecimal, de timestamp.corpo com o segredo da assinatura.

import { createHmac, timingSafeEqual } from 'node:crypto';

// body: o corpo CRU da requisição, antes de qualquer JSON.parse.
export function webhookValido(headers, body, segredo) {
  const ts = Number(headers['x-finzio-timestamp']);
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const esperado = Buffer.from(
    'v1=' + createHmac('sha256', segredo).update(ts + '.' + body).digest('hex'),
  );
  // Na rotação de segredo chegam duas assinaturas separadas por vírgula.
  return String(headers['x-finzio-signature'])
    .split(',')
    .some((s) => {
      const recebido = Buffer.from(s.trim());
      return recebido.length === esperado.length && timingSafeEqual(recebido, esperado);
    });
}

Entrega, repetição e ordem

Responda 2xx em até 10 segundos e processe depois, em fila. Qualquer outro retorno, ou a falta de resposta, gera nova tentativa: 30 segundos, dobrando até 6 horas, com uma variação aleatória, até 8 tentativas. Depois disso a entrega fica como falha na tela, de onde pode ser reenviada com o mesmo event id. A entrega é ao menos uma vez: o mesmo evento pode chegar duas vezes, e eventos de documentos diferentes podem chegar fora de ordem. Para o mesmo documento, use occurredAt.