Ідемпотентність

Мережа може обірватися посеред запиту. Будь-який запит на запис можна безпечно повторити, тож гість ніколи не отримає кешбек двічі за один чек.

Чеки та візити: 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 для всіх повторів однієї операції. Нове значення означає нову операцію.