Обробка статусу «виконується» під час перевірки замовлення через API

Що означає processing у відповіді API

Статус processing, in_progress або інший рівнозначний стан означає, що постачальник прийняв замовлення в роботу, але не зафіксував підсумок. Для послуг просування це може бути перевірка посилання, очікування черги, запуск завдання або поступова видача замовленого обсягу.

Processing не підтверджує успішне виконання і не означає помилку. Після нього замовлення може перейти в completed, partial, canceled або failed. Поки постачальник повертає проміжний статус, не створюйте повторну заявку на те саме посилання і той самий обсяг.

HTTP 200 зі статусом processing означає успішну відповідь API, а не успішне завершення замовлення. Ці події потрібно зберігати й обробляти окремо.

Які дані потрібні для перевірки замовлення

Для polling потрібен зовнішній ID замовлення, який повернув постачальник під час створення. Збережіть його разом із внутрішнім ID, початковим обсягом, параметрами послуги, посиланням, часом створення та початковою відповіддю API. Шукати замовлення за назвою каналу, посиланням або обсягом ненадійно: такі значення можуть збігатися у кількох заявок.

Якщо після створення прийшов тайм-аут, не надсилайте заявку повторно автоматично. Постачальник міг прийняти запит, а відповідь могла загубитися в дорозі. Спершу скористайтеся методом пошуку замовлення, якщо він є в документації, або передайте випадок на перевірку.

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

Приклад запиту статусу через curl

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

GET-запит для одного замовлення

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

Приклад відповіді:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "значення_часу"

}

Поля completed_quantity і remains наведено лише як приклад структури. Постачальник може використовувати progress, start_count, balance або інші назви. Недолік GET-підходу в тому, що частина API приймає перевірку статусу лише через POST.

Приклад POST-запиту та пакетної перевірки

POST-запит статусу одного замовлення

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

Не передавайте API-ключ у рядку URL. Адреси запитів потрапляють у журнали проксі, системи аналітики, історію браузера та технічні логи. Недолік POST у тому, що його складніше вручну перевірити через адресний рядок, але це не причина переносити секрет в URL.

Пакетний запит активних замовлень

Якщо API підтримує пакетну перевірку, надсилайте кілька ID одним запитом:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

Зіставляйте відповідь із внутрішнім замовленням за зовнішнім ID, а не за позицією елемента в масиві. Недолік пакетної перевірки: постачальник може повернути не всі замовлення, обмежити розмір списку або повідомити помилку лише для одного ID.

Як призначати polling для processing

Після першої відповіді processing поставте наступну перевірку в чергу. Інтервал обирайте за документацією API, обмеженнями частоти та характером послуги. Для завдань, де статус змінюється швидко, допустима частіша перевірка на початку. Для поступового просування постійні короткі запити зазвичай не дають нової інформації.

Практична схема — збільшувати паузу після однакових відповідей processing. Перша перевірка відбувається після стартової затримки, далі інтервал зростає до встановленого максимуму. Якщо API повертає прогрес або новий час оновлення, відлік можна починати від цієї зміни.

• Після створення замовлення не перевіряйте статус одразу багато разів поспіль: сервісу може знадобитися час на постановку в чергу.
• За повторюваного processing збільшуйте інтервал між запитами, а не тримайте постійну частоту.
• Додавайте невелике випадкове відхилення до часу запуску завдань, щоб замовлення не опитували API одночасно.
• Якщо постачальник передає Retry-After або аналогічну рекомендацію, використовуйте її як пріоритетну.
• Для замовлень із вебхуками залишайте контрольний polling: повідомлення може не дійти.

Недолік рідкісного polling — інтерфейс може показувати старий статус після фактичного завершення. Недолік надто частого polling — ризик упертися в ліміти API, отримати 429 і створити зайве навантаження.

Які часи зберігати для контролю processing

