Идемпотентность

Сеть может оборваться посреди запроса. Любой запрос на запись можно безопасно повторить, и гость никогда не получит кэшбэк за один чек дважды.

Чеки и визиты: external_id

POST /v1/transactions и POST /v1/visits требуют external_id: ваш собственный id чека или визита. Каждый external_id применяется в заведении один раз. При повторной отправке вы получите 200 с сохранённым результатом вместо 201, а на карте ничего не изменится. Это работает бессрочно, а не одни сутки, поэтому после простоя кассы можно спокойно переотправить всю смену.

Остальные запросы: Idempotency-Key

Для остальных запросов на запись (регистрация участника, выдача награды, создание блюда) передавайте заголовок Idempotency-Key с уникальным значением, например UUID, сгенерированным до первой попытки. Мы храним ответ 24 часа. Повтор с тем же ключом и тем же телом вернёт этот ответ с заголовком Idempotent-Replayed: true. Тот же ключ с другим телом будет отклонён с ошибкой 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

Как повторять запросы

Повторяйте запрос при сетевых ошибках, таймаутах, 429, 500, 502 и 503. Другие 4xx не повторяйте: ответ не изменится.
Делайте паузу перед каждым повтором и увеличивайте её, например 1, 2, 4, 8 секунд.
Во всех повторах одной операции используйте тот же external_id или Idempotency-Key. Новое значение означает новую операцию.