Как настроить уведомления о завершении API-заказов

Какие события считать завершением заказа

Сначала зафиксируйте, какой статус в API означает фактическое завершение заказа. У разных поставщиков это могут быть выполненный, доставленный, отменённый, отклонённый, возвращённый или частично выполненный заказ. Не привязывайте автоматизацию только к слову «успех»: заказ может пройти несколько промежуточных состояний, а затем остановиться из-за лимита, проверки или отмены.

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

Составьте таблицу соответствия статусов

Не передавайте статус API в интерфейс без обработки. Названия и логика поставщика могут измениться, а один и тот же внутренний статус иногда объединяет несколько внешних. Храните исходное значение отдельно: оно пригодится для разбора ошибок и сверки с документацией.

• pending, created, queued — новый или ожидающий обработки заказ.
• processing, in_progress, running — заказ выполняется.
• completed, delivered, success — выполненный заказ.
• partial, partially_completed — частично выполненный заказ.
• cancelled, rejected, failed — отменённый или завершившийся ошибкой заказ.
• refunded, returned — заказ требует возврата или корректировки.
• Неизвестный статус — не меняет карточку автоматически и передаётся на проверку.

Названия выше приведены как пример схемы. Окончательную таблицу нужно строить по статусам конкретного API. Недостаток ручного маппинга в том, что после обновления API его нужно поддерживать: новый статус может попасть в обработчик раньше, чем появится правило для него.

Выберите вебхуки, опрос API или обе схемы

Вебхук — это запрос от сервиса на ваш URL при смене статуса заказа. Опрос API работает наоборот: ваша система через интервал запрашивает информацию о заказе. Для уведомлений о завершении обычно удобнее вебхуки, потому что обновление приходит без постоянных запросов к методу проверки статуса.

• Вебхуки подходят для быстрой реакции: обновления карточки, запуска следующего этапа или отправки сообщения ответственному.
• Опрос подходит, если поставщик не поддерживает callback-уведомления или сервер не принимает внешние запросы.
• Комбинированная схема использует вебхуки как основной канал, а опрос — для поиска пропущенных или зависших заказов.

Недостаток опроса — задержка и лишняя нагрузка на API. Недостаток вебхуков — нужно защитить endpoint, учитывать дубли и не полагаться на порядок доставки событий.

Настройте endpoint для приёма событий

Для уведомлений нужен публичный HTTPS-адрес, доступный со стороны API-сервиса. В настройках интеграции обычно указывают URL обработчика, секрет подписи и список событий: изменение статуса, завершение, отмена, ошибка или частичное выполнение.

Выделите отдельный маршрут только для API-событий. Так проще настроить журналирование, ограничить доступ, задать лимиты запросов и не смешивать служебный трафик с формами сайта. Не используйте адрес тестовой среды для рабочих заказов: после обновления окружения поставщик продолжит отправлять события по сохранённому URL.

До запуска проверьте метод запроса и формат тела по документации. Чаще всего это POST с JSON, но встречаются form-data, query-параметры или собственная схема сериализации. Ошибку разбора нужно записывать в журнал, иначе будет сложно отличить неверный payload от сбоя приложения.

Сохраняйте связь между заказом и событием

При создании заказа через API сохраняйте идентификатор, который вернул поставщик. Рядом храните внутренний номер заказа, тип услуги, исходный статус, время последнего изменения и исходный ответ API в безопасном виде. Входящий вебхук сопоставляйте по ID поставщика, а не по ссылке на канал, названию услуги или имени клиента.

Если API разрешает передавать внешний идентификатор при создании, добавляйте свой номер заказа в поле вроде external_id или client_reference. Это упрощает поиск в логах и разбор спорных ситуаций. Но не делайте внешний номер единственным ключом: часть поставщиков не возвращает его в каждом уведомлении.

Не создавайте новый заказ по неизвестному ID из вебхука. Неизвестное событие нужно сохранить в журнал и проверить отдельно. Автоматическое создание записи может привести к ошибочным данным или обработке поддельного запроса.

Используйте понятную структуру payload

Точные названия полей зависят от API. Ниже не контракт конкретного сервиса, а пример JSON-события, на который можно ориентироваться при проектировании внутреннего обработчика. Важны идентификатор события, ID заказа у поставщика, статус, время изменения и данные для диагностики.

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

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

Проверяйте подпись по исходному телу запроса

Открытый URL обработчика может получить запрос не только от API-сервиса. Если поставщик передаёт подпись, секрет или токен, проверяйте их до изменения заказа. Распространённая схема — HMAC-SHA256: поставщик вычисляет подпись из байтов тела запроса и общего секрета, а затем передаёт результат в HTTP-заголовке.

Принцип вычисления выглядит так: берётся исходное тело запроса, например байты JSON без изменений, и секрет интеграции. Затем вычисляется HMAC-SHA256. Если результат в шестнадцатеричном виде совпадает со значением заголовка, тело не менялось после подписи и запрос, вероятно, отправлен стороной, знающей секрет.

Условный пример: HMAC_SHA256(секрет, raw_body) = подпись из заголовка X-Signature. Название заголовка, алгоритм и формат результата нужно брать только из документации API. Некоторые сервисы добавляют временную метку или ID события в строку для подписи. В этом случае нельзя проверять только JSON-тело.

