Как да получите най-новия статус на пратката чрез API, без да чакате webhook
За да получите най-новия наличен статус на пратката, без да чакате webhook, изпратете удостоверена заявка към API за справка с пратки на вашия доставчик на услуги за проследяване. Използвайте отговора, за да актуализирате приложението си незабавно, след което оставете webhook-ите активирани за последващи промени. Важното разграничение е, че заявката обикновено извлича най-новата съхранена информация за проследяване от доставчика; тя не задейства непременно нова проверка при превозвача.

Този подход е полезен, когато клиент отвори страница на поръчка, служител от поддръжката се нуждае от актуална информация или системата ви трябва да се възстанови след пропуснато известие. Надеждната реализация съчетава заявки при поискване, ясни индикатори за актуалност и защити срещу дублирани или получени в неправилен ред актуализации.
Определете какво означава „най-нов статус на пратката“
Преди да изберете endpoint, разграничете три операции, които могат да звучат сходно, но дават различни резултати.
| Операция | Какво прави | Какво не установява |
|---|---|---|
| Прочитане на собствената ви база данни | Връща информацията за проследяване, която приложението ви вече съхранява. | Дали доставчикът е получил по-нова актуализация. |
| Заявка към API за проследяване | Извлича информацията, налична чрез операцията за заявка на доставчика. | Дали по време на тази заявка е извършена нова проверка при превозвача. |
| Заявка за обновяване на проследяването | Заявява нова проверка нагоре по веригата, ако доставчикът предлага такава операция. | Че превозвачът има ново сканиране или че обновяването ще завърши синхронно. |
Използвайте заявка, когато ви е необходим отговор сега. Проучвайте операция за обновяване само когато е необходимо доставчикът да извърши нова проверка нагоре по веригата. Не приемайте, че добавянето на параметър за заобикаляне на кеша, повтарянето на заявка или изпращането на HTTP заглавка за контрол на кеша ще принуди превозвача да предостави нова информация.
Видимостта на пратката има няколко етапа: превозвачът записва събитие, доставчикът на проследяването го получава, а приложението ви го получава или извлича. Директната API заявка може да избегне чакането за доставка на известие, но не може да премахне забавянията по-рано в тази верига.
Проверете договора на заявката, преди да пишете код
Разработчикът, който интегрира услугата за проследяване, отговаря за този работен процес. Започнете с актуалната документация на доставчика, а не с endpoint, копиран от стар пример за интеграция. Потвърдете следните подробности:
- Идентичност на пратката: Приема ли заявката номер за проследяване, вътрешен идентификатор на пратката или номер за проследяване, комбиниран с идентификатор на превозвача?
- Изисквания за регистрация: Трябва ли пратката да бъде регистрирана, преди да може да бъде заявена?
- Удостоверяване: Коя заглавка или кой механизъм за удостоверяване е необходим?
- Значение на отговора: Връща ли операцията съхранена информация, започва ли събиране на данни или връща задача, която трябва да бъде проверена по-късно?
- Обработка на резултата: Може ли успешен HTTP отговор да съдържа грешка на ниво пратка или резултат в изчакване?
- Ограничения за използване: Какви ограничения за честотата, пакетите и конкретния акаунт се прилагат?
- Полета за актуалност: Кои времеви маркери представляват събитията на превозвача, актуализациите от доставчика и генерирането на отговора?
За интеграция с 17TRACK подходящият продукт е Tracking API, а не потребителска страница за проследяване или интерфейс за проследяване в онлайн магазин. Използвайте официалната API документация, за да потвърдите операцията за заявка на информация за проследяване, удостоверяването, полетата на заявката и структурата на отговора за вашата интеграция. Разглеждайте заявките и обработката на webhook-и като отделни пътища на приложението, които актуализират един и същ запис за пратката.
Избягвайте твърдо кодирани предположения за поведението при обновяване или честотата на заявките. Тези подробности трябва да съответстват на операцията и условията на услугата, която действително използвате.
Изградете справка при поискване чрез вашия backend
Практичен дизайн е да предоставите удостоверен endpoint в собственото си приложение. Браузърът заявява актуализация на пратката от този endpoint; сървърът ви проверява оторизацията, решава дали е необходима заявка към доставчика и връща нормализиран резултат.
Следващият маршрут е пример за endpoint, който бихте създали в приложението си. Това не е endpoint на 17TRACK или спецификация за заявка към доставчик.
GET /api/orders/{order_id}/shipment-statusИзползвайте идентификатора на поръчката, за да намерите пратката на сървъра. Не позволявайте на извикващия да извлича историята на проследяване на друг клиент само чрез замяна на номера за проследяване в заявка. Съхранявайте идентификационните данни за API на доставчика в backend-а си, а не в JavaScript кода на браузъра или в пакета на мобилното приложение.
Работен поток на заявка, който можете да реализирате
- Удостоверете достъпа. Потвърдете, че клиентът или служителят има право да вижда поръчката.
- Разрешете пратката. Прочетете съхранения идентификатор за проследяване и информацията за превозвача, когато е приложимо.
- Проверете локалната актуалност. Ако вече съществува скорошна успешна заявка, използвайте я повторно съгласно политиката за актуалност на приложението.
- Заявете доставчика при необходимост. Използвайте документираната операция и ограничен timeout на заявката.
- Валидирайте резултата. Проверете както HTTP резултата, така и резултата на ниво пратка.
- Обединете информацията. Прилагайте същите правила за нормализация и съгласуване, които използвате за събитията от webhook.
- Върнете статуса и актуалността. Когато е налично, включете времето на последното събитие и времето на последната успешна проверка при доставчика.
Политиката за локална актуалност е инженерно решение, а не твърдение за честотата на актуализациите от превозвача. Изберете я според изискванията на интерфейса, ограниченията на доставчика, обема на пратките и наблюдаваната полезност на заявките. Клиент, който многократно натиска бутон за актуализация, не трябва да създава неограничен поток от заявки нагоре по веригата.
Нормализирайте отговора, без да измисляте актуалност
Приложението ви може да връща стабилен вътрешен формат, дори когато структурите на отговорите на доставчиците се различават. Този илюстративен обект е ваш договор на приложението, а не действителен payload от доставчик:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}Попълвайте всеки времеви маркер само когато значението му е известно. Времето, когато сървърът ви е получил отговора, принадлежи към метаданните на заявката; то не трябва да се представя като времето, когато пратката се е придвижила. Ако доставчикът не предоставя времеви маркер за актуализация от доставчика, оставете това поле празно или null, вместо да замествате стойността с друг времеви маркер.
За клиентския интерфейс разделете съобщенията: „Последно събитие от превозвача“ описва активността по пратката, докато „Проследяването е проверено“ описва активността по извличане на данни от приложението ви. Това разграничение предотвратява представянето на непроменено сканиране като новозаписано.
Не позволявайте на API заявките и webhook-ите да презаписват взаимно данните си
След като и двата механизма са активни, едно и също събитие може да пристигне чрез заявка и webhook. Те могат също да завършат в различен ред от този, в който са започнали. Заявка, стартирана първа, може да завърши след като webhook вече е предоставил по-нова информация.
Не използвайте логика „последният отговор печели“. Най-скоро полученият payload не е непременно най-новото състояние на пратката.
- Използвайте един общ pipeline за актуализации. Изпращайте резултатите от заявките и payload-ите от webhook през едни и същи функции за валидация, нормализация и съхранение.
- Премахвайте дублираните събития. Предпочитайте документиран идентификатор на събитие. Ако такъв няма, изградете внимателно дефиниран отпечатък от налични полета като време на събитието, статус, местоположение и описание.
- Използвайте полета за подреждане с известно значение. Документирана ревизия или последователност е по-полезна от предположението, че времето на пристигане представлява реда на събитията.
- Запазвайте историята. Новополучено събитие може да попълни историческа празнина, без да променя текущото обобщение на пратката.
- Позволявайте корекции. Статусите не образуват универсална линейна стълбица. Следвайте документираното поведение при корекции, вместо постоянно да отхвърляте всеки привидно обратен преход.
Когато редът на събитията е несигурен, запазвайте оригиналния payload и неговия произход за разследване. Не разрешавайте двусмислието чрез измисляне на времеви маркер за събитие или чрез предположение, че всички времеви маркери на превозвачите използват една и съща часова зона.
Разграничете липсващите данни от неуспешните заявки
Празен резултат, непроменен резултат и неуспешна заявка не трябва да водят до едно и също съобщение към клиента.
Заявката е успешна, но статусът не се е променил
Запазете съществуващия статус на пратката и актуализирайте времето на последната успешна заявка. Не генерирайте ново събитие за пратката само защото друга справка е завършила. Ако клиентът се нуждае от повече подробности, покажете съществуващата история на събитията и обяснете, че не е върнато по-ново събитие за проследяване.
Пратката все още няма информация за проследяване
Проверете дали е необходима регистрация, дали идентификаторът и превозвачът са правилни и как доставчикът представя събирането на данни в изчакване. Липсата на събития сама по себе си не доказва, че номерът за проследяване е невалиден или че пратката е изгубена. Запазете разграничението на доставчика между неизвестен идентификатор, регистрирана пратка, очакваща информация, и заявка, която не е могла да бъде обработена.
Заявката към доставчика изтича или е неуспешна
Ако разполагате с предишен валиден статус, върнете го с изрично указание, че последната проверка не е била успешна. Запазете времето на по-ранната успешна заявка непроменено. Мрежова грешка не е изключение при доставката и не трябва да променя бизнес статуса на пратката.
Използвайте ограничен брой повторни опити с backoff и jitter за подходящи временни грешки. Не повтаряйте многократно заявки с невалидни идентификационни данни или неправилен формат. Когато отговорът предоставя Retry-After, интерпретирайте го съгласно договора на доставчика и HTTP семантиката. HTTP спецификацията позволява тази стойност да бъде изразена като забавяне в секунди или като HTTP дата.
Пристигат няколко заявки за една и съща пратка
Обединявайте едновременните справки, така че да споделят една заявка нагоре по веригата. Прилагайте ограничения по акаунт и пратка и предотвратявайте умножаването на автоматичните повторни опити през няколко слоя на приложението. Когато се поддържа пакетна обработка, проверявайте резултата за всяка пратка, вместо да приемате целия пакет за успешен само защото HTTP заявката е завършила.
Използвайте polling като контролиран резервен вариант
Без webhook-и планираният polling може да поддържа базата ви данни актуална, но изисква изрична оперативна политика. Определете кои пратки остават допустими, как неуспехите влияят върху графика и кога обичайният polling спира.
За повечето интеграции хибридният дизайн е разумна отправна точка: webhook-ите обработват фоновите промени, заявките при поискване обслужват интерактивните заявки, а задачите за съгласуване проверяват записите, които изискват внимание. Това е архитектурна препоръка, а не гаранция, че ще минимизира разходите за всеки акаунт.
- Приоритизирайте активните пратки и записите с неразрешени грешки при извличане.
- Избягвайте да заявявате всяка историческа пратка при всяко планирано изпълнение.
- Определете как се обработват завършените пратки, включително всеки период за корекции, необходим за бизнеса ви.
- Следете колко често заявките откриват действително нова информация.
- Проучвайте проблемите с доставката на webhook-и, вместо да ги прикривате с все по-чест polling.
Наблюдавайте забавянето на заявките към доставчика, неуспешните заявки, отговорите за ограничение на честотата и разликите между данните от заявките и записите, получени чрез webhook. Отделно наблюдавайте възрастта на последното събитие от превозвача. Успешните API отговори могат да съществуват едновременно с непроменена информация за проследяване.
Тествайте работния процес преди пускане
Успешната заявка е само първият тест. Проверете ситуациите, които иначе могат да създадат подвеждащи актуализации на статуса:
- Webhook пристига, докато заявка при поискване все още се изпълнява.
- Двама клиенти или служители заявяват една и съща пратка едновременно.
- Доставчикът връща HTTP успех, но съобщава грешка на ниво пратка.
- Заявка се проваля, след като приложението ви вече разполага с валидна информация за проследяване.
- На дадено събитие му липсва часова зона или съдържа непознат код на статуса.
- Корекция от превозвача променя вече показан резултат.
- Потребител се опитва да получи достъп до пратка, принадлежаща на друг акаунт.
Критерият ви за пускане трябва да бъде приложението да връща най-добрата известна информация за пратката, да обяснява точно нейната актуалност и да не поврежда тази информация, когато заявките се провалят или пристигат в неправилен ред.
ЧЗВ
Принуждава ли заявката към API превозвача да сканира или актуализира пратка?
Не. Извличането на информация за проследяване не може да предизвика физическо сканиране. Дали заявката задейства проверка нагоре по веригата зависи от документираната операция. Дори поддържано обновяване може да върне непроменена информация, ако превозвачът няма по-ново събитие.
Мога ли да използвам API заявки без конфигуриране на webhook-и?
Ако доставчикът поддържа необходимия работен процес за заявки, можете да изградите интеграция около заявки при поискване или polling. Първо потвърдете изискванията за регистрация и заявки. След това приложението ви ще отговаря за решението кога да проверява, контролирането на обема на заявките и откриването на промени.
Колко често трябва да проверявам статуса на пратката чрез polling?
Няма универсален интервал. Изберете график, който съответства на ограниченията на доставчика, обема на пратките и бизнес стойността на по-ранното откриване на актуализации. Измервайте колко често polling връща нови събития, след което коригирайте графика, вместо да приемате, че честите заявки осигуряват по-актуални данни от превозвача.
Защо API връща информация, която вече съм получил чрез webhook?
И двата пътя могат да предоставят един и същ базов запис за пратката. Webhook доставя известие, докато заявката извлича информация при поискване. Получаването на едно и също събитие и по двата пътя не е непременно грешка; приложението ви трябва да премахне дубликата.
Трябва ли бутонът за актуализация да гласи „Обновяване на проследяването“?
Само ако този текст точно описва операцията. Ако бутонът извлича съхранени данни от доставчика, „Проверка за актуализации“ е по-ясно. Показвайте последното събитие от превозвача отделно от времето, когато приложението ви последно е завършило успешна проверка.
Източници
- 17TRACK Tracking API — официален продуктов справочник за интеграцията с API за проследяване, разгледана в това ръководство.
- Документация за API на 17TRACK — справочник за специфичните за доставчика операции, удостоверяването, полетата на заявките и обработката на отговорите.
- RFC 9110, раздел 10.2.3: Retry-After — дефинира формите delay-seconds и HTTP-date на HTTP заглавката.


