API do Fiscalo

1. Autenticação

Crie a chave no app, em Configurações > API e webhooks (dono ou administrador, com a verificação em duas etapas). Ela aparece uma vez só. Envie em todas as chamadas:

curl https://api.fiscalo.com.br/v1/empresas \
  -H "Authorization: Bearer fsk_test_SUA_CHAVE"

A chave vale para a conta que a criou; não precisa do cabeçalho de organização. Limite: 300 requisições por minuto por chave. Erros voltam como {"erro": "mensagem"}, com o código HTTP correspondente.

2. Rotas principais

3. Emitir uma nota

Crie o rascunho (o cálculo é feito e guardado nesse momento) e depois emita:

curl -X POST https://api.fiscalo.com.br/v1/empresas/{id}/notas \
  -H "Authorization: Bearer fsk_test_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"competencia": "2026-11-20", "servicoId": "…", "tomadorId": "…", "valor": "1500.00"}'

curl -X POST https://api.fiscalo.com.br/v1/empresas/{id}/notas/{nota}/emitir \
  -H "Authorization: Bearer fsk_test_SUA_CHAVE"

A resposta traz status: AUTORIZADA (com número e chave de acesso), REJEITADA (com os erros da Sefin) ou PENDENTE_CONFIRMACAO, que se resolve sozinho e chega pelo webhook.

4. Webhooks

Cadastre a URL (https) no app. Enviamos nota.autorizada, nota.rejeitada, nota.cancelada e nota.substituida, com novas tentativas por até 2 dias se a sua URL falhar:

POST https://seu-sistema.com.br/fiscalo
Fiscalo-Evento: nota.autorizada
Fiscalo-Assinatura: t=1793900000,v1=5d41402abc4b2a76…

{"id": "evt_123", "tipo": "nota.autorizada", "criado_em": "2026-11-05T16:40:46Z", "tentativa": 1,
 "dados": {"id": "…", "empresa_id": "…", "status": "AUTORIZADA", "numero": "128",
           "chave_acesso": "3550308…", "competencia": "2026-11-05", "valor": "1500.00"}}

Confira a assinatura antes de confiar no corpo: HMAC-SHA256 de t + "." + corpo com o segredo do webhook (whsec_…), e recuse eventos com mais de 5 minutos.

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

function assinaturaValida(corpo, cabecalho, segredo) {
  const [, t, v1] = cabecalho.match(/^t=(\d+),v1=([0-9a-f]{64})$/) ?? []
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const esperado = createHmac('sha256', segredo).update(`${t}.${corpo}`).digest()
  return timingSafeEqual(esperado, Buffer.from(v1, 'hex'))
}

Responda com qualquer código 2xx em até 10 segundos. Use o id do evento para não processar o mesmo aviso duas vezes.