Лидпульт
Трекеры и постбэки

Идемпотентность и apiid: безопасные повторы запросов к API

Сеть и серверы иногда подводят: запрос ушёл, а ответ не вернулся. Параметр apiid позволяет повторить отправку без риска создать второй лид. Разбираем, как он работает и как выбрать его значение.

· 5 мин чтения

Проблема, которую решает 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: если один человек оставит две заявки по разным офферам, вы потеряете вторую.

Алгоритм повтора

Правильная логика отправки с повторами такая:

  1. Сгенерируйте apiid один раз и сохраните его вместе с заявкой.
  2. Отправьте запрос с таймаутом, достаточным для ответа.
  3. При ответе 200 сохраните lead_id и закончите.
  4. При ответе 4xx запишите код ошибки и закончите: повтор не поможет.
  5. При сетевой ошибке, таймауте или 5xx повторите запрос с тем же apiid через паузу, увеличивая её.
  6. После нескольких неудач переведите заявку в очередь на ручную проверку.
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 на входе и проверки на выходе даёт сквозную защиту от дублей в обе стороны.

Вопросы и ответы

Сколько хранится связка apiid и lead_id?

В документации срок хранения не указан, поэтому не полагайтесь на повтор через очень большой срок. Повторяйте отправку в разумных пределах, в пределах часов.

Что будет, если отправить тот же apiid с другим телефоном?

Не рассчитывайте на изменение данных: сеть вернёт уже созданный лид. Для новой заявки используйте новый apiid.

Нужен ли apiid для ручных проверок?

Нет, но он не повредит. Для тестов используйте значения вроде test-001, чтобы потом найти заявки по метке.

Приходит ли постбэк на повторный запрос?

Нет, повтор не создаёт нового лида, поэтому новых событий не возникает. Постбэки уходят при приёме лида и при смене его статуса.

Влияет ли повтор на дневной лимит?

Нет. Повтор с тем же apiid возвращает уже созданный лид и не занимает лимит заново, потому что новый лид не создаётся.