Fiscal Contora
Fiscal Contora Infraestrutura fiscal
Documentação / Resiliência e Idempotência v1
Quickstart OpenAPI IA Health
API REST fiscal

Emita com total segurança contra falhas de rede e instabilidades do governo.

Esta documentação descreve a versão pública atual da API fiscal da Contora, com base compartilhada de empresas, certificados, chaves, filas, webhooks e artefatos para NF-e, NFC-e, NFS-e, CT-e e MDF-e. NF-e, NFC-e e NFS-e operam em produção regular; CT-e e MDF-e em produção assistida e controlada.

Atualizado em .

Arquitetura parruda e tolerante a falhas

O motor fiscal da Contora foi desenhado sob o princípio de que redes falham e servidores do governo saem do ar. Nossa arquitetura não tenta apenas repassar a falha para o seu ERP; ela implementa mecanismos de proteção ativa, como idempotência, filas resilientes e circuit breaker.

Chave de Idempotência (Idempotency Key)

Para evitar que falhas de conexão de rede ou retentativas automáticas gerem notas fiscais duplicadas ou cobranças repetidas, a API aceita uma chave de idempotência. Envie o cabeçalho Idempotency-Key (ou X-Idempotency-Key) com um valor único (recomenda-se um UUID v4 por requisição). 

curl -X POST https://fiscal.contora.com.br/api/v1/nfe/drafts/18f017f7-a69c-4fa6-89c7-05f52fcc8be4/dispatch \
  -H 'Authorization: Bearer fct_...' \
  -H 'Idempotency-Key: e9a2c3d4-b5e6-4f7a-8b9c-0d1e2f3a4b5c' \
  -H 'Content-Type: application/json' \
  -d '{"action": "authorize"}'
Duração da Chave
Garantida por 24 horas. Requisições idênticas nesse período retornam a mesma resposta instantaneamente sem reprocessar.
Cabeçalho de Reenvio
Quando uma resposta é servida a partir do cache de idempotência, a API inclui o header X-Fiscal-Idempotency-Replayed: 1.
Conflito de Payload (409)
Se a mesma chave for enviada com um payload diferente para a mesma rota, a API rejeita com erro HTTP 409 (idempotency_key_conflict).
Boa prática de robustez: Sempre envie a chave de idempotência ao despachar ou cancelar um documento. Caso sua chamada sofra timeout, repita exatamente a mesma chamada com a mesma chave.

Proteção automática contra duplicidade (Rejeição 539)

Além da Idempotency-Key, o dispatch com action: authorize confere, antes de falar com a SEFAZ, se aquele número e série já foram autorizados antes para a mesma empresa e ambiente — mesmo sem chave de idempotência, e mesmo que a chamada venha de um documento diferente. Se já existir, a API devolve o documento já autorizado na hora (HTTP 200, com o mesmo access_key e protocolo), sem enviar uma nova tentativa à SEFAZ.

Por que isso importa: reenvio do mesmo numero + serie — seja por engano, seja reagindo a um timeout que na verdade tinha dado certo — costumava gerar a Rejeição 539 (Duplicidade com chave diferente) só depois de um envio inteiro à SEFAZ. Agora isso é resolvido localmente, sem esperar o retorno do governo.
Isso não substitui a Idempotency-Key: ela cobre reenvio da mesma requisição (mesmo payload) dentro de 24h; a checagem de número/série cobre reenvio do mesmo número de nota por qualquer via, sem prazo de expiração.

Fila assíncrona com retentativas automáticas

A autorização de notas fiscais não bloqueia sua conexão HTTP. Ao disparar o dispatch, o documento entra em nossa fila de alta prioridade.

Retries em Background Se a SEFAZ estiver instável ou lenta, nosso worker reagenda internamente a tentativa de transmissão respeitando tempos seguros, sem que sua aplicação precise lidar com loops de retry HTTP.
Previsibilidade Você recebe um status queued ou processing imediatamente, e é notificado via Webhook assim que a SEFAZ devolve o resultado definitivo.

Retry do cliente HTTP

Repita apenas timeouts, HTTP 408, 429 e 5xx. Não repita automaticamente erros 4xx permanentes de autenticação, validação ou regra de negócio. Quando houver Retry-After, aguarde o período informado; caso contrário, use backoff exponencial com jitter.

Operações de escrita: o retry deve reutilizar a mesma Idempotency-Key e o mesmo corpo. Trocar o payload com a mesma chave retorna HTTP 409.

Indisponibilidade da SEFAZ

Em falhas transitórias, a plataforma registra a tentativa e usa fila, retry e circuit breaker para proteger a operação. Emissão SVC e contingência offline de NFC-e ainda não fazem parte do contrato público da API; o ERP não deve presumir chaveamento automático de modalidade.

Disponibilidade e Circuit Breakers

Para proteger tanto a nossa infraestrutura quanto o tempo de resposta do seu ERP, implementamos Circuit Breakers em todas as comunicações com órgãos públicos.

Comportamento Ativo
Se a SEFAZ estadual falhar consecutivamente por 5 vezes, o circuito "abre".
Resposta Rápida (Fail-Fast)
Com o circuito aberto, a API rejeita novas tentativas de transmissão imediatamente, devolvendo erro claro em menos de 100ms em vez de fazer sua requisição esperar 30 segundos em timeout.
Recuperação Automática
O circuito volta a testar a SEFAZ de forma segura em background após 5 minutos.

Fluxo recomendado para integração "inquebrável"

  1. Gere chaves de idempotência únicas para cada documento (ex: concatenar ID_PEDIDO + TIPO_ACAO).
  2. Cadastre Webhooks para ouvir os eventos definitivos (document.authorized, document.rejected).
  3. Monitore os cabeçalhos de Rate Limit para não exceder a capacidade do seu plano.
  4. Se receber um erro 5xx ou timeout, repita a requisição usando exatamente a mesma chave de idempotência.