Skip to main content
Басты бетБлогНұсқаулықтарЖөнелтімді қадағалау API жұмыс процесі: жөнелтімді тіркеуден бастап қадағалау мәліметтерін алуға дейін

Жөнелтімді қадағалау API жұмыс процесі: жөнелтімді тіркеуден бастап қадағалау мәліметтерін алуға дейін

17TRACK

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

Жөнелтімді тіркеуден бастап алуға дейінгі жөнелтімді қадағалау API жұмыс процесі

Бұл нұсқаулық электрондық коммерция платформасын, тапсырыстарды басқару жүйесін, қойма қолданбасын немесе клиенттерге қызмет көрсету құралын қосатын әзірлеушілерге арналған осы жұмыс процесін түсіндіреді. Мұнда қолданба дизайны бойынша ұсыныстар провайдерге тән API талаптарынан бөлек қарастырылады. 17TRACK интеграциясы үшін төмендегі мысалдарды іске асырмас бұрын сұрау схемасын, аутентификацияны, қолдау көрсетілетін операциялар мен жауап өрістерін растау үшін ресми API құжаттамасын пайдаланыңыз.

Тіркеу не істейтінін және не істемейтінін түсініңіз

Жөнелтімді қадағалау қызметіне тіркеу дегеніміз — қызмет оны API келісіміне сәйкес қадағалауы немесе басқаруы үшін идентификаторды жіберу. Бұл пошта ақысын төлеу, жеткізу жапсырмасын жасау, жинауды брондау немесе сәлемдемені тасымалдаушыға тапсыру операцияларымен бірдей емес.

Қолданбаңызда мына үш нәтижені бөлек ұстаңыз:

  • Сұрау алынды: API HTTP сұрауыңызға жауап қайтарды.
  • Тіркеу қабылданды: Қызмет жеке қадағалау жазбасын өңдеуге қабылдады.
  • Қадағалау ақпараты қолжетімді: Қызметте қолданбаңыз ала алатын немесе қабылдайтын жөнелтім туралы ақпарат бар.

Бұл нәтижелерді бір «сәттілік» жалаушасына біріктіруге болмайды. Қабылданған қадағалау нөмірінде әлі тасымалдаушы оқиғалары болмауы мүмкін. Сол сияқты, топтамалық сұрау бойынша сәтті HTTP жауабы топтамадағы әрбір элемент қабылданғанын білдірмейді; провайдер анықтаған қолданбалық нәтиже құрылымын тексеріңіз.

1. Жөнелтім идентификаторы мен API конфигурациясын дайындаңыз

Тіркеу сұрауын жібермес бұрын жөнелтімнің жеке жүйеңізде қалай анықталатынын шешіңіз. Әдетте тек тапсырыс идентификаторы жеткіліксіз, себебі бір тапсырыс бірнеше сәлемдемеге бөлінуі мүмкін. Әрбір жөнелтімге немесе сәлемдемеге жеке ішкі жазба беріп, оны тиісті тапсырыспен байланыстырыңыз.

Пайдалы ішкі жазбада мына ақпарат болады. Бұл ұсынылатын қолданба өрістері, 17TRACK сұрау схемасы емес.

  • Ішкі жөнелтім ID: Сәлемдемеге арналған тұрақты идентификаторыңыз.
  • Тапсырыс сілтемесі: Ол тиесілі тапсырыс немесе орындау жазбасы.
  • Қадағалау нөмірі: Тасымалдаушы берген идентификатор; бастапқы нөлдерді сақтау үшін мәтін ретінде сақталады.
  • Тасымалдаушы туралы ақпарат: Белгілі болса, орындау жүйесі ұсынған тасымалдаушы идентификациясы.
  • Провайдер сілтемесі: Кейінгі операцияларға қажет қадағалау қызметі қайтарған кез келген идентификатор.
  • Тіркеу күйі: Жіберу күтілуде, қабылданды, қабылданбады немесе салыстыру күтілуде деген жазбаңыз.
  • Қадағалау күйі: Тіркеу күйінен бөлек жүргізілетін жөнелтімнің соңғы күйі.

Жібермес бұрын енгізу деректерін тексеріңіз. Кездейсоқ қосылған басындағы және соңындағы бос орындарды алып тастаңыз, бірақ тасымалдаушы пішіміне қатысты болжамдарға сүйеніп қадағалау нөмірін өзгертпеңіз. Ақауларды жою үшін бастапқы мәнді сақтаңыз. Тасымалдаушы белгілі болса, бейресми көрсетілетін атауды емес, провайдер құжаттамасында көрсетілген тасымалдаушы идентификаторын пайдаланыңыз.

