Emitir uma nota pela API da Spedy é uma operação assíncrona: a resposta
2xx do POST que cria a nota confirma apenas que a solicitação foi aceita
para processamento — não que a nota foi autorizada pela SEFAZ ou pela
prefeitura. Entre a criação e a autorização, a nota passa por uma sequência
de estados, e o tempo entre um estado e outro varia de segundos a, em
contingência, horas ou dias.
Há dois caminhos de entrada, que diferem em quando a nota é enfileirada:
- POST direto na nota (
/v1/product-invoices, /v1/consumer-invoices,
/v1/service-invoices): a nota já é enfileirada para emissão no próprio
POST — não existe um passo de emissão separado.
- Via venda (
POST /v1/orders): a emissão segue o autoIssueMode da venda —
pode ser imediata ou ficar aguardando (created) até um gatilho (ex.:
afterPayment). Veja Fluxo de emissão.
Saber em qual estado a nota está — e o que fazer em cada um — é o que
permite ao seu sistema decidir quando liberar a mercadoria, emitir o
DANFE/DANFSE ou notificar o cliente, em vez de assumir que “a chamada
respondeu 200, então a nota está pronta”.
Estados e transições
O campo status (InvoiceStatus) de uma nota — NF-e, NFC-e ou NFS-e —
segue a máquina de estados abaixo:
authorized, rejected, denied e canceled são estados terminais para
aquela numeração — uma nota rejeitada ou denegada não “vira” autorizada
depois; você corrige o problema e emite uma nova nota. A exceção é
inContingent, que é sempre transitório: assim que a autoridade volta a
operar e o lote é reprocessado, a nota é reclassificada como authorized
ou rejected.
O que cada status significa
InvoiceStatus não é InvoiceProcessingStatus. São dois campos
diferentes e é fácil confundir os dois:
InvoiceStatus (status) é o estado fiscal da nota — os valores
da tabela acima (created, authorized, rejected etc.).InvoiceProcessingStatus é o estado interno de processamento de
um evento na fila: processing (aguardando execução), success
(o evento foi executado) ou failed (falha interna de infraestrutura ao
processar o evento).
success em InvoiceProcessingStatus não significa nota autorizada —
significa que a Spedy conseguiu executar aquele passo do fluxo (enviar o
lote, receber a resposta da SEFAZ, atualizar o status). Uma nota
rejeitada também tem InvoiceProcessingStatus igual a success,
porque o processamento funcionou normalmente; só o resultado fiscal foi
negativo. Para saber se a nota foi autorizada, olhe sempre o
InvoiceStatus — nunca o InvoiceProcessingStatus.Como acompanhar as transições
Não faça polling apertado esperando a nota “ficar pronta” logo após criá-la.
Use um dos dois mecanismos abaixo.
Webhooks (recomendado)
A forma mais eficiente de saber que o status mudou é configurar um
webhook: a Spedy notifica seu sistema a cada transição relevante (recebida,
autorizada, rejeitada, cancelada etc.), sem que você precise consultar a
API. Veja Visão geral de webhooks e
Eventos e payload para o formato de
cada evento.
Obter a nota fiscal (GET por ID)
Se você não usa webhooks, obtenha a nota (GET .../{id}) para ler o
status atual guardado pela Spedy — essa leitura não aciona a SEFAZ.
O endpoint check-status consulta a nota diretamente na
SEFAZ/prefeitura e reconcilia o resultado no seu registro. Use-o apenas
para destravar ou reconciliar uma nota cujo status no Spedy pode estar
desatualizado — por exemplo, uma nota marcada como rejected que na
verdade consta autorizada na SEFAZ, ou um acompanhamento automático que
esgotou as tentativas. Enquanto a nota ainda está enqueued (não enviada à
autoridade), esse endpoint responde erro — ele não serve para “furar a
fila” e forçar uma emissão imediata. 