Щоб відрізнити звичайне виконання від зависання, недостатньо одного поточного статусу. Для кожного активного замовлення зберігайте час створення, перше отримання processing, останню успішну відповідь API, останню зміну зовнішнього статусу та останню зміну прогресу.

Також корисно зберігати початковий обсяг, підтверджений виконаний обсяг, залишок і оригінальний статус постачальника. Якщо API не віддає прогрес, це не привід вважати замовлення завислим: орієнтуйтеся на час останньої відповіді та очікуваний період обробки, якщо він указаний в умовах послуги.

Максимальний час очікування не можна задавати одним числом для всіх послуг. Використовуйте строк, який постачальник указує для конкретної послуги, із внутрішнім запасом на чергу та оновлення даних. Якщо строк не вказано, задайте окреме правило для кожної категорії послуг і переглядайте його за історією фактичної обробки.

Що робити, якщо processing не змінюється

Тривалий processing не доводить помилку. Спершу перевірте, чи надходили успішні відповіді API, чи змінювалися completed_quantity або remains, чи були вебхуки і чи не змінилися правила послуги. Відсутність видимого зростання може бути пов'язана із затримкою статистики майданчика або з тим, що постачальник оновлює прогрес лише у фіналі.

Коли внутрішній строк очікування перевищено, не скасовуйте замовлення автоматично. Виконайте позачергову перевірку статусу, запитайте дані окремим методом, якщо він передбачений, і перевірте історію повідомлень. Якщо постачальник усе ще підтверджує processing, переведіть замовлення у внутрішній стан «потрібна перевірка», але збережіть зовнішній статус без підміни.

• Зафіксуйте час останньої підтвердженої відповіді та всю відповідь API.
• Перевірте, чи не змінився прогрес із моменту попереднього опитування.
• Знизьте частоту автоматичних запитів після досягнення внутрішнього порогу.
• Передайте в підтримку зовнішній ID, посилання, параметри послуги, історію статусів і технічні помилки.
• Не запускайте залишок повторно до відповіді постачальника або явного фінального статусу.

Недолік ручної перевірки — замовлення потребує уваги підтримки. Але автоматичне скасування або дубль небезпечніші: виконання може тривати в постачальника.

Як відокремлювати збій запиту від статусу замовлення

Помилка мережі, тайм-аут, HTTP 429 і відповідь 5xx не повідомляють стан самого замовлення. Вони означають лише те, що новий достовірний статус отримати не вдалося. У такій ситуації залишайте останній підтверджений статус, записуйте технічну помилку та плануйте нову перевірку.

При 429 враховуйте Retry-After, якщо заголовок передано. При тимчасових помилках мережі та 5xx збільшуйте паузу між спробами. При помилці авторизації, підпису або прав доступу не ставте часті ретраї: потрібно перевірити ключ, строк дії токена, IP-обмеження та налаштування доступу.

Якщо API повернув HTTP 200, але JSON не розбирається або у відповіді немає order_id і status, збережіть тіло відповіді повністю і позначте перевірку як некоректну. Не замінюйте відсутність статусу на completed, canceled або processing.

Коли припиняти автоматичні повторні запити

Polling не повинен бути нескінченним. Обмежте кількість технічних повторів для тимчасових помилок і окремо контролюйте загальний строк перебування замовлення в processing. Після вичерпання ліміту ретраїв переведіть завдання перевірки в чергу розбору, а не створюйте нові запити щохвилини без результату.

Повтор запиту статусу зазвичай безпечний, якщо метод лише читає дані. Методи створення, скасування, поповнення, перезапуску та повернення не можна повторювати механічно після тайм-ауту. Без ідемпотентного ключа або явного підтвердження постачальника такий повтор може змінити замовлення двічі.

Недолік обмеження ретраїв у тому, що частина оновлень стане ручним завданням. Нескінченні ретраї гірші: вони маскують збій, витрачають ліміти та ускладнюють розбір журналів.

Як приймати фінальний статус після processing