Аутентификацияны сервер жағында конфигурациялаңыз. Тіркелгі деректерін бастапқы кодты басқару жүйесінен тыс сақтаңыз, әзірлеу және өндірістік конфигурацияларды бөлек ұстаңыз және құпияларды журналдардан жасырыңыз. Қатысы жоқ интеграциядан мәндерді көшірмей, құжатталған API нұсқасын, сұрау шектеулерін, топтама шектеулерін және тіркелгі талаптарын растаңыз.

2. Жөнелтімді тіркеп, элемент деңгейіндегі нәтижені сақтаңыз

Қадағалау жазбасын провайдер құжаттамасында сипатталған тіркеу операциясы арқылы жіберіңіз. Тек міндетті өрістерді және нақты мақсаты бар қосымша ақпаратты қосыңыз. Тапсырыс дерекқорыңызда бар болғаны үшін клиенттердің аттарын, мекенжайларын немесе басқа жеке деректерді жібермеңіз.

Келесі псевдокод қолданбадағы реттілікті көрсетеді. Функция атаулары мысал ретінде берілген; олар API соңғы нүктелері немесе SDK әдістері емес.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Не болғанын түсіндіруге жеткілікті ақпаратты сақтаңыз: ішкі жөнелтім ID, жіберу уақыты, әрекет нөмірі, элемент деңгейіндегі нәтиже және провайдердің кез келген сұрау сілтемесі. Тек уақытша жұмыс процесі журналына сүйенбеңіз. Клиенттерге қызмет көрсету және операциялық топтарға жөнелтімнің сәтті тіркелген-тіркелмегені туралы тұрақты жауап қажет.

Топтамалық жіберулерді жеке өңдеңіз

Егер API топтамалық тіркеуді қолдаса, қайтарылған әрбір элементті бастапқы жөнелтімімен байланыстырыңыз. HTTP сұрауы сәтті аяқталғандықтан бүкіл топтаманы қабылданды деп белгілемеңіз. Қабылданған элементтерді сақтап, қабылданбағандарын бөлек шығарыңыз және түсініксіз нәтижелерді жеке зерттеңіз.

Бұл бір қате пішімделген қадағалау нөмірі бұрыннан сәтті болған жазбаларды қажетсіз қайта жіберуге мәжбүрлеуіне жол бермейді. Сонымен қатар операциялық қызметкерлерге түзетуді қажет ететін жазбалардың нақты тізімін береді.

Тайм-ауттарды белгісіз нәтиже ретінде қарастырыңыз

Тайм-аут тіркеудің сәтсіз болғанын дәлелдемейді. Байланыс үзілмей тұрып провайдер сұрауды қабылдаған болуы мүмкін. Соқыр түрде қайта жібермес бұрын нәтижені салыстыру үшін құжатталған идемпотенттілік тәртібін, қайталанатын сұрауларды өңдеу мүмкіндігін немесе іздеу операцияларын пайдаланыңыз.

Провайдердің қайталанатын сұрауларды өңдеу тәртібі түсініксіз болса, автоматты қайта жіберуді қоспас бұрын оны басқарылатын жазбалармен тексеріп, келісімді растаңыз. Тіркеу тапсырмаларын ішкі деңгейде қайталамау әлі де пайдалы, бірақ бұл қашықтағы қызметтің қайталанған сұрауларды қалай өңдейтінін түсінудің орнын баспайды.

3. Алғашқы қадағалау ақпаратының келуіне мүмкіндік беріңіз

Тіркеу қабылданғаннан кейін қадағалау мәліметтері бірден қолжетімді болмауы мүмкін. Тасымалдаушы физикалық өңдеу оқиғасын тіркемей тұрып, жапсырма жасалуы ықтимал. Ақпараттың болмауы қадағалау нөмірін, тасымалдаушы таңдауын немесе жөнелтімге тән іздеу талаптарын тексеруді қажет етуі мүмкін.

Бұл жағдайды нақты көрсетіңіз. «Тіркелді; қадағалау ақпараты күтілуде» деген белгі «Жолда» немесе «Тіркеу сәтсіз аяқталды» дегеннен дәлірек. Бос интерфейсті толтыру үшін жеткізу болжамын немесе қозғалыс оқиғасын ойдан шығармаңыз.

