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

# Idempotência

> Aprenda a usar o header Idempotency-Key em requisições POST para garantir que retries não criem recursos duplicados na Ticto API.

Idempotência é a propriedade que garante que realizar a mesma operação múltiplas vezes produz o mesmo resultado que realizá-la uma única vez. Na Ticto API, isso é essencial para lidar com falhas de rede: se uma requisição POST não receber resposta (timeout, queda de conexão, etc.), você pode reenviá-la com segurança usando a mesma chave, sem risco de criar produtos ou ofertas duplicados na sua conta.

## Como funciona

Toda requisição `POST` para a Ticto API exige o header `Idempotency-Key` contendo um **UUID v4**. O comportamento é o seguinte:

* Na **primeira** chamada com uma chave, a API processa a requisição normalmente e armazena a resposta vinculada àquela chave.
* Em chamadas **subsequentes** com a mesma chave, a API devolve exatamente a mesma resposta da primeira chamada (**o mesmo status**, `201` no caso de criação), acrescida do header `Idempotent-Replay: true`, sem reprocessar a operação. Não é um erro.
* O escopo da chave é **por token**: chaves de outros produtores não interferem nas suas.

### Exemplo de requisição com Idempotency-Key

```bash theme={null}
curl -X POST https://api.ticto.cloud/api/v2/products \
  -H "Authorization: Bearer ticto_live_SUA_CHAVE_AQUI" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Curso de Marketing Digital",
    "type": "course",
    "description": "Curso completo do zero ao avançado."
  }'
```

## Replay: reenvio com a mesma chave

Quando a mesma `Idempotency-Key` é reenviada, a API **não reprocessa** a operação: ela devolve a resposta armazenada da primeira chamada, com o **mesmo status** e o **mesmo corpo**, apenas acrescentando o header `Idempotent-Replay: true`. Um `POST` de criação replayado responde `201` com o recurso original, não um erro.

```http theme={null}
HTTP/1.1 201 Created
Idempotent-Replay: true
Content-Type: application/json

{
  "object": "product",
  "id": "PMKT2024",
  "reference_id": 101,
  "name": "Curso de Marketing Digital",
  "type": "course",
  "status": "approved",
  "is_active": true,
  "created_at": "2024-07-15T10:30:00Z"
}
```

Detecte o replay pela presença do header `Idempotent-Replay: true` e trate a resposta como se fosse a original: o recurso já existe e nada novo foi criado.

<Warning>
  Use um UUID único por operação lógica. Reutilizar a mesma chave para uma requisição **diferente** faz a API devolver a resposta armazenada da operação **original**, não a da nova, sem processá-la. Nunca reaproveite a chave entre recursos distintos.
</Warning>

## Boas práticas

* **Gere UUIDs v4 aleatórios** para cada nova operação. Não use identificadores previsíveis ou sequenciais.
* **Armazene a chave junto com a operação** em sua base de dados. Assim, em caso de falha, você pode recuperar a chave original para o retry.
* **Em retries, use a mesma chave** da tentativa original, que é exatamente o que garante a idempotência.
* **Não reutilize chaves entre recursos diferentes**: uma chave usada para criar um produto não deve ser reaproveitada para criar uma oferta.

## Gerando UUIDs

<CodeGroup>
  ```javascript JavaScript theme={null}
  // Node.js 14.17+ ou browsers modernos
  const idempotencyKey = crypto.randomUUID();
  // Exemplo: "3b5a6c2d-1f4e-4a8b-9c0d-e2f3a4b5c6d7"

  // Alternativa com biblioteca uuid
  import { v4 as uuidv4 } from 'uuid';
  const idempotencyKey = uuidv4();
  ```

  ```php PHP theme={null}
  // Com a biblioteca ramsey/uuid (recomendado)
  use Ramsey\Uuid\Uuid;

  $idempotencyKey = Uuid::uuid4()->toString();
  // Ex.: 3b5a6c2d-1f4e-4a8b-9c0d-e2f3a4b5c6d7
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.