Idempotência (Padrão IETF)

No ecossistema fiscal brasileiro, quedas de conexão de rede ou timeouts entre o seu servidor e a API podem gerar incerteza sobre se a nota foi autorizada ou não pela SEFAZ. Sem proteção, reenviar a requisição causaria rejeição por duplicidade ou geraria uma segunda nota indevida.

Para solucionar isso, a API adota o padrão formal IETF Idempotency-Key.

---

O Cabeçalho Idempotency-Key

Ao disparar operações de mutação (POST e PUT), envie um identificador único de requisição:

Idempotency-Key: pedido_ecommerce_982187

RECOMENDAÇÃO DE CHAVE

Utilize como chave o ID único da transação no seu banco de dados (ex: uuid da venda ou ID do pedido no e-commerce).

---

Como a API Processa a Idempotência

flowchart TD
    A[Requisição com Idempotency-Key] --> B{Chave já existe no Redis / Banco?}
    B -- Não --> C[Executa Emissão SEFAZ normalmente]
    C --> D[Armazena Resultado e Hash do Payload]
    D --> E[Retorna HTTP 201 Created]
    
    B -- Sim (Em andamento) --> F[Retorna HTTP 409 Conflict ou aguarda lock]
    B -- Sim (Concluída) --> G{O payload é idêntico?}
    G -- Sim --> H[Retorna exatamente o mesmo HTTP 200/201 do cache]
    G -- Não --> I[Retorna HTTP 422 Unprocessable Entity - Payload divergente]

1. Mesmo Payload + Mesma Chave: Retorna imediatamente a resposta armazenada (mesma chave de acesso, status e protocolo), sem reenviar à SEFAZ.
2. Payload Diferente + Mesma Chave: A API rejeita a requisição para evitar que uma chave seja reutilizada acidentalmente com dados de outra operação.