Жазба бос күйінде қалса, мына практикалық ретпен зерттеңіз:

  1. Жеке тіркеудің қабылданғанын растаңыз.
  2. Жіберілген қадағалау нөмірін орындау жазбасымен салыстырыңыз.
  3. Тасымалдаушы сәйкестігін және құжатталған қосымша іздеу талаптарын тексеріңіз.
  4. Сол жөнелтім үшін тасымалдаушының өз қадағалау бетін тексеріңіз.
  5. Егер тасымалдаушыда оқиғалар бар, бірақ интеграцияңызда жоқ болса, алу жауаптарын тексеріп, жасырылған диагностикалық ақпаратпен API провайдеріне хабарласыңыз.

Дәлелсіз әмбебап күту мерзімін енгізбеңіз. Эскалация ережелері жеткізу қызметіне, күтілетін тапсыру процесіне және өзіңіздің операциялық міндеттемелеріңізге сәйкес болуы керек.

4. Қадағалау мәліметтерін алып, оларды дұрыс түсіндіріңіз

Жазба қолжетімді болған соң, қажетті идентификаторларды пайдаланып, құжатталған қадағалау мәліметтерін алу операциясын шақырыңыз. Тіркеу мен алу бірдей өрістерді қабылдайды деп болжамаңыз. Кейбір API келісімдері қадағалау нөмірлерін, тасымалдаушы идентификаторларын және провайдер жасаған жазба сілтемелерін ажыратады.

Қолданбаңыз ақпараттың үш деңгейін ажыратуы керек:

  • Жөнелтім қорытындысы: Бақылау тақталарында, тапсырыс беттерінде және операциялық сүзгілерде қолданылатын жалпы күй.
  • Оқиғалар тарихы: Берілсе, оқиға сипаттамаларын, уақыт белгілерін және орындарды қамтитын жеке бақылаулар.
  • Алу метадеректері: Қолданба ақпаратты қашан алғаны немесе сұратқаны және сұраудың сәтті аяқталған-аяқталмағаны.

Сәтті іздеу алу операциясының сәтті болғанын білдіреді. Бұл алдыңғы іздеуден бері сәлемдеме қозғалды дегенді білдірмейді. Хабарландыру немесе кейінгі жұмыс процесін жасамас бұрын қайтарылған қадағалау ақпаратын сақталған жазбамен салыстырыңыз.

Оқиға уақытын алу уақытынан бөлек сақтаңыз

Тасымалдаушы оқиғасына қатысты уақытты жүйеңіз оны алған уақыттан бөлек сақтаңыз. Бүгін түстен кейін алынған оқиға бұрынырақ жасалған сканерлеуді сипаттауы мүмкін. Оның оқиға уақытын алу уақытымен ауыстыру ескі жаңартуды жаңа физикалық қозғалыс сияқты көрсетеді.

Бастапқы уақыт белгісін және берілген уақыт белдеуінің ығысуын сақтаңыз. Уақыт белдеуі белгілі болғанда ғана салыстыру үшін уақыт белгілерін қалыпқа келтіріңіз. Оқиғада уақыт белдеуі көрсетілмесе, серверіңіздің уақыт белдеуін үнсіз тағайындамай, бұл белгісіздікті сақтаңыз.

Қалыпқа келтірілген күймен бірге бастапқы мағынаны сақтаңыз

Қалыпқа келтірілген күй тасымалдаушылар арасындағы жөнелтімдерді топтастыруға пайдалы, бірақ бастапқы оқиға сипаттамасы операциялық мәселені дәлірек түсіндіруі мүмкін. Мүмкін болған жерде екеуін де сақтаңыз. Жалпы ерекшелік санатының өзі қолдау қызметкеріне келесі әрекет мекенжайды тексеру, алушымен байланысу немесе басқа жаңартуды күту екенін әрдайым көрсете бермейді.

Белгісіз күйден жеткізу кепілдігін, расталған жоғалуды немесе кедендік рәсімдеудің нақты нәтижесін болжамаңыз. Негізгі ақпарат пен операциялық саясатыңызға сәйкес эскалация жасаңыз.

5. Жазбаларды сауалнама немесе вебхуктар арқылы жаңартып отырыңыз

Мәліметтерді бір рет алу байланысты тексеруге жеткілікті, бірақ жөнелтімнің көрінуін сақтау үшін жеткіліксіз. Өндірістік дизайныңызға жаңарту механизмі қажет. Таңдалған провайдер қолдайтын механизмдер мен оларға қойылатын шарттарды растаңыз.

