Идемпотентность и apiid: безопасные повторы запросов к API
Сеть и серверы иногда подводят: запрос ушёл, а ответ не вернулся. Параметр apiid позволяет повторить отправку без риска создать второй лид. Разбираем, как он работает и как выбрать его значение.
Проблема, которую решает apiid
Представьте: ваш сервер отправил лид, сеть его приняла, но ответ потерялся по дороге, и ваш сервер получил таймаут. Что делать? Если не повторять, заявка может остаться неотправленной. Если повторить, можно создать дубль и потратить лимит или бюджет клиники впустую.
Идемпотентность решает это: повторный запрос с тем же идентификатором возвращает результат первого, а не создаёт новый лид. В API Лидпульта за это отвечает необязательный параметр apiid.
Как это работает
Вы передаёте в запросе apiid — идентификатор заявки в вашей системе. Сеть запоминает пару «ваш вебмастер плюс apiid» и номер созданного лида. Если приходит второй запрос с тем же apiid, лид заново не создаётся: в ответ возвращается тот же lead_id и признак duplicate_of_request: true.
// первый запрос
{ "status": "ok", "lead_id": 443110 }
// повтор с тем же apiid
{ "status": "ok", "lead_id": 443110, "duplicate_of_request": true }Признак в ответе говорит, что это повтор. Для вашей логики оба ответа означают успех: заявка в системе под номером 443110.
Чем apiid отличается от дубля по телефону
Это два разных механизма, которые легко перепутать.
| Механизм | Что проверяет | Результат |
|---|---|---|
| apiid | Повтор вашего собственного запроса | Тот же lead_id, успех |
| Дубль по телефону | Этот номер уже приходил по офферу за 30 дней | Ошибка duplicate, HTTP 409 |
Первый защищает вас от технических сбоев, второй защищает клинику от повторной оплаты за одного и того же человека. Повторять запрос после ошибки duplicate не нужно.
Как выбрать значение apiid
Хороший apiid уникален для заявки и не меняется при повторе. Варианты:
- номер заявки в вашей CRM или базе;
- идентификатор клика из трекера, если заявка создаётся один раз на клик;
- идентификатор формы или сессии, сгенерированный на странице при загрузке.
Не используйте телефон как apiid: если один человек оставит две заявки по разным офферам, вы потеряете вторую.
Алгоритм повтора
Правильная логика отправки с повторами такая:
- Сгенерируйте apiid один раз и сохраните его вместе с заявкой.
- Отправьте запрос с таймаутом, достаточным для ответа.
- При ответе 200 сохраните lead_id и закончите.
- При ответе 4xx запишите код ошибки и закончите: повтор не поможет.
- При сетевой ошибке, таймауте или 5xx повторите запрос с тем же apiid через паузу, увеличивая её.
- После нескольких неудач переведите заявку в очередь на ручную проверку.
for (attempt = 1; attempt <= 5; attempt++) {
res = send(lead, apiid) // один и тот же apiid
if (res.ok) break // 200
if (res.status < 500 && res.status != 0) break // 4xx
sleep(2 ** attempt) // пауза растёт
}Внутренняя защита от гонок
Сеть проверяет лимит и дубль атомарно: при одновременных заявках лимит не превышается. Для вас это значит, что можно безопасно отправлять лиды параллельно из нескольких потоков. Но защиту от повтора одной и той же заявки по-прежнему обеспечивает apiid, а не атомарность лимита.
Типичные ошибки
- apiid не передаётся вовсе, и сбой сети приводит к лишнему лиду.
- apiid берётся из времени отправки и меняется при каждой попытке.
- Один и тот же apiid используется для разных заявок, поэтому вторая заявка «склеивается» с первой.
- Повторяют запрос после 4xx, расходуя время и засоряя журнал.
Подробнее о кодах ответа читайте в статье про документацию, а о защите клиники от повторных заявок в правилах трафика.
Пример отказоустойчивой отправки с очередью
Для небольших проектов хватает повторов в одном процессе, но стабильнее поставить между формой и сетью очередь. Заявка записывается в вашу базу со статусом «ожидает отправки» и генерированным apiid. Отдельный обработчик берёт заявки из очереди, отправляет их и обновляет статус. Если обработчик упал на середине, после перезапуска он снова возьмёт заявку и отправит её с тем же apiid: новый лид не появится, а потерянной заявки не будет.
Такая схема особенно полезна в часы пиковых нагрузок, когда сеть отвечает дольше обычного, а пациенты нажимают на кнопку повторно. Вы принимаете заявку мгновенно, показываете пользователю подтверждение и спокойно отправляете в сеть в фоне.
Как проверить, что защита работает
Проверка занимает минуту. Отправьте запрос с apiid вроде test-idem-001, получите lead_id. Повторите тот же запрос и убедитесь, что вернулся тот же lead_id и признак duplicate_of_request: true. Затем откройте кабинет и убедитесь, что заявка там одна. Не отправляйте тестовые заявки с вымышленными номерами на живые офферы клиник без согласования с менеджером: это создаёт нагрузку на колл-центр и нарушает правила трафика.
Идемпотентность и постбэк
Идемпотентность относится к отправке лида, а не к постбэку, но эти механизмы дополняют друг друга. На стороне трекера повтор постбэка по тому же событию тоже должен быть безопасным: при получении второго запроса с тем же идентификатором клика и тем же статусом конверсия не должна создаваться заново. Так вы защищаетесь от двойного учёта, когда сеть повторила отправку из-за того, что ваш ответ потерялся по дороге. Сочетание apiid на входе и проверки на выходе даёт сквозную защиту от дублей в обе стороны.
Вопросы и ответы
Сколько хранится связка apiid и lead_id?
В документации срок хранения не указан, поэтому не полагайтесь на повтор через очень большой срок. Повторяйте отправку в разумных пределах, в пределах часов.
Что будет, если отправить тот же apiid с другим телефоном?
Не рассчитывайте на изменение данных: сеть вернёт уже созданный лид. Для новой заявки используйте новый apiid.
Нужен ли apiid для ручных проверок?
Нет, но он не повредит. Для тестов используйте значения вроде test-001, чтобы потом найти заявки по метке.
Приходит ли постбэк на повторный запрос?
Нет, повтор не создаёт нового лида, поэтому новых событий не возникает. Постбэки уходят при приёме лида и при смене его статуса.
Влияет ли повтор на дневной лимит?
Нет. Повтор с тем же apiid возвращает уже созданный лид и не занимает лимит заново, потому что новый лид не создаётся.