Як налаштувати повідомлення про завершення 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. Ця перевірка не замінює вебхуки, але допомагає виявити пропущену подію, збій черги або випадок, коли зовнішній статус змінився без коректного повідомлення.