Сауалнама кезінде қолданбаңыз қадағалау мәліметтерін кесте бойынша сұратады. Сұрауларды құжатталған шектерде жоспарлаңыз, себепсіз өзгермеген жазбаларды қайталап сұратпаңыз және қайта орындауға болатын сәтсіздіктер үшін кідірісті арттыруды пайдаланыңыз. Клиент тапсырыс бетін ашқанда жоғары деңгейдегі шектеусіз сұрау автоматты түрде іске қосылмауы керек; сақталған қадағалау көрінісі бетті көрсете алады, ал басқарылатын фондық процесс оны жаңартады.

Вебхуктарды пайдалансаңыз, кіріс сұрауларын провайдер құжаттамасында көрсетілген тексеру механизмі арқылы растаңыз. Вебхук келісіміне сәйкес растау жібермес бұрын қабылданған хабарларды сақтаңыз немесе тұрақты кезекке қойыңыз, содан кейін оқиғаларды асинхронды түрде өңдеңіз.

Құжатталған жеткізу келісімі өзгеше кепілдік бермесе, қабылдағышты қайталанатын хабарлар мен күтпеген келу ретіне төзімді етіп құрыңыз. Мүмкін болса, қайталануды жою үшін провайдер оқиғасының идентификаторын пайдаланыңыз. Әйтпесе, қолайлы оқиға өрістеріне негізделген із қалыптастырып, оны анықтап, тексеріңіз; мұндай із деректеріңізге қарай түзетуді қажет етуі мүмкін.

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

6. Қадағалау ақпаратын қауіпсіз бизнес әрекеттеріне айналдырыңыз

Клиентке бағытталған әрекеттерді іске қоспас бұрын ішкі жөнелтім жазбасын жаңартыңыз. Қайталанатын оқиға қайталанатын хабарламалар тудырмауы үшін хабарландырулар мен жұмыс процесі ауысуларының тұрақты жазбасын жүргізіңіз.

Бизнес әрекеттерін әрбір API жауабына емес, мағыналы өзгерістерге байланыстырыңыз. Жаңадан байқалған жеткізу оқиғасы жеткізілді деген хабарландыруды негіздеуі мүмкін. Сол оқиғаны қамтитын қайталама жауап негіздемейді. Ерекше жағдай ішкі тексеруді қажет етуі мүмкін, бірақ клиентке арналған хабарлама оқиғада нақты не айтылғанын көрсетуі керек.

Жөнелтім аяқталды деп есептелгеннен кейін алынған оқиғаларды қалай өңдейтініңізді анықтаңыз. Қорытынды күйге жеткендіктен оқиғалар тарихын жоймаңыз немесе кейінгі барлық жаңартуларды біржола бұғаттамаңыз. Сақтау, салыстыру және хабарландыру ережелеріңіз аяқталған жұмыс процестерін қайта-қайта ашпай, заңды түзетулерді ескеруі керек.

Жұмыс процесін 17TRACK интеграциясына қолдану

Арнайы қадағалау интеграциясы үшін бастапқы нүктелер — 17TRACK Tracking API беті және оның әзірлеушілерге арналған құжаттамасы. Ұсынысты бағалау үшін өнім бетін, ал нақты интеграция келісімін белгілеу үшін құжаттаманы пайдаланыңыз. Тұтынушыларға арналған қадағалау беттері API сипаттамаларының орнын баспайды.

Адаптерді жазбас бұрын аутентификация пішімін, тіркеу және алу операцияларын, тасымалдаушыны анықтау ережелерін, элемент деңгейіндегі жауаптарды өңдеуді және қолданыстағы сұрау шектеулерін растаңыз. Вебхук негізіндегі өңдеу үшін пайдалы жүктеме схемасын, тексеру процесін, растау талаптарын және қайта жіберу тәртібін де растаңыз.

Провайдерге тән осы мәліметтерді жауап өрістеріне қатысты болжамдарды тапсырыстар жүйесіне таратып жібермей, адаптер ішінде ұстаңыз. Сонда қолданбаның қалған бөлігі тіркеу нәтижесі, жөнелтім күйі, оқиғалар тарихы және соңғы сәтті синхрондау сияқты ішкі ұғымдармен жұмыс істей алады.

