Idempotência

​

Como funciona

• 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

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

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"
}

​

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

// 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();

// Com a biblioteca ramsey/uuid (recomendado)
use Ramsey\Uuid\Uuid;

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