Pular para o conteúdo principal

Referência externa e idempotência

O sistema que chama o Conota precisa conseguir relacionar uma operação fiscal ao registro correspondente na própria base. Para isso, envie uma referência externa única na emissão.

{
  "referencia_externa": "pedido_98231",
  "cpf_cnpj": "60772432000142",
  "nota": { "...": "..." }
}

Até 120 caracteres, letras e números — um UUID serve bem.

O que ela garante​

Reenviar a mesma referência não emite outra nota

A referencia_externa é idempotente por conta. Reenviar a mesma referência devolve o job já existente, com HTTP 200 e "idempotente": true, em vez de emitir de novo.

{
  "job_id": "6f8dc295-...",
  "referencia_externa": "pedido_98231",
  "idempotente": true,
  "status": "completed",
  "mensagem": "Emissão já registrada para esta referencia_externa — retornando o job existente..."
}

Repare na diferença de código HTTP: 202 é emissão nova, 200 é a mesma de antes.

Por que isso importa​

Imagine que sua aplicação envie uma emissão e a conexão caia antes da resposta chegar. Sem uma referência própria, ela fica em dúvida entre três hipóteses:

  • a emissão nunca chegou;
  • está sendo processada;
  • o documento já foi autorizado.

Com a referência persistida antes do envio, você localiza a operação em vez de adivinhar:

GET /v1/jobs/localizar?ref=pedido_98231

A busca por referência é exata e dispensa informar período.

Para reemitir corrigido, use uma referência NOVA​

Se a nota falhou e você corrigiu o payload, não reutilize a mesma referência — ela devolveria o job antigo em vez de emitir a versão corrigida. Gere uma nova, mantendo no seu banco o vínculo entre as duas tentativas.

Sem a referência, ainda dá para achar​

GET /v1/jobs/localizar também aceita atributos de negócio: emitente, destinatário, valor exato e período. É o caminho de reconciliação quando o job_id se perdeu e não havia referência.

Última atualização em