Іске қосу алдындағы қымбат қателердің алдын алатын тексерулер

  • Қабылданды, бірақ жазба бос: Интерфейс қадағалау ақпараты күтіліп тұрғанын көрсетеді, сәлемдеме қозғалып жатқанын емес.
  • Аралас топтама нәтижесі: Әр жөнелтімнің өз сақталған нәтижесі болады.
  • Жіберуден кейінгі тайм-аут: Жұмыс процесі сәтсіздік деп болжамай, белгісіз нәтижені салыстырады.
  • Қайталанған оқиға: Жөнелтім хронологиясы мен клиент хабарландыруы қайталанбайды.
  • Ескі оқиға кейін алынды: Жаңа қорытындыны соқыр түрде ауыстырмай, оқиға сақталады.
  • Жоғары деңгейдегі қызмет қолжетімсіз: Клиент беті жаңалықтың тиісті көрсеткішімен соңғы сақталған нәтижені көрсете алады.
  • Тасымалдаушы сәйкестігі қате: Жазбаны құжатталған қалпына келтіру жолы арқылы түзетуге болады.
  • Бөлінген тапсырыс: Әр сәлемдеме өзінің қадағалау күйі мен оқиғалар тарихын сақтайды.
  • Тіркелгі деректері немесе пайдалы жүктеме ашылып қалды: Журналдарда құпияларды немесе қажетсіз жеке ақпаратты жарияламай, диагностикалық сілтемелер болады.

Практикалық аяқталу критерийі жай ғана сәтті тіркеу жауабын алу емес. Ол — сәлемдемені жіберуден бастап жаңартуларға дейін қадағалай алу, бос немесе сәтсіз нәтижені түсіндіру және оқиғаларды жоғалтпай немесе клиент әрекеттерін қайталамай, үзілген өңдеуден қалпына келе алу.

Жиі қойылатын сұрақтар

Қадағалау нөмірін тіркеу жөнелтім жасай ма?

Осы жерде сипатталған жұмыс процесінде — жоқ. Қадағалауды тіркеу бұрыннан бар идентификаторды қадағалау қызметіне жібереді. Белгілі бір API оларды арнайы біріктірмесе, жапсырма жасау, пошта ақысын төлеу және тасымалдаушыға тапсырыс беру бөлек операциялар болып табылады.

Тіркеу сәтті болғаннан кейін қадағалау мәліметтері неге бос?

Тіркеудің қабылдануы мен қадағалау деректерінің қолжетімділігі — әртүрлі шарттар. Тасымалдаушы оқиғаны әлі тіркемеген болуы мүмкін немесе қадағалау нөмірін, тасымалдаушы сәйкестігін не қосымша іздеу ақпаратын тексеру қажет болуы ықтимал. Жазбаны сәтті тіркелді деп есептемес бұрын элемент деңгейіндегі нәтижені тексеріңіз.

Күйін алған сайын жөнелтімді тіркеуім керек пе?

Қайталама тіркеуді әдепкі жаңарту механизмі ретінде пайдаланбаңыз. Қабылданған тіркеу күйін сақтап, құжатталған алу немесе жаңарту механизмін қолданыңыз. Түзетулер, қайта белсендіру немесе қайталанатын жіберулерге қатысты провайдердің нақты ережелерін орындаңыз.

Сауалнаманы немесе вебхуктарды қолдануым керек пе?

Құжатталған API келісіміне және операциялық талаптарыңызға сәйкес келетін механизмді таңдаңыз. Сауалнама басқарылатын сұрау кестесін талап етеді. Вебхуктар қауіпсіз, тұрақты қабылдағыш пен қайталануға төзімді өңдеуді талап етеді. Қолдау көрсетілсе, мақсатты салыстырумен бірге вебхук жаңартулары практикалық қалпына келтіру жолын қамтамасыз ете алады.

Дерекқорымдағы жалғыз жөнелтім идентификаторы ретінде қадағалау нөмірін пайдалана аламын ба?

Оның орнына ішкі жөнелтім идентификаторын пайдаланыңыз. Қадағалау нөмірі мен тиісті тасымалдаушы мәнмәтінін осы жазбаның атрибуттары ретінде сақтаңыз. Бұл ішкі жөнелтімнің идентификациясын өзгертпей, бөлінген тапсырыстарды, түзетілген қадағалау нөмірлерін және провайдерге тән сілтемелерді басқаруды жеңілдетеді.

Дереккөздер

  • 17TRACK Tracking API — 17TRACK API интеграциясын бағалауға арналған ресми өнімнің бастапқы беті.
  • 17TRACK API құжаттамасы — іске асыруға тән сұрау пішімдері, операциялар, жауаптар және интеграция талаптары бойынша ресми анықтамалық. Бұл нұсқаулықтағы псевдокод пен ішкі өрістер жөніндегі ұсыныстар қолданба дизайнының мысалдары болып табылады, осы API келісімінен алынған дәйексөздер емес.