UPS Tracking API пайдалану жолы: қадамдық баптау нұсқаулығы

UPS Tracking API пайдалану үшін UPS Developer аккаунтын жасаңыз, қолданбаны тіркеңіз, OAuth 2.0 тіркелгі деректерін алыңыз, қатынау токенін сұратыңыз және жарамды UPS бақылау нөмірімен аутентификацияланған бақылау сұрауларын жіберіңіз. Порталдағы нақты атаулар, мақұлдау қадамдары және API талаптары өзгеруі мүмкін, сондықтан өндірістік интеграцияны іске қоспас бұрын ресми UPS Developer Portal жүйесіндегі ағымдағы нұсқауларды тексеріңіз.

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

UPS Tracking API не істейді

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

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

Бастамас бұрын

Әзірлеушілер порталына кірмес бұрын келесі элементтерді дайындаңыз:

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

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

1-қадам: UPS Developer Portal жүйесін ашу

ресми UPS Developer Portal жүйесінен бастаңыз. Ағымдағы API каталогын, аутентификация нұсқауларын, қосылу талаптарын, шарттарды және орталар туралы ақпаратты қарап шығыңыз. Басқа UPS қызметіне арналған нұсқаулар бақылауға да қолданылады деп болжамай, Tracking API құжаттамасын арнайы іздеңіз.

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

2-қадам: Қолданбаны тіркеу

Әзірлеушілер порталында қолданба жасап, қолданбаға нақты қажет UPS API интерфейстерін таңдаңыз. Тек бақылауға арналған жоба үшін жұмыс процесі қосымша қызметтерді талап етпесе, тек бақылау мүмкіндігін сұраңыз. Рұқсаттарды шектеу конфигурация күрделілігін азайтып, кейінгі ақауларды жоюды жеңілдетеді.

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

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

3-қадам: OAuth 2.0 аутентификациясын іске асыру

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

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

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

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

4-қадам: Бақылау сұрауын жасау

Ресми Tracking API анықтамалығында көрсетілген сұрау пішімін пайдаланыңыз. Әдеттегі сұрауға жолдағы немесе сұрау параметрлеріндегі бақылау нөмірі, авторизация тақырыбындағы қатынау токені және UPS API талап ететін тақырыптар кіреді. Бақылау нөмірі ғана қажет деп болжамаңыз: ағымдағы анықтамалықта нұсқа, транзакция, content-type немесе корреляция тақырыптары көрсетілуі мүмкін.

Жеңілдетілген сұрау үлгісі мынадай:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

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

5-қадам: Оқиғаларды деректер моделіне талдау

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

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

Әр күйді соңғы жеткізу нәтижесі ретінде қарастырмаңыз. Мысалы, жолдағы оқиға, ерекшелік, жеткізу әрекеті және жеткізілді оқиғасы бір клиент хабарламасына біріктірілмеуі керек. Нақты сәйкестіктер жасаңыз және UPS кодыңыз танымайтын оқиға мәнін қосқан жағдайда не болатынын анықтаңыз.

6-қадам: Қайталап сұрау, тексеру және мониторинг қосу

Өндірістік интеграция әзірлеу консоліндегі сәтті сұраудан да көп нәрсені талап етеді. Тексеру мен операциялық қауіпсіздік шараларын қосыңыз:

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

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

7-қадам: Шынайы жағдайлармен сынақтан өткізу

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

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

Көп тасымалдаушыға арналған Tracking API қашан тиімдірек

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

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

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

Жиі кездесетін іске асыру қателері

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

Өндірісте іске қосуға арналған практикалық тексеру тізімі

1. Қолданбаның ағымдағы UPS құжаттамасы мен мақұлданған ортаны пайдаланып жатқанын растаңыз.
2. Тіркелгі деректерінің сервер жағында сақталатынын және ауыстырылатынын тексеріңіз.
3. Аутентификация қателерін, тасымалдаушы қателерін, қате пішімделген кіріс деректерін және тайм-ауттарды сынаңыз.
4. Өкілдік жөнелтілімдер үшін қалыпқа келтірілген күйлерді бастапқы жауаппен салыстырыңыз.
5. Жаңарту саясатын орнатып, сұрау көлемін бақылаңыз.
6. Анықталмаған оқиғаларға, кешіктірілген жаңартуларға және клиент шағымдарына кім жауап беретінін белгілеңіз.
7. Басқа әзірлеуші тіркелгі деректерін, соңғы нүкте нұсқаларын және күй сәйкестіктерін қауіпсіз жаңарта алуы үшін интеграцияны құжаттаңыз.

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

Tracking API пайдалану үшін UPS аккаунты қажет пе?

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

UPS Tracking API тегін бе?

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

UPS API интерфейсіне браузердегі JavaScript арқылы тікелей қоңырау шала аламын ба?

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

Қолданбам бақылау жаңартуларын қаншалықты жиі сұрауы керек?

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

UPS-пен тікелей интеграцияны немесе көп тасымалдаушы API интерфейсін пайдалануым керек пе?

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

Дереккөздер

• UPS Developer Portal — ресми API каталогы, қолданбаға қатынау, аутентификация және әзірлеушілер құжаттамасы.
• UPS Technology Integration — UPS технологиясын бизнес жүйелерімен интеграциялау туралы ресми ақпарат.
• 17TRACK Tracking API — көп тасымалдаушы бақылауына арналған ресми өнім және әзірлеушілерге арналған бастапқы бет.
• 17TRACK API Documentation — аутентификация, сұраулар және жауаптарды өңдеуге арналған ресми API құжаттамасы.