UPS Tracking API құжаттамасы: әзірлеушілер білуі тиіс 7 негізгі мүмкіндік
UPS tracking API құжаттамасы әзірлеушіге бақылау нөмірінен сенімді жөнелтілім күйін көрсету тәжірибесіне өтуге көмектескен кезде ең пайдалы болады. Қарастырылатын жеті сала: аутентификация, бақылау сұраулары, жауап схемалары, оқиғалар тарихы, қателерді өңдеу, операциялық шектеулер және тестілеу. UPS тікелей UPS интеграциялары үшін өзінің әзірлеушілер платформасын ұсынады, ал 17TRACK Tracking API сияқты бірнеше тасымалдаушыға арналған қызмет бір интеграция UPS және басқа тасымалдаушыларды қолдауы қажет болғанда қолайлырақ болуы мүмкін.
Дұрыс іске асыру сіз құрып жатқан жүйеге байланысты. Бөлшек сауда компаниясына тапсырыс бетіндегі жеткізу жаңартулары, қойма тобына ерекше жағдайлар туралы ескертулер, ал корпоративтік платформаға бірнеше тасымалдаушы бойынша қалыпқа келтірілген бақылау деректері қажет болуы мүмкін. Құжаттаманы осы пайдалану жағдайлары тұрғысынан оқу кең таралған қателіктің алдын алады: API-дің сәтті жауабын жөнелтілімнің толық көріну шешімімен бірдей деп қабылдамау.
UPS tracking API құжаттамасы қандай сұрақтарға жауап беруге көмектесуі керек
Код жазбас бұрын төрт сұрақты нақтылаңыз:
- Сіз тек UPS-пен интеграция жасайсыз ба, әлде жүйе бірнеше тасымалдаушыны бақылай ма?
- Сізге пакеттің ағымдағы күйі, сканерлеулердің толық тарихы немесе екеуі де қажет пе?
- Қолданбаңыз жаңартуларды сұраныс бойынша сұрай ма, хабарландырулар қабылдай ма, әлде осы тәсілдердің үйлесімін қолдана ма?
- Жөнелтілім кешіккенде, жеткізілгенде, қайтарылғанда немесе әлі табылмағанда клиенттер мен ішкі топтар нені көруі керек?
UPS құжаттамасы ағымдағы тіркелгі деректері, қолдау көрсетілетін операциялар, сұрау талаптары, жауап өрістері және коммерциялық қолжетімділік шарттары үшін негізгі дереккөз болып табылады. Бұл мәліметтер API өніміне, есептік жазба құрылымына немесе әзірлеушілер платформасының нұсқасына қарай өзгеруі мүмкін, сондықтан өндірістік код ескі код үлгісіне сүйенбей, ағымдағы UPS әзірлеушілер порталын басшылыққа алуы керек.
Әзірлеушілер түсінуі тиіс 7 негізгі мүмкіндік
1. Аутентификация және қолданбаға қолжетімділік
Аутентификация — алғашқы практикалық мүмкіндік, себебі ол қолданбаның өз тұлғасын қалай дәлелдейтінін және API шақыруға рұқсатты қалай алатынын анықтайды. UPS әзірлеушілер құжаттамасы қолданбаны тіркеу, тіркелгі деректерін жасау, қолжетімділікті сұрау және токендерді басқарудың ағымдағы үдерісін ұсынады. Құжаттама UPS API интерфейстеріне OAuth негізіндегі қолжетімділікті сипаттайды, алайда әзірлеушілер іске асыру алдында ағымдағы порталдағы grant ағынын, ауқымдарды, токеннің жарамдылық мерзімін және орта талаптарын растауы керек.
Тіркелгі деректерін сервер жағында сақтаңыз. Оларды браузердегі JavaScript кодының, мобильді жинақтардың, жалпыға қолжетімді репозиторийлердің немесе клиент көретін бақылау бетінің кодына енгізуге болмайды. Қауіпсіз архитектура клиентке арналған қолданба мен UPS арасында backend қызметін орналастырады. Бұл қызмет қауіпсіз аутентификациядан өтіп, сұрау шектеулерін қолдана алады, құпияларды ашпай техникалық нәтижелерді тіркей алады және frontend-ке тек қажет жөнелтілім деректерін қайтара алады.
UPS платформасы бөлек орталарды қолдайтын жағдайда әзірлеу тіркелгі деректерін өндірістік тіркелгі деректерінен де ажыратыңыз. Орналастыруды тексеру тізіміне құпияларды сақтау, оларды ауыстыру, қолжетімділік иелігі, мерзімі өткен токендерді өңдеу және аутентификация қателері көбейе бастағанда ескерту енгізілуі керек.
2. Бақылау нөмірі сұраулары және тасымалдаушы контексті
Бақылау интеграциясына бақылау идентификаторын жіберудің және жөнелтілім туралы ақпарат сұраудың болжамды тәсілі қажет. Маңызды сұрақтар тек endpoint мекенжайымен шектелмейді. Оларға қабылданатын бақылау нөмірінің пішімі, сұраудың бір немесе бірнеше нөмірді қолдайтыны, тасымалдаушының қалай анықталатыны және нөмір толық емес немесе әлі танылмаған кезде API-дің қалай жауап беретіні жатады.
Бақылау нөміріне ұқсайтын әрбір жол UPS-ке тиесілі деп ойламаңыз. Қолданбаңыз бірнеше жөнелту жүйесінен жапсырмалар алса, тасымалдаушы белгілі болған сайын оны бөлек өріс ретінде сақтаңыз. Тасымалдаушыны ескеретін бағыттау қате сәйкестіктерді азайтып, ақауларды іздеуді жеңілдетеді. Сондай-ақ бизнесіңізге болашақта басқа тасымалдаушыны қосу қажет болса, кеңейтуге ыңғайлы жол қалыптастырады.
Сұрау жібермес бұрын енгізілген деректерді тексеріңіз, бірақ пішімі өзгергендіктен немесе жапсырма жақында жасалғандықтан жарамды идентификаторды қабылдамай қоятын тым қатаң тексеруді қолданбаңыз. API жауабы негізгі тексеру болып қала береді. Бастапқы мәнді, іздеу үшін пайдаланылатын қалыпқа келтірілген мәнді, тасымалдаушыны, тапсырыс сілтемесін және соңғы сәтті сұрау уақытын сақтаңыз.
3. Құрылымдалған жауап схемасы
Пайдалы UPS tracking API құжаттамасы жөнелтілім деректерінің қалай ұйымдастырылатынын және қай өрістердің міндетті емес екенін түсіндіреді. Әзірлеушілер жауап моделінен жөнелтілім идентификациясын, ағымдағы күйді, күй сипаттамасын, сканерлеу уақыт белгілерін, орналасқан жерлерді, жеткізу болжамдарын, қызмет туралы ақпаратты және пакет деңгейіндегі мәліметтерді тексеруі керек. Өрістің болмауы бос мәні бар өріспен бірдей емес, сондай-ақ олардың ешқайсысын автоматты түрде сәтсіз жөнелтілім деп санауға болмайды.
Бүкіл қолданбаны провайдерге тән өріс атауларына тікелей байланыстырмай, қалыпқа келтірілген ішкі модель құрыңыз. Мысалы, дерекқорыңыз жөнелтілім идентификаторын, тасымалдаушыны, ағымдағы күйді, соңғы оқиға уақытын, болжамды жеткізу уақытын, жеткізілген уақытты, ерекше жағдай кодын және провайдердің бастапқы payload деректерін сақтай алады. Қалыпқа келтірілген өрістер есептер мен пайдаланушы интерфейстерін қолдайды, ал бастапқы payload аудиттер мен болашақтағы сәйкестендіру өзгерістерін қолдайды.
Берілген жағдайда уақыт белгілерін олардың UTC ығысуы немесе уақыт белдеуі туралы ақпаратпен бірге сақтаңыз. Бір орналасқан жердегі сканерлеуді көрушінің жергілікті уақытында болғандай көрсету жеткізу барысы туралы түсініксіз баяндау тудыруы мүмкін. Сол сияқты тасымалдаушының егжей-тегжейлі күйін бизнес ережесі құжатталмайынша қарапайым белгіге айналдырмаңыз.
4. Сканерлеу тарихы және күйді түсіндіру
UPS tracking құндылығы көбіне бір ағымдағы белгіден емес, оқиғалар тізбегінен көрінеді. Пакет жапсырманы жасаудан, алып кетуден, тасымалдаудан, келу сканерлеуінен, ерекше жағдайдан, жеткізуге шығарылудан және жеткізуден өтуі мүмкін. Пайдалы интеграция оқиғаларды ретімен сақтап, мүмкіндігінше олардың бастапқы сипаттамаларын сақтайды.
Күйлерді сәйкестендіру редакциялық және операциялық пайымдауды қажет етеді. «Тасымалдау үстінде» бірнеше түрлі кезеңді қамтуы мүмкін, ал «ерекше жағдай» күй атауынан нақтырақ түсіндіруді қажет етуі ықтимал. Қолданбаңыз кемінде қалыпты қозғалысты, жеткізу белсенділігін, жеткізілгенді, ерекше жағдайды, қайтарылғанды және әлі анықталмаған күйді ажыратуы керек. Нақты сәйкестендіру UPS құжаттамасында көрсетілген өрістер мен кодтарға негізделуі тиіс, тек ағылшынша сипаттамаларға сүйенбеуі керек.
Клиенттерге арналған беттерде соңғы маңызды оқиғаны, оның уақытын және қысқа түсіндірмесін көрсетіңіз. Ішкі операциялар үшін оқиғалардың толық тарихын және тасымалдаушының бастапқы мәтінін сақтаңыз. Бұл қолдау қызметкерлеріне жүйе алған ақпаратты клиенттен қайта сұрамай-ақ шағымды зерттеуге мүмкіндік береді.
5. Жеткізу болжамдары және ерекше жағдайларды өңдеу
Әзірлеушілер көбіне қалыпты сценарийге назар аударады, бірақ жеткізу болжамдары мен ерекше жағдайлар бақылау деректерінің тәжірибеде пайдалы болуын анықтайды. Жөнелтілімде болжам болмауы, болжамның өзгеруі немесе ерекше жағдай қалыпты қозғалысты уақытша тоқтатуы мүмкін. Құжаттамадан осы жағдайларды көрсететін өрістер мен шарттарды тексеру керек.
Тиісті UPS қызмет шарттары бұл түсіндірмені нақты қолдамаса, болжамды ешқашан кепілдік ретінде көрсетпеңіз. Пайдаланушы интерфейсінде болжамды болжам деп белгілеңіз және күнді немесе уақыт аралығын деректер қолдайтындай дәл көрсетіңіз. API болжамды өткізіп жіберсе, жалпы тасымалдау уақыты ережесі бойынша ойдан құрастырмай, «Қазіргі уақытта жеткізу болжамы қолжетімді емес» сияқты бейтарап хабарлама көрсетіңіз.
Ерекше жағдайларға арналған жұмыс үдерістері нақты болуы керек. Жаңа ерекше жағдай электрондық поштаға, қолдау қызметінің тапсырмасына, тапсырысты басқару әрекетіне немесе тек күй өзгерісіне әкелетінін шешіңіз. Қайта-қайта сұрау бір ескертуді бірнеше рет жібермеуі үшін қайталануды жоюды қосыңыз. Практикалық ереже — жаңа хабарландыру жасамас бұрын оқиға идентификаторын немесе оқиға уақыты, күйі және сипаттамасының тұрақты үйлесімін салыстыру.
6. Қателер, қайталап көру және операциялық шектеулер
API құжаттамасын тек сәтті мысалдар тізімі емес, операциялық келісім ретінде оқу керек. Әзірлеушілер аутентификация қателерін, жарамсыз сұрауларды, белгісіз бақылау нөмірлерін, уақытша қызмет ақауларын, тайм-ауттарды және сұрау жиілігі шегіне қатысты жауаптарды түсінуі қажет. Әр санатқа әртүрлі жауап берілуі тиіс.
- Аутентификация қателері инженерлік ескерту тудыруы керек және шексіз қайталанбауы тиіс.
- Тексеру қателері сұрауды түзетуге жеткілікті контекстпен тіркелуі керек.
- Уақытша ақаулар экспоненциалды кідіріспен және әрекеттердің ең көп санымен қайталап тексерілуі мүмкін.
- Белгісіз немесе жаңадан жасалған бақылау нөмірлерін кейінірек қайта тексеруге болады, бірақ оларды жоғалған деп жіктеуге болмайды.
- Сұрау жиілігі шегіне қатысты жауаптар бақылау кестесін баяулатып, ағымдағы UPS құжаттамасында көрсетілген шектерді сақтауы керек.
Тайм-ауттарды, circuit breaker механизмдерін, сұрау идентификаторларын және құрылымдалған журналдарды қолданыңыз. Қолжетімділік токендері мен қажетсіз жеке ақпаратты қоспай, провайдер жауабының күйін, ішкі жөнелтілім идентификаторын және уақыт белгісін сақтаңыз. Құжаттамада жауап тақырыптары немесе қайталап көру жөніндегі нұсқаулар көрсетілсе, жалпы саясат қолданбай, сол нұсқауларды іске асырыңыз.
7. Тестілеу, мониторинг және өндіріске дайындық
Бақылау API интеграциясын бір ғана сәтті бақылау нөмірімен шектелмей тестілеу керек. Жаңадан жасалған жапсырма, бірнеше сканерлеуі бар жөнелтілім, ерекше жағдай, жеткізілген пакет, белгісіз нөмір, мерзімі өткен тіркелгі деректері, қате пішімделген сұрау, тайм-аут және қайталанған оқиға үшін тест жағдайларын жасаңыз. Нақты тест деректері мен sandbox мінез-құлқы UPS әзірлеу ортасында расталуы тиіс, өйткені нақты жөнелтілім деректері мен тест орталары әрдайым бірдей жұмыс істей бермейді.
Техникалық және бизнес нәтижелерін де бақылаңыз. Техникалық көрсеткіштерге сұрау көлемі, кідіріс, тайм-аут деңгейі, аутентификация қателері, провайдер қателерінің деңгейі және қайталап көру саны жатады. Бизнес көрсеткіштеріне соңғы оқиғасы бар жөнелтілімдердің пайызы, жаңартылмаған ең ескі жөнелтілімнің жасы және ерекше жағдай әсер еткен тапсырыстар саны жатады. Егер сұрау немесе оқиғаларды өңдеу тоқтаса, HTTP қателерінің деңгейі төмен болғанымен, қызмет ескірген бақылау ақпаратын ұсынуы мүмкін.
Іске қоспас бұрын сұрауларды тоқтату, тіркелгі деректерін ауыстыру, сәтсіз жауаптарды қайта ойнату, қате күй сәйкестігін түзету және UPS қолдау қызметіне хабарласу тәртібін құжаттаңыз. Тексеру үшін қажет болса, провайдердің payload деректерін бақылаулы сақтау мерзімі ішінде сақтаңыз және құпиялылық пен деректерді сақтау талаптарын тиісті жауапты тұлғамен қарастырыңыз.
Тікелей UPS интеграциясы ма, әлде бірнеше тасымалдаушыға арналған API ме?
UPS жалғыз тасымалдаушы болғанда, команда тасымалдаушыға тән модельді басқарғысы келгенде және қажетті UPS API қолжетімді болғанда, тікелей UPS интеграциясы орынды таңдау болып табылады. Ол UPS терминологиясы мен операциялық үдерістеріне жақын сәйкестікті қамтамасыз ете алады.
Бір қолданба UPS, пошта операторлары және басқа логистикалық провайдерлердің сәлемдемелерін бақылауы қажет болса, бірнеше тасымалдаушыға арналған API архитектуралық тұрғыдан қолайлырақ болуы мүмкін. Техникалық шешім қабылдамас бұрын 17TRACK API documentation құжаттамасынан ағымдағы аутентификация моделін, қолдау көрсетілетін операцияларды, жауап құрылымын, webhook мінез-құлқын, пайдалану шарттарын және тасымалдаушылар қамтуын қарау керек. Бұл сценарийдегі оның құндылығы құжаттама қажеттілігін алмастыруында емес, әзірлеу тобының бір интеграция қабатын бірнеше тасымалдаушыға тән байланысты қолдау құнымен салыстыра алуында.
Салыстыруды proof of concept арқылы жасаңыз. Әр нұсқа үшін бірдей жөнелтілім өмірлік циклін пайдаланып, іске асыру күшін, өрістердің толықтығын, оқиғалардың жаңалығын, қайталап көру мінез-құлқын, webhook немесе polling талаптарын, бақыланымдылықты және тасымалдаушы жауабын өзгерткенде қажет жұмысты өлшеңіз. Провайдерді тек үлгі сұрауы қысқа болғаны үшін таңдамаңыз. Қолданбаңыз қамтамасыз етуі тиіс операциялық нәтижені қолдайтын нұсқа — жақсырақ таңдау.
Іске асырудың практикалық реті
- Клиенттерге арналған бақылау беті немесе ерекше жағдайлар кезегі сияқты пайдаланушы және операциялық нәтижелерді анықтаңыз.
- Ауқым тек UPS-пен шектеле ме, әлде бірнеше тасымалдаушыны қамти ма — растаңыз.
- Аутентификация, бақылау сұраулары, жауап өрістері, қателер, шектеулер және тестілеу жөніндегі ағымдағы ресми құжаттаманы оқыңыз.
- Провайдерге тәуелсіз жөнелтілім және оқиға моделін жасаңыз.
- Сервер жағындағы қауіпсіз аутентификация мен енгізілген деректерді тексеруді іске асырыңыз.
- Бастапқы жауаптар мен қалыпқа келтірілген өрістерді бөлек сақтаңыз.
- Қайталануды жою және кідірту арқылы polling немесе оқиғаларды қабылдауды қосыңыз.
- Қалыпты, кешіккен, ерекше, белгісіз және сәтсіз сұрауларды тестілеңіз.
- Жаңалықты, ақауларды және ескірген жөнелтілімдерді бақылау арқылы іске қосыңыз.
Бұл реттілік API шақыруының бүкіл дизайнға айналып кетуіне жол бермейді. Бақылау — үздіксіз деректер үдерісі: қолданба оқиғаларды алуы, оларды мұқият түсіндіруі, анық көрсетуі және провайдер немесе желі қолжетімсіз болғанда қалпына келуі керек.
Жиі қойылатын сұрақтар
UPS tracking API құжаттамасынан алдымен нені оқуым керек?
Аутентификациядан және бақылау операциясынан бастаңыз. Содан кейін сұрау талаптарын, жауап өрістерін, қателердің мінез-құлқын, пайдалану шектерін және тестілеу нұсқауларын қарастырыңыз. Бұл бөлімдер толық интеграцияға инвестиция салмас бұрын API-дің қауіпсіздік моделіңіз бен деректер талаптарыңызға сәйкес келетінін көрсетеді.
Клиенттерге арналған бақылау беті үшін UPS tracking API пайдалана аламын ба?
Иә, API клиенттерге арналған бетке деректер бере алады, бірақ API тіркелгі деректерін браузерде ашпау үшін бет backend арқылы ұсынылуы керек. Бетті ағымдағы күйді, сканерлеу тарихын, болжамдарды және ерекше жағдайларды ажырататындай етіп құрыңыз және болжамдарды кепілдік ретінде көрсетпеңіз.
Бақылау нөмірлерін үздіксіз polling арқылы тексеру керек пе?
Міндетті емес. Polling жиілігі жөнелтілім кезеңіне, бизнес маңыздылығына, құжатталған пайдалану шектеріне және оқиғаларға негізделген опцияның бар-жоғына сай болуы керек. Өзгермеген жөнелтілімдер үшін кідірісті қолданыңыз және жеткізілгеннен немесе қайтарудың соңғы күйінен кейін polling-ті тоқтатыңыз немесе азайтыңыз.
Белгісіз бақылау нөмірі мен жоғалған пакеттің айырмашылығы қандай?
Белгісіз бақылау нөмірі ағымдағы сұрау танылған жөнелтілім нәтижесін қайтармағанын білдіреді. Нөмір жаңадан жасалған, қате енгізілген, қате тасымалдаушыға бағытталған немесе уақытша қолжетімсіз болуы мүмкін. Оны бөлек бизнес үдерісі мен растайтын дәлелдерсіз жоғалған деп белгілеуге болмайды.
Бірнеше тасымалдаушыға арналған бақылау API-сін қашан қарастырған жөн?
Қолданбаңыз бірнеше тасымалдаушыны қолдауы керек болғанда немесе бөлек аутентификацияны, схемаларды, күй сәйкестіктерін және қате саясаттарын жүргізу елеулі операциялық жұмыс тудыратын кезде оны бағалаған жөн. Провайдерлерді нақты жөнелтілім сценарийлері арқылы салыстырыңыз және ағымдағы тасымалдаушылар мен мүмкіндіктер туралы ақпаратты олардың ресми құжаттамасынан тексеріңіз.
Дереккөздер
- UPS Developer Portal — UPS API өнімдеріне, қолданбаны баптауға, аутентификацияға және әзірлеуші ресурстарына арналған ресми қолжетімділік нүктесі.
- UPS Tracking — UPS-тің ресми бақылау қызметі және терминология анықтамалығы.
- 17TRACK Tracking API — бірнеше тасымалдаушыға арналған бақылау интеграциясын бағалауға арналған ресми өнім беті.
- 17TRACK API Documentation — ағымдағы API мәліметтері мен интеграция талаптарына арналған ресми әзірлеуші құжаттамасы.
