Skip to main content
Um dos erros mais comuns ao integrar com a Spedy é tratar a resposta 2xx de um endpoint de emissão como “nota emitida”. A API da Spedy é assíncrona: a resposta HTTP confirma apenas que a solicitação foi aceita para processamento, não que a nota foi autorizada pela SEFAZ ou pela prefeitura.
Um 200 OK (ou 201 Created) em POST /v1/orders/{id}/invoices/issue ou em POST /v1/product-invoices, /v1/consumer-invoices, /v1/service-invoices significa apenas que a Spedy aceitou a solicitação e a enfileirou. A nota pode, minutos depois, ser rejeitada pela SEFAZ. Nunca libere mercadoria, feche a venda para o cliente ou dê a operação fiscal por concluída só porque a chamada retornou 2xx.

​
Por que é assíncrono

Autorizar uma nota fiscal depende de um sistema fora da Spedy — a SEFAZ do estado ou a prefeitura do município — que pode levar de alguns segundos a, em cenários de indisponibilidade (contingência), horas ou dias para responder. Se a API da Spedy segurasse a conexão HTTP até ter esse resultado, qualquer lentidão ou instabilidade do lado da autoridade fiscal travaria sua integração. Por isso a emissão funciona em duas fases desacopladas:
  1. Aceite da solicitação — resposta HTTP imediata (2xx), confirmando que os dados foram recebidos e a nota entrou na fila de processamento.
  2. Processamento fiscal — a Spedy envia o lote à SEFAZ/prefeitura, aguarda o retorno e atualiza o status da nota de forma assíncrona, independente da chamada HTTP original.
Os estados possíveis nessa segunda fase — created, enqueued, received, authorized, rejected, inContingent, denied, canceled — e as transições entre eles estão documentados em Ciclo de vida da nota.

​
Como acompanhar o resultado

Como a resposta HTTP não carrega o veredito final, seu sistema precisa de uma forma de saber quando a nota chegou a um estado terminal. Há dois mecanismos, e eles não são intercambiáveis:
Não faça polling apertado logo após o issue esperando a nota “ficar pronta”. Prefira webhooks para ser notificado no momento da mudança de status; use consulta de status apenas quando precisar do estado atual sob demanda.

​
Resumo

  • Síncrono é só o aceite HTTP: confirma que a Spedy recebeu a solicitação, nada além disso.
  • Assíncrono é o processamento fiscal real: pode levar segundos ou, em contingência, muito mais — veja Contingência.
  • O único jeito confiável de saber se uma nota foi autorizada é observar o status via webhook ou consulta — nunca o código HTTP da chamada de emissão.