> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spedy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotência e reprocessamento

> Reenvie requisições com segurança usando transactionId e integrationId.

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:

| Identificador   | Onde é enviado                                                         | Identifica        | Ao reenviar com o mesmo valor                                             |
| --------------- | ---------------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------- |
| `transactionId` | `POST /v1/orders`                                                      | a **venda**       | não cria uma venda duplicada (a venda **não** é editada)                  |
| `integrationId` | `POST /v1/product-invoices`, `/consumer-invoices`, `/service-invoices` | a **nota fiscal** | atualiza a nota existente, enquanto não autorizada, denegada ou cancelada |

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](/pages/guides/ciclo-de-vida-da-nota).

```bash cURL theme={null}
curl -X POST https://sandbox-api.spedy.com.br/v1/product-invoices \
  -H "X-Api-Key: sua-chave-de-api" \
  -H "Content-Type: application/json" \
  -d '{ "integrationId": "NOTA-2026-000123", "...": "demais campos da nota" }'
```

## `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](/pages/start/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

* [Erros e respostas](/pages/start/erros-e-respostas)
* [Ciclo de vida da nota](/pages/guides/ciclo-de-vida-da-nota)
* [Eventos e payload de webhooks](/pages/webhooks/eventos-e-payload)