Како да го добиете најновиот статус на пратката преку API без да чекате на webhook
За да го добиете најновиот достапен статус на пратката без да чекате webhook, испратете автентификувано барање до API-то на вашиот провајдер за пребарување пратки. Користете го одговорот веднаш да ја ажурирате апликацијата, а потоа оставете ги webhook-овите овозможени за последователни промени. Важната разлика е што пребарувањето обично ги презема најновите зачувани информации за следење од провајдерот; тоа не значи нужно дека ќе започне нова проверка кај превозникот.

Овој пристап е корисен кога клиентот отвора страница со нарачка, кога агентот за поддршка има потреба од ажурирање или кога системот треба да се опорави од пропуштено известување. Сигурната имплементација комбинира пребарувања на барање, јасни индикатори за свежина и заштити од дупликати или ажурирања по погрешен редослед.
Одредете што значи „најнов статус на пратката“
Пред да изберете endpoint, разликувајте ги трите операции што можат да звучат слично, но да дадат различни резултати.
| Операција | Што прави | Што не утврдува |
|---|---|---|
| Читање на сопствената база | Ги враќа информациите за следење што апликацијата веќе ги има. | Дали провајдерот примил поново ажурирање. |
| Пребарување преку API-то за следење | Ги презема информациите достапни преку операцијата за пребарување на провајдерот. | Дали при тоа барање се извршила нова проверка кај превозникот. |
| Барање за освежување на следењето | Бара нова проверка во надворешниот систем, ако провајдерот ја нуди таа операција. | Дека превозникот има ново скенирање или дека освежувањето ќе заврши синхроно. |
Користете пребарување кога ви е потребен одговор веднаш. Истражете ја операцијата за освежување само кога ви е потребно провајдерот да се обиде со нова проверка во надворешниот систем. Не претпоставувајте дека додавањето параметар за заобиколување на кешот, повторувањето на барањето или испраќањето HTTP заглавје cache-control ќе го принуди превозникот да достави нови информации.
Видливоста на пратката има неколку фази: превозникот бележи настан, провајдерот за следење го презема, а апликацијата го прима или го презема. Директното API-барање може да го заобиколи чекањето на доставата на известувањето, но не може да ги отстрани доцнењата што се случуваат порано во тој синџир.
Проверете го договорот за пребарување пред да напишете код
Програмерот што ја интегрира услугата за следење е одговорен за овој тек. Започнете со тековната документација на провајдерот, а не со endpoint преземен од стар пример за интеграција. Потврдете ги следните детали:
- Идентификација на пратката: Дали пребарувањето прифаќа број за следење, внатрешен ID на пратката или број за следење комбиниран со идентификатор на превозникот?
- Барања за регистрација: Дали пратката мора да биде регистрирана пред да може да се пребарува?
- Автентикација: Кое заглавје или механизам за автентикација е потребен?
- Значење на одговорот: Дали операцијата враќа зачувани информации, започнува преземање или враќа задача што треба да се провери подоцна?
- Обработка на резултатот: Дали успешен HTTP-одговор може да содржи неуспех на ниво на пратка или резултат што сè уште се обработува?
- Ограничувања на користењето: Кои ограничувања на брзината, сериите и конкретната сметка се применуваат?
- Полиња за свежина: Кои временски ознаки ги претставуваат настаните кај превозникот, ажурирањата од провајдерот и генерирањето на одговорот?
За интеграција со 17TRACK, Tracking API е релевантниот производ, наместо страницата за следење за корисници или интерфејсот за следење во продавницата. Користете ја официјалната API-документација за да ги потврдите операцијата за пребарување информации за следење, автентикацијата, полињата на барањето и структурата на одговорот за вашата интеграција. Третирајте ги пребарувањето и обработката на webhook-ови како одделни патеки на апликацијата што го ажурираат истиот запис за пратката.
Избегнувајте претпоставки вградени директно во кодот за однесувањето при освежување или зачестеноста на пребарувањето. Овие детали треба да одговараат на операцијата и условите на услугата што навистина ги користите.
Изградете пребарување на барање преку вашиот backend
Практичен дизајн е да изложите автентификуван endpoint во сопствената апликација. Прелистувачот бара ажурирање на пратката од тој endpoint; серверот ја проверува дозволата, одлучува дали е потребно пребарување кај провајдерот и враќа нормализиран резултат.
Следната рута е пример за endpoint што би го создале во апликацијата. Тоа не е endpoint на 17TRACK ниту спецификација за барање до провајдер.
GET /api/orders/{order_id}/shipment-statusКористете го идентификаторот на нарачката за да ја пронајдете пратката на серверот. Не дозволувајте повикувачот да ја преземе историјата на следење на друг клиент само со замена на бројот за следење во барањето. Чувајте ги акредитивите за API-то на провајдерот во backend-от, а не во JavaScript во прелистувачот или во пакетот на мобилната апликација.
Тек на барање што можете да го имплементирате
- Овластете пристап. Потврдете дека клиентот или членот на персоналот смее да ја види нарачката.
- Одредете ја пратката. Прочитајте го зачуваниот идентификатор за следење и информациите за превозникот, каде што е применливо.
- Проверете ја локалната свежина. Ако веќе постои неодамнешно успешно пребарување, повторно искористете го според политиката за свежина на апликацијата.
- Пребарајте кај провајдерот кога е потребно. Користете ја документираната операција и ограничено време за барањето.
- Потврдете го резултатот. Проверете го и 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 не е нужно најновата состојба на пратката.
- Користете една заедничка патека за ажурирање. Испраќајте ги резултатите од пребарувањата и payload-ите од webhook-овите низ истите функции за валидација, нормализација и зачувување.
- Отстранувајте дупликати на настани. Претпочитајте документиран идентификатор на настан. Ако не постои, создадете внимателно дефиниран отпечаток од достапните полиња, како време на настанот, статус, локација и опис.
- Користете полиња за редослед со познато значење. Документирана ревизија или секвенца е покорисна од претпоставката дека времето на пристигнување го претставува редоследот на настаните.
- Зачувајте ја историјата. Новопримен настан може да пополни историска празнина без да го промени тековниот преглед на пратката.
- Дозволете корекции. Статусите не се универзална линеарна скала. Следете го документираното однесување при корекции наместо трајно да го одбивате секој очигледен чекор наназад.
Кога редоследот на настаните е неизвесен, зачувајте го оригиналниот payload и неговото потекло за истрага. Не ја решавајте нејасноста со измислување временска ознака или со претпоставка дека сите временски ознаки на превозниците ја користат истата временска зона.
Разликувајте ги недостигот на податоци и неуспешните барања
Празен резултат, непроменет резултат и неуспешно барање не треба да создаваат иста порака за клиентот.
Пребарувањето е успешно, но статусот не е променет
Задржете го постојниот статус на пратката и ажурирајте го времето на последното успешно пребарување. Не создавајте нов настан на пратката само затоа што завршило ново пребарување. Ако клиентот има потреба од повеќе детали, прикажете ја постојната историја на настани и објаснете дека не е вратен понов настан за следење.
Пратката сè уште нема информации за следење
Проверете дали е потребна регистрација, дали идентификаторот и превозникот се точни и како провајдерот го претставува чекањето на преземањето податоци. Недостигот на настани сам по себе не докажува дека бројот за следење е неважечки или дека пратката е изгубена. Зачувајте ја разликата на провајдерот меѓу непознат идентификатор, регистрирана пратка што чека информации и барање што не можело да се обработи.
Барањето кон провајдерот истекува или не успева
Ако имате претходен валиден статус, вратете го со јасна ознака дека последната проверка не успеала. Оставете го времето на претходното успешно пребарување непроменето. Мрежната грешка не е исклучок при испорака и не треба да го промени деловниот статус на пратката.
Користете ограничени повторни обиди со постепено зголемување на паузата и случајно отстапување за соодветни привремени грешки. Не повторувајте постојано неважечки акредитиви или неправилно формирани барања. Кога одговорот содржи Retry-After, толкувајте го според договорот на провајдерот и семантиката на HTTP. Спецификацијата на HTTP дозволува таа вредност да биде изразена како доцнење во секунди или како HTTP-датум.
Пристигнуваат повеќе барања за истата пратка
Обединете ги истовремените пребарувања за да можат да споделат едно барање кон надворешниот систем. Применувајте ограничувања по сметка и пратка и спречете автоматското повторување да се намножи низ неколку слоеви на апликацијата. Кога е поддржано групно барање, проверете го резултатот за секоја пратка наместо целата серија да ја третирате како успешна само затоа што HTTP-барањето завршило.
Користете polling како контролиран резервен механизам
Без webhook-ови, планираниот polling може да ја одржува базата ажурирана, но бара јасна оперативна политика. Одлучете кои пратки остануваат подобни, како неуспесите влијаат врз распоредот и кога рутинскиот polling престанува.
За повеќето интеграции, хибридниот дизајн е разумна почетна точка: webhook-овите ги обработуваат промените во заднина, пребарувањата на барање ги опслужуваат интерактивните барања, а задачите за усогласување ги проверуваат записите на кои им е потребно внимание. Ова е архитектонска препорака, а не гаранција дека ги намалува трошоците за секоја сметка.
- Дајте приоритет на активните пратки и записите со нерешени грешки при преземањето.
- Избегнувајте пребарување на секоја историска пратка при секое планирано извршување.
- Дефинирајте како се обработуваат завршените пратки, вклучувајќи го периодот за корекции што го бара вашиот бизнис.
- Следете колку често пребарувањата наоѓаат навистина нови информации.
- Истражувајте ги проблемите со доставата на webhook-ови наместо да ги прикривате со сè почест polling.
Следете ја доцнежноста на барањата кон провајдерот, неуспешните пребарувања, одговорите за ограничување на брзината и разликите меѓу пребараните податоци и записите добиени преку webhook. Одделно следете ја староста на најновиот настан кај превозникот. Успешните API-одговори може да постојат истовремено со информации за следење што не се промениле.
Тестирајте го текот пред објавување
Успешното барање е само првиот тест. Проверете ги ситуациите што инаку можат да создадат погрешни ажурирања на статусот:
- Webhook пристигнува додека пребарувањето на барање сè уште работи.
- Двајца клиенти или членови на персоналот истовремено ја бараат истата пратка.
- Провајдерот враќа HTTP успех, но пријавува грешка на ниво на пратка.
- Барањето не успева откако апликацијата веќе има валидни информации за следење.
- На настанот му недостига временска зона или содржи непознат код за статус.
- Корекција од превозникот го менува претходно прикажаниот резултат.
- Корисник се обидува да пристапи до пратка што му припаѓа на друга сметка.
Критериумот за објавување треба да биде апликацијата да ги враќа најдобрите познати информации за пратката, точно да ја објаснува нивната свежина и да не ги оштетува кога барањата не успеваат или пристигнуваат по различен редослед.
ЧПП
Дали пребарувањето преку API го принудува превозникот да ја скенира или ажурира пратката?
Не. Преземањето информации за следење не може да предизвика физичко скенирање. Дали барањето започнува проверка во надворешниот систем зависи од документираната операција. Дури и поддржано освежување може да врати непроменети информации ако превозникот нема понов настан.
Може ли да користам API-пребарувања без конфигурирање webhook-ови?
Ако провајдерот го поддржува потребниот тек на пребарување, можете да изградите интеграција околу барања на барање или polling. Најпрво потврдете ги барањата за регистрација и пребарување. Потоа вашата апликација ќе биде одговорна да одлучи кога да проверува, да го контролира обемот на барањата и да открива промени.
Колку често треба да го проверувам статусот на пратката?
Не постои универзален интервал. Изберете распоред што одговара на ограничувањата на провајдерот, обемот на пратките и деловната вредност на пораното откривање ажурирања. Измерете колку често polling-от враќа нови настани, а потоа приспособете го наместо да претпоставувате дека честите барања создаваат посвежи податоци од превозникот.
Зошто API-то враќа информации што веќе ги примив преку webhook?
Двете патеки можат да го изложат истиот основен запис за пратката. Webhook доставува известување, додека пребарувањето ги презема информациите на барање. Примањето на истиот настан преку двете патеки не е нужно грешка; апликацијата треба да го отстрани дупликатот.
Дали копчето за ажурирање треба да пишува „Освежи го следењето“?
Само ако тој израз точно ја опишува операцијата. Ако копчето ги презема зачуваните податоци од провајдерот, „Провери за ажурирања“ е појасно. Прикажете го последниот настан кај превозникот одделно од времето кога апликацијата последен пат успешно завршила проверка.
Извори
- 17TRACK Tracking API — официјална референца за производот за интеграцијата со API-то за следење опишана во овој водич.
- 17TRACK API documentation — референца за операциите специфични за провајдерот, автентикацијата, полињата на барањата и обработката на одговорите.
- RFC 9110, Section 10.2.3: Retry-After — ги дефинира формите delay-seconds и HTTP-date на HTTP-заглавјето.


