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

# Idempotência

> Previna criação duplicada de cobranças e saques.

## Quando usar

Sempre envie uma chave única por operação quando houver risco de retry por timeout/rede.

## CASHIN: `referenceId`

Endpoint: `POST /v1/integrations/create-transaction`

* Campo: `referenceId` (UUID)
* Escopo: único por `userId` + `type = CASHIN`
* Se repetir: retorna a mesma transação criada anteriormente

Se a chave já existir em outro contexto, a API responde `409 Conflict`.

## CASHOUT: `idempotencyKey`

Endpoint: `POST /v1/integrations/create-cashout`

* Campo: `idempotencyKey` (UUID)
* Escopo: único por `userId` + `type = CASHOUT`
* Se repetir: retorna o mesmo saque

Se a chave já existir em outro contexto, a API responde `409 Conflict`.

## Padrão recomendado

1. Gere UUID no seu backend no momento da intenção de pagamento/saque.
2. Salve essa chave no seu banco junto com o pedido.
3. Em retry, reutilize exatamente a mesma chave.
4. Nunca gere nova chave para o mesmo evento de negócio.

## Exemplo

```json theme={null}
{
  "amount": 20.00,
  "description": "Pedido #1234",
  "referenceId": "77823bb5-3d84-4cbf-a2a4-43230cc3b1d1"
}
```

## Observação importante

Idempotência evita duplicidade de criação na AXNPAY, mas você ainda deve ter idempotência no seu próprio sistema para fechamento de pedido e conciliação.