Observabilidade e logs
Seu sistema deve conseguir responder três perguntas sobre qualquer emissão, inclusive meses depois:
- o que tentamos emitir?
- qual operação foi criada no Conota?
- qual foi o resultado final conhecido?
Se qualquer uma delas depende de "abrir o painel e procurar", a sua observabilidade está incompleta.
Campos de correlação
referencia_externa;job_id;- CNPJ do emitente;
- tipo do documento;
- número e série, quando já existirem;
- data e hora da tentativa;
- ambiente;
- status do job e status da nota;
- código e motivo da rejeição.
Registre a tentativa, não só o resultado
O log mais útil é o da requisição que nunca voltou
Se você só registra respostas, o caso mais difícil — o timeout — não deixa rastro. Grave a intenção
antes de enviar, com a referencia_externa já definida. É isso que torna a reconciliação
possível.
Nunca registre
- API Key;
- senha do certificado;
- o certificado;
- o payload inteiro se ele carregar credenciais.
Conciliação periódica
Vale uma rotina que, todo dia, busque jobs sem estado final e consulte em lote:
POST /v1/jobs/consultar-lote
E, para o panorama do período:
GET /v1/jobs/erros?de=...&ate=...&formato=resumo
GET /v1/jobs/rejeitadas?de=...&ate=...&formato=resumo
O formato resumo agrupa por motivo — costuma revelar que a maior parte das rejeições da semana
tem uma causa só.