Sua primeira emissão

Uma emissão fiscal não é um POST que termina quando a API responde.

O Conota recebe a solicitação, cria uma operação de emissão e executa o processamento até existir um estado conclusivo ou uma situação que exija ação da sua integração.

O que a API devolve

A emissão responde HTTP 202 com o identificador do trabalho:

{
  "job_id": "6f8dc295-...",
  "referencia_externa": "pedido_98231",
  "status": "pending",
  "mensagem": "NF-e enfileirada para emissão.",
  "consulta": "/v1/nfe/consultar/6f8dc295-...",
  "webhook": "configurado"
}

202 não significa autorizada. Significa aceita para processamento.

Fluxo

Seu sistema
   │
   ├── POST /v1/nfe/emitir  ──►  202 { job_id }
   │
   ▼
Conota
   ├── valida e registra a operação
   ├── monta e assina o documento
   ├── transmite ao autorizador
   │
   ▼
Resultado
   ├── autorizada
   ├── rejeitada    (uma regra fiscal recusou)
   └── falha        (não chegou a uma decisão fiscal)

Acompanhando

curl -s https://api.conota.dev/v1/nfe/consultar/$JOB_ID \
  -H "X-API-Key: $CONOTA_API_KEY"

A resposta traz status, tentativas, o bloco nota (número, série, chave de acesso, motivo) e arquivos com os links de download.

Prefira webhooks a consultar em laço.

Guarde os identificadores

Ao criar uma emissão, armazene:

o job_id retornado;
a sua referencia_externa;
tipo de documento;
emitente;
data e hora da solicitação.

São esses dados que permitem reconciliar seu sistema com o Conota quando uma conexão cai ou uma resposta não é persistida localmente.

Não reenvie no escuro

Timeout não significa que nada aconteceu

Se a conexão cair depois de você enviar a emissão, não presuma que falhou. Primeiro localize:

GET /v1/jobs/localizar?ref=pedido_98231

Reenviar às cegas uma operação fiscal pode gerar duplicidade ou conflito de numeração. Melhor ainda: envie referencia_externa desde o começo — reenviar a mesma referência devolve o job existente em vez de emitir de novo.

Antes de emitir de verdade, confira o payload

Existe uma rota que confere os campos sem emitir e sem consumir cota:

POST /v1/nfe/verificar-campos

Ela pega o erro mais traiçoeiro dessa API: um campo com nome errado é ignorado em silêncio — vlrProd no lugar de vProd gera uma nota válida no schema com o produto a R$ 0,00.

O que a API devolve​

Fluxo​

Acompanhando​

Guarde os identificadores​

Não reenvie no escuro​

Antes de emitir de verdade, confira o payload​

Próximos passos​