Erros e rejeições

A distinção mais importante de uma integração fiscal é separar erro técnico de rejeição fiscal. Elas pedem reações opostas.

As quatro categorias

1. Erro de requisição

O Conota não aceitou a chamada como enviada. Autenticação inválida, campo obrigatório ausente, formato incompatível, cota esgotada.

Chega como 4xx, de forma síncrona. Repetir a mesma chamada sem mudar nada dá o mesmo resultado.

2. Falha de processamento

O job foi criado, mas alguma etapa anterior à autorização não pôde ser concluída — indisponibilidade do autorizador, erro de comunicação, certificado inválido.

Aparece como status: "failed" com a mensagem em erro. Muitas dessas podem ser repetidas.

3. Rejeição fiscal

O documento chegou ao autorizador e foi recusado por uma regra fiscal.

Vem com codigo_status e motivo_status do próprio autorizador. Repetir igual dá rejeição igual: é preciso corrigir os dados.

Motivos comuns envolvem cadastro do destinatário, NCM, CFOP, CST/CSOSN, tributação, numeração, inconsistência entre totais e regras específicas do município.

4. Documento autorizado

A emissão foi aceita e passou a produzir efeitos fiscais.

Rejeição não é a API fora do ar

Uma rejeição prova o contrário: o documento chegou até o autorizador. Tratá-la como erro de infraestrutura leva ao pior comportamento possível — reenviar em laço.

Reconciliação em lote

Para achar o que falhou num período, sem varrer o histórico:

GET /v1/jobs/erros?de=2026-09-01&ate=2026-09-03        # jobs com falha
GET /v1/jobs/rejeitadas?de=2026-09-01&ate=2026-09-03   # notas rejeitadas

Ambas aceitam formato=resumo para agrupar por motivo — útil para descobrir que 80% das rejeições da semana são a mesma causa. A janela é de no máximo 90 dias; sem datas, os últimos 7.

Para entender uma rejeição item a item:

GET /v1/jobs/{job_id}/itens

Ela marca qual item provocou a rejeição, com os grupos tributários de cada um.

O que registrar no seu sistema

• identificador da operação (job_id);
• referencia_externa;
• tipo de documento e emitente;
• data e hora;
• código e mensagem retornados;
• ambiente;
• status final conhecido.

Nunca registre segredo em log

API Key, senha de certificado e o próprio certificado não podem aparecer em log, APM ou ticket.