# Idempotência

Repita um POST após uma falha de rede sem criar registos duplicados, com o cabeçalho Idempotency-Key, e saiba quando a resposta guardada é devolvida e quando há conflito.


Quando um POST fica sem resposta (tempo esgotado, ligação cortada), não sabe se o servidor chegou a executá-lo. Se o pedido levar o cabeçalho `Idempotency-Key`, pode repeti-lo com a mesma chave: o servidor executa-o uma vez e, nas repetições, devolve a resposta que guardou.

## Onde funciona

O cabeçalho é aceite em todos os pedidos `POST` da Business API (`$BUSINESS_API`) e da Consumer API (`$CONSUMER_API`), tanto em criações como em acções sobre um registo existente. Os pedidos `GET`, `PATCH`, `PUT` e `DELETE` ignoram-no. Sem o cabeçalho, o pedido é executado normalmente, sem protecção contra repetições.

## Regras da chave

- De 1 a 255 caracteres ASCII visíveis, sem espaços. Um UUID v4 gerado pelo seu sistema por cada operação lógica serve bem.
- Uma chave fora deste formato é recusada com `400` e `invalid_params` a apontar para `Idempotency-Key`.
- A chave vale para a combinação de credencial (`Authorization`), contexto (`X-Context-ID`), método e caminho. A mesma chave enviada com outra chave de API ou para outro caminho é tratada como nova.
- A resposta guardada fica disponível durante 24 horas após o primeiro pedido.

## Exemplo de pedido e resposta

Este pedido cria um cliente e precisa da permissão `business:customers:create`.

```bash
curl -sS -X POST "$BUSINESS_API/customers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: 9b2f4c1e-7a3d-4e8b-b5c6-0d1e2f3a4b5c" \
  -H "Content-Type: application/json" \
  -d '{"customer_type":"individual","category":"residential","display_name":"Felismina Mabunda","phone":"+258849876543"}'
```

Primeira resposta, `201 Created`:

```json
{
  "id": "cus_2kGa3TnW7qLzE5rHbV1mXc8yJdP",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "customer_type": "individual",
  "category": "residential",
  "display_name": "Felismina Mabunda",
  "phone": "+258849876543",
  "status": "active",
  "created_at": "2026-11-19T10:42:07.318250Z",
  "updated_at": "2026-11-19T10:42:07.318250Z"
}
```

Se repetir exactamente o mesmo pedido, recebe outra vez `201` com o mesmo `id`, mais dois cabeçalhos: `Idempotency-Key` com a chave enviada e `Idempotent-Replayed: true`, que indica que esta é a resposta guardada e não uma segunda execução.

## Conflito: a mesma chave com outro corpo

O servidor compara o corpo de cada repetição com o do primeiro pedido. Se mudar um único campo e reutilizar a chave, recebe `409`:

```json
{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Idempotency-Key was already used with a different request payload.",
  "instance": "$BUSINESS_API/customers",
  "code": "CONFLICT",
  "error_code": "request.idempotency_conflict",
  "request_id": "req_4f1c9a2b7e3d48a6b0c5d2e1f9a8b7c6"
}
```

Gere uma chave nova sempre que o conteúdo do pedido muda. O campo `type` aponta para a página de erros do site quando o operador o configura; caso contrário vem como `about:blank`.

## O que fica guardado

- Respostas com estado abaixo de 500 ficam guardadas, incluindo recusas `4xx`. Se o primeiro pedido falhou por um campo inválido, a repetição com a mesma chave devolve a mesma recusa: corrija o corpo e use uma chave nova.
- Erros `5xx` não ficam guardados. Pode repetir com a mesma chave e o pedido volta a ser executado.
- Corpos de pedido acima de 4 MiB não passam pela protecção de idempotência.
- As chaves vivem na memória do servidor que respondeu. Uma repetição atendida por outra instância, ou depois de um reinício, é executada de novo.
- Alguns endpoints também registam a chave na base de dados. Os comandos de turno de caixa guardam-na durante 7 dias, por isso aí a repetição é reconhecida mesmo depois de um reinício; a operação respectiva na referência explica o funcionamento.

## Próximos passos

- [Ler os códigos de erro da API](/docs/getting-started/errors)
- [Receber pagamentos e confirmá-los por webhook](/docs/guides/receive-payments)
- [Criar clientes a partir de outro sistema](/docs/guides/import-customers)

