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

Чувајте ги акредитивите на серверската страна. Тие не треба да бидат вградени во JavaScript во прелистувачот, мобилни верзии, јавни репозиториуми или кодот на страницата за следење што е видлив за клиентите. Посигурната архитектура поставува backend услуга помеѓу апликацијата насочена кон клиентите и UPS. Таа услуга може безбедно да се автентицира, да ги спроведува ограничувањата на барањата, да ги евидентира техничките резултати без откривање тајни и да ги враќа само податоците за пратката што му се потребни на frontend-от.

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

2. Барања со број за следење и контекст на превозникот

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

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

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

3. Структурирана шема на одговор

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

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

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

4. Историја на скенирања и толкување на статусот

Вредноста на UPS tracking често е во низата настани, а не во една единствена тековна ознака. Пакетот може да помине низ креирање етикета, преземање, транспорт, скенирање при пристигнување, исклучок, настан „на испорака“ и испорака. Корисната интеграција ги чува настаните по редослед и ги задржува нивните оригинални описи каде што е можно.

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

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

5. Проценки за испорака и справување со исклучоци

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

Никогаш не прикажувајте проценка како гаранција освен ако релевантните услови за услугата на UPS изречно не поддржуваат такво толкување. Во корисничкиот интерфејс означете ја проценката како проценка и прикажете го датумот или временскиот интервал точно онака како што го поддржуваат податоците. Ако API-ето не врати проценка, прикажете неутрална порака како „Моментално нема достапна проценка за испорака“, наместо да измислувате проценка врз основа на општо правило за времето на транспорт.

Работните текови за исклучоци треба да бидат експлицитни. Одлучете дали нов исклучок активира е-пошта, задача во help desk, дејство во управувањето со нарачката или само промена на статусот. Додајте дедупликација за повтореното анкетирање да не го испраќа истото известување повеќепати. Практично правило е да се спореди идентификаторот на настанот или стабилна комбинација од времето на настанот, статусот и описот пред да се создаде ново известување.

6. Грешки, повторни обиди и оперативни ограничувања

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

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

Користете истекувања на времето, прекинувачи на кола, идентификатори на барања и структурирани дневници. Чувајте го статусот на одговорот од давателот, интерниот ID на пратката и временската ознака, при што исклучете ги токените за пристап и непотребните лични информации. Ако документацијата наведува заглавија на одговорот или упатства за повторен обид, вклучете ги тие инструкции наместо да применувате општа политика.

7. Тестирање, следење и подготвеност за продукција

Интеграцијата со API за следење треба да се тестира со повеќе од еден успешен број за следење. Создајте тест случаи за новосоздадена етикета, пратка со неколку скенирања, исклучок, испорачан пакет, непознат број, истечена акредитација, неправилно барање, истекување на времето и дупликат настан. Точните тест-податоци и однесувањето на sandbox-от мора да се потврдат во средината за програмери на UPS, бидејќи податоците од реални пратки и тест-околините не се однесуваат секогаш идентично.

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

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

Директна UPS интеграција или API за повеќе превозници?

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

API за повеќе превозници може да биде подобро архитектонско решение кога истата апликација мора да следи пратки од UPS, поштенски оператори и други логистички даватели. 17TRACK API documentation треба да се разгледа за неговиот тековен модел на автентикација, поддржаните операции, структурата на одговорите, однесувањето на webhook-ите, условите за користење и покриеноста на превозниците пред да се донесе техничка одлука. Неговата вредност во ова сценарио не е во тоа што ја заменува потребата од документација; туку во тоа што развојниот тим може да оцени еден интеграциски слој во однос на трошокот за одржување на неколку врски специфични за превозниците.

Направете споредба со proof of concept. Користете го истиот животен циклус на пратката за секоја опција и измерете го напорот за имплементација, целосноста на полињата, свежината на настаните, однесувањето при повторни обиди, барањата за webhook или анкетирање, видливоста и работата потребна кога превозникот ќе го промени својот одговор. Не избирајте давател само затоа што примерното барање е кратко. Подобро одговара оној што го поддржува оперативниот резултат што вашата апликација мора да го обезбеди.

Практичен редослед на имплементација

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

Овој редослед спречува повикот кон API да стане цел дизајн. Следењето е континуиран процес на податоци: апликацијата мора да добива настани, внимателно да ги толкува, јасно да ги прикажува и да се опоравува кога давателот или мрежата не се достапни.

Често поставувани прашања

Што прво треба да прочитам во документацијата за UPS tracking API?

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

Може ли да користам UPS tracking API за страница за следење насочена кон клиентите?

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

Дали броевите за следење треба постојано да се анкетираат?

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

Која е разликата помеѓу непознат број за следење и изгубен пакет?

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

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

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

Извори

• UPS Developer Portal — официјална точка за пристап до UPS API производите, поставувањето апликации, автентикацијата и ресурсите за програмери.
• UPS Tracking — официјална услуга за следење на UPS и референца за терминологијата.
• 17TRACK Tracking API — официјална страница на производот за проценка на интеграција за следење од повеќе превозници.
• 17TRACK API Documentation — официјална документација за програмери за тековните детали на API-ето и барањата за интеграција.