Idempotency, paginación y rate limits

Idempotency-Key (POST /orders)

POST /orders requiere el header Idempotency-Key — es el único endpoint con soporte de idempotencia. Si tu sistema reintenta el mismo request (ej. después de un timeout), pasá el mismo key y la API devuelve el mismo response sin crear un duplicado. El resto de los endpoints de escritura no leen este header.

Cómo elegir el key

Cualquier string único hasta 255 chars. Recomendado: UUID v4.

curl -H "Authorization: Bearer tk_live_..." \
     -H "Idempotency-Key: $(uuidgen)" \
     -H "Content-Type: application/json" \
     -X POST https://ciervo.tikra.com.ar/api/v1/portal/orders \
     -d '{"destinatario_id":"...","items":[...]}'

Comportamiento

• Mismo key + mismo body → mismo response (cacheado por 24h).
• Mismo key + body distinto → 409 idempotency/key-reused-with-different-body. Generá un key nuevo.
• Mismo key después de 24h → request se procesa como nuevo.

Paginación cursor-based

Endpoints que devuelven listas usan paginación por cursor:

{
  "data": [...],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0wOVQxMjowMDowMFoiLCJpZCI6ImFiYyJ9",
  "has_more": true
}

Para la siguiente página: ?cursor=<next_cursor>. Cuando has_more es false, llegaste al final.

limit es opcional (default 50, máx 100).

Rate limits

Per API key, sliding window:

Headers en cada response:

• X-RateLimit-Limit — el tier limit que aplica al request
• Retry-After (sólo en 429) — segundos a esperar

Si recibís 429, hacé backoff exponencial.