Skip to main content
Em qualquer integração assíncrona, uma requisição pode ser reenviada — por timeout do cliente, retry automático ou instabilidade de rede — sem que você tenha certeza se a primeira tentativa foi processada. Em emissão fiscal isso é crítico: emitir a mesma operação duas vezes pode gerar duas notas fiscais para a mesma venda, um problema fiscal real. Para evitar isso, a API da Spedy oferece idempotência nativa por meio de dois identificadores que você controla e reutiliza nas retentativas: Ambos são idempotentes por empresa — o mesmo valor pode se repetir entre empresas diferentes, mas não dentro da mesma empresa.

​
Por que idempotência importa em emissão fiscal

Diferente de uma chamada de leitura, reenviar uma emissão não é “seguro por padrão”: sem um identificador estável, cada tentativa vira uma nova nota. Com transactionId e integrationId, você pode reenviar a mesma operação quantas vezes precisar que o resultado é sempre o mesmo — a Spedy reconhece o identificador e não duplica.

​
integrationId — idempotência da nota

Identificador da nota no seu sistema (máximo de 36 caracteres). Recomendado em todas as integrações que emitem notas diretamente pelos endpoints de nota.
  • Idempotência: um segundo POST com o mesmo integrationId atualiza a nota existente em vez de criar uma nova — protege contra duplicidade em retries e timeouts. A edição só é possível enquanto a nota não estiver autorizada, denegada ou cancelada; nesses estados finais ela não pode mais ser alterada.
  • Correção de rejeitada: uma nota rejected ainda pode ser editada — para corrigi-la, reenvie o POST com os dados corrigidos e o mesmo integrationId, sem precisar deletar a anterior. Veja Ciclo de vida da nota.
cURL

​
transactionId — idempotência da venda

Código da transação/venda no seu sistema, enviado ao criar uma venda em POST /v1/orders. Reenviar a criação da venda com o mesmo transactionId não gera uma venda duplicada — útil quando a emissão parte de uma venda (veja Primeiros passos). Diferente da nota, a venda não é editável: reenviar com o mesmo transactionId evita a duplicação, mas não altera a venda já registrada.

​
Boas práticas

  • Use um identificador estável por operação lógica (o id da sua venda ou nota interna) e reutilize-o em cada retry — não gere um valor novo a cada tentativa, senão a idempotência não funciona.
  • Trate timeouts com cautela: um timeout de rede não significa que a operação falhou do lado da Spedy — ela pode ter sido processada mesmo sem a resposta chegar até você. Reenviar com o mesmo identificador é seguro.
  • Reconcilie pelo status real: consulte a nota (ou receba o evento de webhook) para confirmar o resultado antes de agir, em vez de assumir que a chamada anterior falhou.

​
Relacionado