Idempotency

Идемпотентность нужна, чтобы при сетевых сбоях и ретраях вы могли спокойно повторять запрос — мы вернём тот же результат, что и в первый раз, не создавая новый лид.

Заголовок

http

Idempotency-Key: <ваш-уникальный-id>

Длина: 1–80 байт.
Уникальность: в пределах вашего партнёра (мы изолируем ключи по affiliate_id).
Время жизни: 24 часа. После — ключ можно переиспользовать.

Что положить в ключ

Самое простое — <ваш partner_slug>-<external_id>-<retry_attempt>, например aff42-lead-001-r0. Главное — детерминированно на стороне отправителя.

Поведение

Первый запрос с ключом K:

Обрабатываем как обычно (валидация / дедуп / сохранение).
Запоминаем результат на 24 часа.
Возвращаем стандартный ответ.

Повторный запрос с тем же K (в окне 24 часов):

Не вызываем бизнес-логику повторно.
Возвращаем сохранённый результат с дополнительным полем replay: true.

json

{
  "id": "le-12345",
  "status": "accepted",
  "reason": null,
  "replay": true
}

Что считается «тем же ключом»

Сравнение строгое, byte-equal.
Тело запроса при повторе не сверяется с оригинальным — мы доверяем ключу. Это значит: если вы случайно отправили два разных payload с одним ключом, второй будет проигнорирован. Используйте уникальные ключи для уникальных лидов.

Без `Idempotency-Key`

Запрос отработает без идемпотентного слоя. Сетевые ретраи могут создать дубликаты — их поймает дедупликация по phone/email, но это не гарантировано (например, если лид прислан с разными телефонами по ошибке вашей системы).

Очень рекомендуем всегда отправлять Idempotency-Key

Это самый надёжный способ исключить race-condition'ы и двойные отправки. Минимальная цена интеграции — большая защита.

Совместная работа с дедупликацией

Сценарий	Что вернётся
Идемпотентный повтор, лид принят	прежний `accepted` ответ
Идемпотентный повтор, лид был дубликат	прежний `duplicate` ответ
Новый ключ, но `phone` совпал с прежним лидом	`duplicate` (новый ответ)
Новый ключ, новый лид	`accepted`

То есть idempotency защищает от ретраев одного и того же запроса, а дедупликация защищает от двух разных запросов с одним телефоном/email.

Idempotency ​

Заголовок ​

Поведение ​

Что считается «тем же ключом» ​

Без Idempotency-Key ​