Idempotencia

La red puede fallar en mitad de una llamada. Cualquier escritura se puede reintentar sin riesgo, así que un cliente nunca recibe cashback dos veces por el mismo ticket.

Tickets y visitas: external_id

POST /v1/transactions y POST /v1/visits exigen external_id: tu propio id del ticket o de la visita. Aplicamos cada external_id una sola vez por local. Si lo vuelves a enviar, recibes 200 con el resultado guardado en lugar de 201, y la tarjeta no cambia. Esto vale para siempre, no solo durante un día, así que puedes reenviar un turno entero después de que la caja haya estado sin conexión.

Todo lo demás: Idempotency-Key

Para el resto de escrituras (inscribir a un socio, canjear una recompensa, crear un plato) envía una cabecera Idempotency-Key con un valor único, por ejemplo un UUID que generes antes del primer intento. Guardamos la respuesta durante 24 horas. Un reintento con la misma clave y el mismo cuerpo devuelve esa respuesta con la cabecera Idempotent-Replayed: true. La misma clave con otro cuerpo se rechaza con 409 idempotency_key_reused.

curl

curl https://loyaltyfy.io/api/v1/members \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f6d1c0a-9b0e-4d2b-8e57-enrol-77" \
  -d '{ "phone": "+37366791102", "first_name": "Ion", "consent": true }'

# repeat the same call: same body, same status, plus the header
# Idempotent-Replayed: true

Cómo reintentar

Reintenta ante errores de red, tiempos de espera agotados, 429, 500, 502 y 503. No reintentes otros 4xx: la respuesta no va a cambiar.
Espera antes de cada reintento y alarga la espera cada vez, por ejemplo 1, 2, 4 y 8 segundos.
Mantén el mismo external_id o Idempotency-Key en todos los reintentos de una operación. Un valor nuevo es una operación nueva.