Webhook-ті күтпей, жөнелтілімнің соңғы күйін API арқылы қалай алуға болады
Веб-хукты күтпей-ақ, қолжетімді ең соңғы жөнелтілім мәртебесін алу үшін трекинг провайдерінің жөнелтілімдерді сұрау API интерфейсіне аутентификацияланған сұрау жіберіңіз. Жауапты қолданбаңызды дереу жаңарту үшін пайдаланыңыз, содан кейінгі өзгерістер үшін веб-хуктарды қосулы күйде қалдырыңыз. Маңызды айырмашылық мынада: сұрау әдетте провайдерде сақталған ең соңғы трекинг ақпаратын алады; ол міндетті түрде тасымалдаушының жаңа тексеруін іске қоспайды.

Бұл тәсіл тұтынушы тапсырыс бетін ашқанда, қолдау қызметкеріне жаңарту қажет болғанда немесе жүйеңіз өткізіп алған хабарламадан кейін қалпына келуі керек болғанда пайдалы. Сенімді іске асыру сұраныс бойынша орындалатын сұрауларды, жаңалықтың өзектілігін көрсететін анық индикаторларды және қайталанатын немесе реттен тыс жаңартулардан қорғаныс тетіктерін біріктіреді.
«Ең соңғы жөнелтілім мәртебесі» нені білдіретінін анықтаңыз
Эндпоинтті таңдамас бұрын, ұқсас естілгенімен, нәтижелері әртүрлі болуы мүмкін үш операцияны ажыратыңыз.
| Операция | Не істейді | Нені анықтамайды |
|---|---|---|
| Өз дерекқорыңызды оқу | Қолданбаңызда бұрыннан бар трекинг ақпаратын қайтарады. | Провайдер жаңағырақ жаңартуды алған-алмағанын көрсетпейді. |
| Трекинг API интерфейсіне сұрау жіберу | Провайдердің сұрау операциясы арқылы қолжетімді ақпаратты алады. | Осы сұрау барысында тасымалдаушының жаңа тексеруі орындалған-орындалмағанын көрсетпейді. |
| Трекингті жаңартуды сұрау | Провайдерде мұндай операция болса, жоғары деңгейдегі тағы бір тексеруді сұрайды. | Тасымалдаушыда жаңа сканерлеу бар екенін немесе жаңарту синхронды түрде аяқталатынын білдірмейді. |
Жауап қазір қажет болса, сұрауды пайдаланыңыз. Провайдердің тағы бір жоғары деңгейдегі тексеруді орындауына себеп керек болғанда ғана жаңарту операциясын қарастырыңыз. Кэшті айналып өту параметрін қосу, сұрауды қайталау немесе HTTP кэшті басқару тақырыбын жіберу тасымалдаушыны жаңа ақпарат беруге мәжбүр етеді деп ойламаңыз.
Жөнелтілімнің көрінуі бірнеше кезеңнен тұрады: тасымалдаушы оқиғаны тіркейді, трекинг провайдері оны алады, ал қолданбаңыз оны қабылдайды немесе сұрау арқылы алады. API арқылы тікелей сұрау хабарламаны жеткізуді күтуді айналып өте алады, бірақ осы тізбектің алдыңғы кезеңдеріндегі кідірістерді жоя алмайды.
Код жазбас бұрын сұрау келісімшартын тексеріңіз
Трекинг қызметін біріктіріп жатқан әзірлеуші осы жұмыс процесіне жауап береді. Ескі интеграция мысалынан көшірілген эндпоинттен емес, провайдердің қолданыстағы құжаттамасынан бастаңыз. Мына мәліметтерді растаңыз:
- Жөнелтілім идентификациясы: Сұрау трекинг нөмірін, ішкі жөнелтілім ID нөмірін немесе тасымалдаушы идентификаторымен бірге трекинг нөмірін қабылдай ма?
- Тіркеу талаптары: Сұрау жібермес бұрын жөнелтілім тіркелуі керек пе?
- Аутентификация: Қай тақырып немесе аутентификация механизмі қажет?
- Жауаптың мағынасы: Операция сақталған ақпаратты қайтара ма, деректер жинауды бастай ма, әлде кейін тексерілетін тапсырманы қайтара ма?
- Нәтижені өңдеу: Сәтті HTTP жауабында жөнелтілім деңгейіндегі қате немесе күтіліп тұрған нәтиже болуы мүмкін бе?
- Пайдалану шектеулері: Қандай жиілік шектеулері, топтық сұрау шектеулері және есептік жазбаға тән талаптар қолданылады?
- Жаңалық өрістері: Қай уақыт белгілері тасымалдаушы оқиғаларын, провайдер жаңартуларын және жауаптың жасалу уақытын көрсетеді?
17TRACK интеграциясы үшін тұтынушыларға арналған трекинг беті немесе дүкендегі трекинг интерфейсі емес, Tracking API тиісті өнім болып табылады. Интеграцияңызға арналған трекинг ақпаратына сұрау операциясын, аутентификацияны, сұрау өрістерін және жауап құрылымын растау үшін ресми API құжаттамасын пайдаланыңыз. Сұрау жіберу мен веб-хуктарды өңдеуді бір жөнелтілім жазбасын жаңартатын бөлек қолданба жолдары ретінде қарастырыңыз.
Жаңарту әрекетіне немесе сұрау жиілігіне қатысты болжамдарды кодқа тікелей енгізбеңіз. Бұл мәліметтер сіз нақты пайдаланатын операция мен қызмет шарттарына сәйкес келуі керек.
Backend арқылы сұраныс бойынша іздеу жасаңыз
Практикалық дизайн — өз қолданбаңызда аутентификацияланған эндпоинт ұсыну. Браузер осы эндпоинттен жөнелтілім жаңартуын сұрайды; серверіңіз авторизацияны тексереді, провайдерге сұрау қажет-қажет еместігін шешеді және қалыпқа келтірілген нәтижені қайтарады.
Келесі маршрут — қолданбаңызда жасайтын эндпоинттің мысалы. Бұл 17TRACK эндпоинті немесе провайдердің сұрау спецификациясы емес.
GET /api/orders/{order_id}/shipment-statusСерверде жөнелтілімді іздеу үшін тапсырыс идентификаторын пайдаланыңыз. Сұраудағы трекинг нөмірін ауыстыру арқылы сұрау жіберушінің басқа тұтынушының трекинг тарихын алуына жол бермеңіз. Провайдердің API тіркелгі деректерін браузердегі JavaScript кодында немесе мобильді қолданба бумасында емес, backend жүйесінде сақтаңыз.
Іске асыруға болатын сұрау ағыны
- Қолжетімділікті авторизациялау. Тұтынушының немесе қызметкердің тапсырысты көруге құқығы бар екенін растаңыз.
- Жөнелтілімді анықтау. Қажет болса, сақталған трекинг идентификаторы мен тасымалдаушы ақпаратын оқыңыз.
- Жергілікті жаңалықты тексеру. Жақында сәтті орындалған сұрау бар болса, оны қолданбаңыздың жаңалық саясатына сәйкес қайта пайдаланыңыз.
- Қажет болғанда провайдерге сұрау жіберу. Құжатталған операцияны және шектелген сұрау күту уақытын пайдаланыңыз.
- Нәтижені растау. HTTP нәтижесін де, жөнелтілім деңгейіндегі нәтижені де тексеріңіз.
- Ақпаратты біріктіру. Веб-хук оқиғалары үшін пайдаланылатын қалыпқа келтіру және салыстыру ережелерін қолданыңыз.
- Мәртебе мен жаңалықты қайтару. Қолжетімді болса, соңғы оқиға уақытын және провайдерді соңғы рет сәтті тексеру уақытын қосыңыз.
Жергілікті жаңалық саясаты — тасымалдаушының жаңарту жиілігі туралы мәлімдеме емес, инженерлік шешім. Оны интерфейс талаптарына, провайдер шектеулеріне, жөнелтілім көлеміне және сұраудың нақты пайдасына сүйене отырып таңдаңыз. Тұтынушы жаңарту түймесін қайта-қайта басқан кезде жоғары деңгейге шектеусіз сұраулар ағыны жасалмауы керек.
Жаңалықты ойдан шығармай, жауапты қалыпқа келтіріңіз
Провайдер жауаптарының құрылымы әртүрлі болса да, қолданбаңыз тұрақты ішкі пішімді қайтара алады. Бұл мысалдағы объект — сіздің қолданбаңыздың жеке келісімшарты, нақты провайдер 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 сұраулары мен веб-хуктардың бірін-бірі қайта жазуына жол бермеңіз
Екі механизм де белсенді болғанда, бір оқиға сұрау және веб-хук арқылы келуі мүмкін. Олар басталған реттен басқа ретпен де аяқталуы ықтимал. Бірінші іске қосылған сұрау веб-хук жаңарақ ақпаратты бергеннен кейін аяқталуы мүмкін.
«Соңғы жауап жеңеді» логикасын қолданбаңыз. Соңғы қабылданған payload міндетті түрде жөнелтілімнің ең соңғы күйі емес.
- Бір жаңарту арнасын ортақ пайдаланыңыз. Сұрау нәтижелері мен веб-хук payload-тарын бірдей растау, қалыпқа келтіру және сақтау функциялары арқылы өткізіңіз.
- Оқиғалардың қайталануын жойыңыз. Құжатталған оқиға идентификаторына басымдық беріңіз. Егер ондай идентификатор болмаса, оқиға уақыты, мәртебе, орналасқан жері және сипаттамасы сияқты қолжетімді өрістерден мұқият анықталған саусақ ізін жасаңыз.
- Мағынасы белгілі реттеу өрістерін пайдаланыңыз. Құжатталған ревизия немесе реттік нөмір қабылдану уақыты оқиғалар ретін білдіреді деп болжағаннан пайдалырақ.
- Тарихты сақтаңыз. Жаңадан қабылданған оқиға ағымдағы жөнелтілім қорытындысын өзгертпей, тарихи олқылықты толтыра алады.
- Түзетулерге мүмкіндік беріңіз. Мәртебелер әмбебап сызықтық баспалдақ емес. Көрінетін әрбір кері ауысуды біржола қабылдамай тастаудың орнына, құжатталған түзету тәртібін ұстаныңыз.
Оқиғалардың реті белгісіз болғанда, бастапқы payload пен оның шығу тегін зерттеу үшін сақтаңыз. Оқиға уақытын ойдан шығару немесе барлық тасымалдаушы уақыт белгілерінің бір уақыт белдеуіне тиесілі екенін болжау арқылы белгісіздікті жоймаңыз.
Жетіспейтін деректер мен сәтсіз сұрауларды әртүрлі өңдеңіз
Бос нәтиже, өзгермеген нәтиже және сәтсіз сұрау тұтынушыға бірдей хабарлама шығармауы керек.
Сұрау сәтті орындалды, бірақ мәртебе өзгермеді
Қолданыстағы жөнелтілім мәртебесін сақтап, соңғы сәтті сұрау уақытын жаңартыңыз. Кезекті іздеу аяқталғаны үшін ғана жаңа жөнелтілім оқиғасын жасамаңыз. Тұтынушыға қосымша мәлімет қажет болса, бар оқиғалар тарихын көрсетіп, жаңарақ трекинг оқиғасы қайтарылмағанын түсіндіріңіз.
Жөнелтілімде әлі трекинг ақпараты жоқ
Тіркеу қажет пе, идентификатор мен тасымалдаушы дұрыс па және провайдер күтіліп тұрған деректерді қалай көрсететінін тексеріңіз. Оқиғалардың болмауы трекинг нөмірінің жарамсыз немесе сәлемдеменің жоғалғанын өздігінен дәлелдемейді. Белгісіз идентификатор, ақпарат күтіп тұрған тіркелген жөнелтілім және өңделмеген сұрау арасындағы провайдер айырмашылығын сақтаңыз.
Провайдер сұрауының күту уақыты аяқталды немесе сұрау сәтсіз болды
Алдыңғы жарамды мәртебе болса, оны соңғы тексерудің сәтсіз болғанын анық көрсетіп қайтарыңыз. Бұрынғы сәтті сұрау уақыт белгісін өзгертпеңіз. Желі қатесі жеткізуге қатысты ерекшелік емес және сәлемдеменің бизнес мәртебесін өзгертпеуі керек.
Тиісті уақытша қателер үшін кідіріс пен кездейсоқ интервалды қолдана отырып, шектеулі қайталауларды пайдаланыңыз. Жарамсыз тіркелгі деректерін немесе қате пішімделген сұрауларды қайта-қайта жібермеңіз. Жауап Retry-After мәнін берсе, оны провайдер келісімшарты мен HTTP мағынасына сәйкес түсіндіріңіз. HTTP спецификациясы бұл мәнді секундпен көрсетілген кідіріс немесе HTTP күні түрінде беруге мүмкіндік береді.
Бір жөнелтілім үшін бірнеше сұрау келді
Бір жоғары деңгейдегі сұрауды ортақ пайдалану үшін қатар орындалатын іздеулерді біріктіріңіз. Есептік жазба мен жөнелтілім бойынша шектеулер қолданыңыз және автоматты қайталаудың бірнеше қолданба қабатында көбейіп кетуіне жол бермеңіз. Топтық сұрауға қолдау көрсетілсе, HTTP сұрауы аяқталғандықтан бүкіл топты сәтті деп санаудың орнына әр жөнелтілімнің нәтижесін тексеріңіз.
Бақылауды басқарылатын қосалқы тәсіл ретінде пайдаланыңыз
Веб-хуктарсыз жоспарланған бақылау дерекқорыңызды жаңартып тұра алады, бірақ бұл үшін нақты пайдалану саясаты қажет. Қай жөнелтілімдердің жарамды болып қалатынын, сәтсіздіктер кестеге қалай әсер ететінін және жоспарлы бақылау қашан тоқтайтынын анықтаңыз.
Көптеген интеграциялар үшін гибридті дизайн — орынды бастапқы нұсқа: веб-хуктар фондық өзгерістерді өңдейді, сұраныс бойынша сұраулар интерактивті сұраныстарға қызмет көрсетеді, ал салыстыру тапсырмалары назар аударуды қажет ететін жазбаларды тексереді. Бұл архитектуралық ұсыныс, әр есептік жазба үшін шығынды азайтатынына кепілдік емес.
- Белсенді жөнелтілімдер мен шешілмеген ақпарат алу қателері бар жазбаларға басымдық беріңіз.
- Әр жоспарланған іске қосу кезінде барлық тарихи жөнелтілімдерге сұрау жібермеңіз.
- Аяқталған жөнелтілімдердің қалай өңделетінін, соның ішінде бизнесіңізге қажет түзету кезеңін анықтаңыз.
- Сұраулардың қаншалықты жиі шын мәнінде жаңа ақпарат табатынын бақылаңыз.
- Барған сайын жиілейтін бақылау арқылы жасырудың орнына, веб-хук жеткізу мәселелерін зерттеңіз.
Провайдер сұрауының кідірісін, сәтсіз сұрауларды, жиілік шектеуіне қатысты жауаптарды және сұралған деректер мен веб-хук арқылы алынған жазбалар арасындағы айырмашылықтарды бақылаңыз. Соңғы тасымалдаушы оқиғасының ескілігін бөлек бақылаңыз. Сәтті API жауаптары трекинг ақпаратының өзгермеген күйімен қатар жүруі мүмкін.
Шығарылымға дейін жұмыс процесін сынаңыз
Сәтті орындалған сұрау — тек бірінші сынақ. Әйтпесе жаңылыстыратын мәртебе жаңартуларына әкелуі мүмкін жағдайларды тексеріңіз:
- Сұраныс бойынша сұрау әлі орындалып жатқанда веб-хук келеді.
- Екі тұтынушы немесе қызметкер сеансы бір жөнелтілімді бір уақытта сұрайды.
- Провайдер HTTP сәттілігін қайтарады, бірақ жөнелтілім деңгейіндегі қате туралы хабарлайды.
- Қолданбаңызда жарамды трекинг ақпараты бар болғаннан кейін сұрау сәтсіз болады.
- Оқиғада уақыт белдеуі көрсетілмеген немесе бейтаныс мәртебе коды бар.
- Тасымалдаушының түзетуі бұрын көрсетілген нәтижені өзгертеді.
- Пайдаланушы басқа есептік жазбаға тиесілі жөнелтілімге қол жеткізуге тырысады.
Шығарылым өлшемі мынадай болуы керек: қолданба ең жақсы белгілі жөнелтілім ақпаратын қайтаруы, оның жаңалығын дәл түсіндіруі және сұраулар сәтсіз болғанда немесе ретсіз келгенде бұл ақпаратты бұзбауы тиіс.
Жиі қойылатын сұрақтар
API интерфейсіне сұрау жіберу тасымалдаушыны сәлемдемені сканерлеуге немесе жаңартуға мәжбүрлей ме?
Жоқ. Трекинг ақпаратын алу физикалық сканерлеуге себеп бола алмайды. Сұрау жоғары деңгейдегі іздеуді іске қоса ма, жоқ па — құжатталған операцияға байланысты. Қолдау көрсетілетін жаңарту әрекетінің өзі тасымалдаушыда жаңарақ оқиға болмаса, өзгермеген ақпаратты қайтаруы мүмкін.
Веб-хуктарды баптамай API сұрауларын пайдалана аламын ба?
Егер провайдер қажетті сұрау процесіне қолдау көрсетсе, интеграцияны сұраныс бойынша орындалатын сұраулар немесе бақылау негізінде құра аласыз. Алдымен тіркеу және сұрау талаптарын растаңыз. Содан кейін қашан тексеру керегін шешу, сұраулар көлемін бақылау және өзгерістерді анықтау жауапкершілігі қолданбаңызға жүктеледі.
Жөнелтілім мәртебесін қаншалықты жиі бақылауым керек?
Әмбебап интервал жоқ. Провайдер шектеулеріне, жөнелтілім көлеміне және жаңартуларды ертерек табудың бизнес құндылығына сәйкес келетін кестені таңдаңыз. Бақылау жаңа оқиғаларды қаншалықты жиі қайтаратынын өлшеп, жиі сұраулар тасымалдаушы деректерін жаңартады деп болжаудың орнына кестені соған сай өзгертіңіз.
Неліктен API веб-хук арқылы бұрын алған ақпаратты қайтарады?
Екі жол да бір негізгі жөнелтілім жазбасын көрсете алады. Веб-хук хабарлама жеткізеді, ал сұрау ақпаратты талап бойынша алады. Бір оқиғаның екі жолмен келуі міндетті түрде қате емес; қолданбаңыз оның қайталануын жоюы керек.
Жаңарту түймесінде «Трекингті жаңарту» деп жазу керек пе?
Бұл сөз тіркесі операцияны дәл сипаттаған жағдайда ғана. Егер түйме провайдерде сақталған деректерді алса, «Жаңартуларды тексеру» деген түсініктірек. Соңғы тасымалдаушы оқиғасын қолданбаңыздың соңғы сәтті тексеруді аяқтаған уақытынан бөлек көрсетіңіз.
Дереккөздер
- 17TRACK Tracking API — осы нұсқаулықта талқыланған трекинг API интеграциясына арналған ресми өнім анықтамасы.
- 17TRACK API құжаттамасы — провайдерге тән операциялар, аутентификация, сұрау өрістері және жауаптарды өңдеу туралы анықтама.
- RFC 9110, 10.2.3-бөлім: Retry-After — HTTP тақырыбының секундпен көрсетілген кідіріс және HTTP күні пішімдерін анықтайды.


