Обработка статуса «выполняется» при проверке заказа через 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://<API_HOST>/orders/<EXTERNAL_ORDER_ID>/status" \

-H "Authorization: Bearer <API_TOKEN>" \

-H "Accept: application/json"

Пример ответа:

{

"order_id": "<EXTERNAL_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://<API_HOST>/orders/status" \

-H "Authorization: Bearer <API_TOKEN>" \

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

-d '{"order_id":"<EXTERNAL_ORDER_ID>"}'

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

Пакетный запрос активных заказов

Если API поддерживает пакетную проверку, отправляйте несколько ID одним запросом:

curl -X POST "https://<API_HOST>/orders/statuses" \

-H "Authorization: Bearer <API_TOKEN>" \

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

-d '{"order_ids":["<ORDER_ID_1>","<ORDER_ID_2>"]}'

Сопоставляйте ответ с внутренним заказом по внешнему 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": "<EXTERNAL_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.