Не допускайте зворотного переходу з completed у processing через пізню polling-відповідь або старий вебхук. Під час кожного оновлення порівнюйте час події від постачальника, порядковий номер версії, якщо він є, і поточний внутрішній стан.

• new і pending можуть перейти в processing, canceled або failed.
• processing може перейти в completed, partial, canceled або failed.
• partial не потрібно автоматично вважати completed.
• completed, canceled і failed зазвичай вважаються фінальними і блокують автоматичне повернення назад.
• Невідомий статус або недопустимий перехід потребують окремої перевірки.

Жорстка таблиця переходів теж має недолік: постачальник може додати коректний новий стан. Тому зберігайте оригінальний статус і не затирайте його внутрішньою класифікацією.

Як обробляти partial і залишок замовлення

Partial означає, що підтверджено лише частину початкового обсягу. У відповіді API можуть бути фактично виконана кількість, залишок, причина та дані про компенсацію. Ці значення зберігайте окремо: початковий обсяг замовлення не можна замінювати виконаною кількістю.

Приклад фінальної відповіді може виглядати так:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "значення_або_відсутність_поля"

}

Спершу визначте, що саме підтверджує API: повернення вже проведено, повернення лише заплановано, залишок скасовано або потрібне звернення до підтримки. Якщо поля про повернення немає, не вважайте залишок компенсованим автоматично.

Не перезапускайте невиконану частину без окремого рішення. Постачальник може ще завершувати розрахунок, статистика майданчика може оновлюватися із затримкою, а повторна заявка здатна створити дублювальне просування. Недолік очікування підтвердження — залишок не буде закрито миттєво, зате не з'явиться зайве замовлення.

Вебхуки не замінюють контрольну перевірку

Вебхук дозволяє оновити картку замовлення одразу після події, не чекаючи наступного polling. В обробнику знайдіть замовлення за зовнішнім ID, перевірте підпис або секрет, збережіть ID події та застосуйте перехід лише після перевірки допустимості.

Повторна доставка вебхука має бути безпечною: ту саму подію не можна вважати новою зміною. Події також можуть надходити не по порядку, тому не переводьте фінальне замовлення назад лише на підставі пізнього processing.

Контрольний polling потрібен навіть за стабільних вебхуків. Недолік вебхуків — складніше налаштування: потрібен доступний обробник, захист від підроблених запитів, дедуплікація та журнал подій.

Що показувати клієнту при processing і зависанні

В інтерфейсі не потрібно виводити весь технічний JSON. Для processing достатньо стану «замовлення в роботі». Якщо API передав достовірний прогрес, показуйте підтверджений обсяг окремо від початкового і не видавайте його за остаточний результат.

Для замовлення, яке перевищило внутрішній строк контролю, використовуйте зрозумілий стан на кшталт «перевіряємо виконання». Не повідомляйте про скасування, повернення або повне завершення, поки це не підтверджено відповіддю постачальника.

Повідомлення корисні при прийнятті замовлення, фінальному виконанні, partial, скасуванні, помилці та необхідності перевірки. Повідомлення після кожного polling створюють шум і не допомагають клієнту зрозуміти реальний стан заявки.

Які записи потрібні в журналі обробки

Історія відповідей допомагає розібрати завислий processing, втрачений вебхук, спір щодо часткового виконання та розбіжність між інтерфейсом і API. Для кожного звернення зберігайте зовнішній ID, джерело оновлення, час запиту та відповіді, HTTP-код, оригінальний статус, нормалізований статус, прогрес, залишок і текст технічної помилки.

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

Перед запуском перевірте сценарії з повторюваним processing, відсутністю прогресу, тайм-аутом, 429, помилкою 5xx, некоректним JSON, пізнім вебхуком, duplicate-вебхуком, partial, canceled і невідомим статусом. Тестовий режим корисний для структури інтеграції, але його недолік у тому, що він може не повторювати реальні черги та затримки робочого API.