Idempotency, paginación y rate limits

Idempotency-Key (writes)

POST /orders y otros endpoints write requieren el header Idempotency-Key. Si tu sistema reintenta el mismo request (ej. después de un timeout), pasá el mismo key — la API devuelve el mismo response sin crear un duplicado.

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://app.tikra.com/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.