Како да го користите API-то за следење на UPS: Водич за поставување чекор по чекор

За да го користите 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, упатствата за автентикација, барањата за започнување, условите и информациите за околината. Побарајте ја конкретно документацијата за Tracking API, наместо да претпоставите дека упатствата за друга UPS услуга важат и за следењето.

Порталот е соодветен извор за тековните полиња на барањата, опсезите за авторизација, дефинициите на одговорите, ограничувањата на стапката, кодовите за грешки и деталите за околината. Овие детали може да се променат, а примерот на код од трета страна може да користи постар UPS интерфејс или застарен метод за автентикација.

Чекор 2: Регистрирајте апликација

Креирајте апликација во порталот за развивачи и изберете ги UPS API што навистина ѝ се потребни на апликацијата. За проект што користи само следење, побарајте само можност за следење, освен ако вашиот работен тек не бара дополнителни услуги. Ограничувањето на дозволите ја намалува сложеноста на конфигурацијата и го олеснува подоцнежното отстранување на проблеми.

Идентификаторот и тајната на апликацијата чувајте ги во менаџер за тајни на серверот или во заштитен систем со променливи на околината. Постапувајте со тајната како со лозинка. Ако биде откриена, променете ја преку процесот што го обезбедува UPS и прегледајте ги дневниците за неовластена употреба.

Ако порталот побара информации за сметката, наплатата, деловното работење или апликацијата, наведете точни податоци. Не измислувајте сценарио за продукциска употреба и не користете туѓи податоци за сметка само за да завршите тест. Пристапот до услугата може да зависи од конфигурацијата на сметката и тековниот процес на одобрување од UPS.

Чекор 3: Имплементирајте OAuth 2.0 автентикација

Тековната документација за развивачи на UPS користи автентикација заснована на OAuth за своите API. Вашиот сервер обично ги разменува акредитивите на апликацијата преку документираниот тек за добивање токен и добива токен за пристап. Потоа го вклучува тој токен во заглавието за авторизација на барањето до API.

Автентикацијата одржувајте ја одвоена од логиката за следење. Практичниот дизајн има една компонента што добива и кешира валиден токен и друга што го повикува крајниот пункт за следење. Компонентата за токен треба:

• Да испраќа акредитиви само до документираниот краен пункт за авторизација на UPS.
• Да ги користи типот на содржина и параметрите за доделување наведени во тековната документација на UPS.
• Привремено да го складира токенот и повторно да го користи додека не истече, наместо да бара нов токен за секој број за следење.
• Да го обнови или повторно да го добие токенот кога ќе настапи документираниот услов за истекување.
• Да ги маскира акредитивите и токените во дневниците на апликацијата, извештаите за грешки и тикетите до поддршката.

Не копирајте токен од сесија во прелистувачот во трајна интеграција. Заднинската услуга обично е побезбедно место за управување со акредитивите бидејќи ги чува тајните подалеку од јавниот клиентски код.

Чекор 4: Изградете го барањето за следење

Користете го форматот на барањето прикажан во официјалната референца за Tracking API. Типичното барање вклучува број за следење во патеката или параметрите на барањето, токен за пристап во заглавието за авторизација и заглавија што ги бара UPS API. Не претпоставувајте дека бројот за следење е единствената потребна вредност: тековната референца може да наведува заглавија за верзија, трансакција, тип на содржина или корелација.

Поедноставениот образец на барањето изгледа вака:

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

Ова е структурен пример, а не краен пункт за копирање и залепување. Користете ги крајниот пункт, верзијата, заглавјата и имињата на параметрите објавени во документацијата на UPS за вашата апликација. Бројот за следење одржувајте го нормализиран според правилата за вашите сопствени податоци за нарачки, но не отстранувајте знаци освен ако документацијата на превозникот не потврди дека тоа е безбедно.

Чекор 5: Внесете ги настаните во вашиот модел на податоци

Одговорите од превозникот често содржат повеќе информации од една статусна ознака. Пред да ја програмирате страницата наменета за клиентите, пресликајте го одговорот во интерен модел, како што се идентификатор на пратката, превозник, последен статус, код на настанот, опис на настанот, временски печат на настанот, локација, информации за проценетата достава и временски печат на доставата кога е достапен.

Зачувајте го оригиналниот одговор од превозникот кога тоа го дозволуваат вашите политики за задржување и приватност. Необработениот одговор може да помогне при дијагностицирање грешка во пресликувањето или да објасни зошто вашиот нормализиран статус се разликува од формулацијата на превозникот. Истовремено, избегнувајте прикажување технички кодови на настани на клиентите без разбирливо објаснување.

Не третирајте го секој статус како конечен исход на доставата. На пример, настан во транзит, исклучок, обид за достава и настан на доставена пратка не треба да се сведат на иста порака за клиентот. Создадете експлицитни пресликувања и дефинирајте што се случува кога UPS ќе додаде вредност на настанот што вашиот код не ја препознава.

Чекор 6: Додајте повторни обиди, валидација и следење

Продукциската интеграција бара повеќе од успешно барање во развојна конзола. Додајте валидација и оперативни заштитни мерки:

• Валидација на внесот: одбијте празни, неправилно форматирани или очигледно нецелосни броеви за следење пред да испратите барања.
• Истек на време: спречете бавниот одговор од превозникот да блокира цел работен тек за наплата, поддршка или магацин.
• Правила за повторен обид: внимателно повторете ги привремените мрежни или услужни грешки, со постепено зголемување на интервалот. Не повторувајте постојано грешки при автентикација или невалидни броеви за следење.
• Следење на ограничувањата: почитувајте ги ограничувањата и правилата за употреба во документацијата на UPS. Кеширајте ги неодамнешните резултати кога тоа го дозволува вашиот деловен процес.
• Непознати состојби: зачувајте непрепознаен настан за преглед, наместо лажно да го означите како доставен или изгубен.
• Набљудливост: бележете го времето на барањето, категоријата на одговорот и информациите за корелација без да запишувате тајни или непотребни лични податоци.

Системот за следење треба да дефинира и колку често ја освежува пратката. Премногу честото испитување може да создаде непотребно оптоварување и можеби нема да донесе нови информации. Премногу реткото испитување може да направи страницата наменета за клиентите да изгледа застарено. Изберете интервал врз основа на обемот на пратките, оперативната итност, правилата на превозникот и свежината што навистина им е потребна на корисниците.

Чекор 7: Тестирајте со реални сценарија

Тестирајте повеќе од успешно доставена пратка. Вклучете непознат број за следење, пратка во транзит, исклучок, пратка со повеќе настани, истечен токен, истек на време, неуспешна авторизација и одговор што содржи полиња што вашиот анализатор не ги очекува. Ако UPS обезбедува посебна тестна околина или тестни акредитиви, прво следете ја таа постапка.

Проверете ја целата патека од барањето до корисничкиот интерфејс. Потврдете дека точната нарачка ја добива точната пратка, дека временските печати се прикажуваат во планираната временска зона, дека дупликатите настани не создаваат дупликат пораки за клиентите и дека прекинот на услугата на превозникот не го заменува претходно валидниот статус со погрешен текст.

Кога API за следење од повеќе превозници е подобар избор

Директната интеграција со UPS може да биде соодветна кога вашето работење главно испраќа преку UPS и бара тесна контрола врз работниот тек на превозникот. Таа станува помалку практична кога нарачките може да се движат преку повеќе превозници, пазари, поштенски оператори или регионални компании за достава. Во таква ситуација, одделните акредитиви, формати на одговори, речници на статуси и правила за повторен обид може да ја зголемат работата за одржување.

Услуга за повеќе превозници како 17TRACK Tracking API може да обезбеди алтернативен модел на интеграција за апликации на кои им е потребно следење преку повеќе превозници. Нејзината документација за развивачи треба директно да се прегледа за поддржаните превозници, форматите на барањата, автентикацијата, условите за употреба и достапните можности. Ова не значи дека таа автоматски е подобра од директната врска со UPS: вистинскиот избор зависи од комбинацијата на превозници, барањата за податоци, контролата врз интеграцијата и комерцијалните или усогласувачките ограничувања.

За пребарување наменето за потрошувачи, наместо интеграција за развивачи, страницата за следење на 17TRACK може да биде посоодветна од градење API врска. За онлајн продавница на која ѝ се потребни брендирани ажурирања по купувањето, разгледајте ја соодветната интеграција со платформата одделно, наместо да додавате API работа што продавницата не ја бара.

Вообичаени грешки при имплементацијата

• Користење стари примери: примерот на код може да се однесува на повлечена верзија, стар метод за автентикација или друга UPS услуга.
• Ставање тајни во фронтенд-кодот: сè што се испорачува до прелистувач треба да се смета за достапно за преглед.
• Претпоставка дека празен резултат значи дека нема пратка: проверете го бројот за следење, дозволите на сметката, околината и пораката во одговорот пред да донесете деловен заклучок.
• Пресликување само на текст: описите на статусите може да се разликуваат. Користете документирани кодови и зачувајте ги непознатите вредности за преглед.
• Игнорирање на барањата за сметката и употребата: техничкиот код може да биде исправен, а апликацијата сепак да не е конфигурирана за бараната услуга.
• Освежување без деловно правило: непотребното испитување може да ги зголеми трошоците, оптоварувањето и оперативниот шум без да го подобри корисничкото искуство.

Практична листа за проверка пред пуштање во работа

1. Потврдете дека апликацијата ја користи тековната документација на UPS и одобрената околина.
2. Проверете дали акредитивите се складираат на серверот и може да се ротираат.
3. Тестирајте неуспешна автентикација, грешки на превозникот, неправилен внес и истек на време.
4. Споредете ги нормализираните статуси со оригиналниот одговор за репрезентативни пратки.
5. Поставете политика за освежување и следете го обемот на барањата.
6. Дефинирајте одговорност за неидентификувани настани, задоцнети ажурирања и ескалации од клиенти.
7. Документирајте ја интеграцијата за друг развивач безбедно да може да ги ажурира акредитивите, верзиите на крајните пунктови и пресликувањата на статусите.

Најчесто поставувани прашања

Дали ми е потребна UPS сметка за да го користам Tracking API?

Треба да ги прегледате тековните барања на 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 документација за автентикација, барања и обработка на одговори.