Не меняйте JSON до проверки подписи

Подпись проверяют по исходным байтам запроса, а не по объекту JSON, который приложение уже разобрало и собрало заново. При повторной сериализации может измениться порядок полей, пробелы, экранирование символов, перевод строки или кодировка. Для человека JSON останется тем же, но набор байтов изменится, и HMAC уже не совпадёт.

Чтобы этого избежать, сначала получите raw body как bytes или buffer, сохраните его в памяти, вычислите подпись и только после успешной проверки разбирайте JSON. Не применяйте к телу trim, преобразование кодировки, сортировку ключей и форматирование. В middleware фреймворка проверьте, не разбирается ли JSON автоматически до доступа к исходному телу.

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

Пример обработчика с проверкой HMAC

Ниже условный пример на Python. Он показывает порядок действий, а не готовую интеграцию: заголовки, алгоритм, формат подписи и поля payload нужно заменить на значения из документации поставщика.

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

Для сравнения используйте функцию, которая не прекращает работу на первом несовпавшем символе. Это снижает риск утечки данных о подписи через время ответа. Секрет не передавайте в клиентский код, не добавляйте в URL и не записывайте целиком в логи.

Делайте обработку событий идемпотентной

Поставщик может доставить одно и то же событие несколько раз. Причины обычные: ваш сервер долго отвечал, соединение оборвалось после сохранения данных, endpoint временно вернул ошибку или сервис запустил повторную доставку по своим правилам. Повтор не означает, что API создал новый заказ.

Идемпотентность означает, что одинаковое событие меняет результат только один раз. Если не учесть это правило, дубликат повторно отправит сообщение клиенту, создаст несколько задач менеджеру, начислит компенсацию или запустит повторную операцию.

Лучше всего использовать event_id из payload. Сохраняйте его в отдельной таблице или журнале обработанных событий с уникальным ограничением. Если отдельного ID нет, формируйте ключ из стабильных полей: ID заказа поставщика, типа события, статуса и времени изменения. Такой вариант хуже: при неточных временных метках разные события могут выглядеть одинаково.

Сохраняйте событие и статус в одной операции

Проверка «обработано ли событие» и запись результата должны выполняться атомарно. Иначе два одинаковых запроса, пришедшие одновременно, оба увидят отсутствие записи и запустят действие дважды. Практичный вариант — уникальный индекс по event_id и транзакция базы данных.

Условное продолжение обработчика выглядит так:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

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

Учитывайте нарушение порядка событий

Вебхуки не всегда приходят строго по времени изменения статуса. Сначала может поступить событие о завершении, а потом — задержавшееся уведомление о статусе «в работе». Если просто записывать последнее полученное значение, выполненный заказ снова станет активным.

Задайте разрешённые переходы. Например, промежуточный статус не может перезаписать финальный, а отменённый заказ не переводится в выполненный без отдельной проверки. Если API допускает корректировку финального статуса, сохраняйте причину, исходное значение и источник изменения.

Если payload содержит время изменения заказа, сравнивайте именно его, а не время получения вебхука. Когда API не передаёт такую метку, используйте приоритеты состояний и сверку через метод получения заказа. Недостаток приоритетов — они не заменяют реальную последовательность, особенно если поставщик разрешает возврат из финального статуса.

Быстро подтверждайте доставку и выносите действия в очередь

Не выполняйте долгие операции до ответа поставщику. Проверку подписи, поиск заказа, запись события и обновление статуса обычно можно завершить быстро. Отправку сообщения, синхронизацию с CRM, формирование отчёта или запросы к сторонним системам лучше передать в очередь задач.

Рабочий порядок такой: проверить подпись, атомарно сохранить событие и смену статуса, вернуть успешный ответ, затем выполнить вторичные действия. Если ответить раньше сохранения, при сбое данные потеряются. Если отвечать после долгой отправки уведомления, поставщик может посчитать доставку неуспешной и отправить дубликат.

Недостаток очереди — появляется отдельный компонент, который нужно контролировать: ошибки задач, задержки и повторные запуски. Зато сбой в уведомлении менеджера не блокирует приём статусов заказов.

Настройте уведомления для команды и клиента

После смены статуса не нужно уведомлять всех одинаково. Менеджеру обычно важны отмены, ошибки, частичное выполнение и заказы, которые долго не меняются. Клиенту чаще достаточно понятного итога: заказ выполнен, отменён или требует уточнения.

• Завершённый заказ — обновление в личном кабинете или краткое сообщение клиенту.
• Ошибка выполнения — уведомление ответственному с причиной, которую передал API.
• Частичное выполнение — задача на проверку корректировки, возврата или следующего действия.
• Неизвестный статус — запись в журнал и сообщение техническому специалисту.
• Неизвестный ID заказа — отдельная проверка связки между вашей системой и поставщиком.

Не отправляйте сообщение при каждом техническом переходе. Лента быстро превратится в шум, а важная проблема останется незамеченной. Внутреннее уведомление должно содержать номер заказа, услугу, текущий статус, внешний ID и ссылку на карточку.

Ведите журнал и сверяйте незавершённые заказы

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

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

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