UPS Tracking API: Водич за почетници за започнување

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

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

Што прави UPS Tracking API

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

Тие податоци можат да поддржат неколку практични функции:

• Страница за следење вградена во онлајн продавница.
• Видливост на пратките во систем за управување со нарачки или систем за планирање на ресурсите на претпријатието.
• Екрани за корисничка поддршка што ја намалуваат потребата рачно да се проверува веб-страницата на превозникот.
• Внатрешни известувања за исклучоци при испорака, доцнења или завршени испораки.
• Пораки по купувањето врз основа на настани поврзани со пратката.

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

UPS Tracking API наспроти веб-страницата на UPS

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

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

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

Што ви е потребно пред да испратите барање

Подгответе ги следните ставки пред да започнете со интеграцијата:

1. UPS развивачка сметка. Користете го официјалниот UPS Developer Portal за да ги прегледате достапните API и да креирате апликација.
2. Акредитиви на апликацијата. Точните имиња на акредитивите и текот на автентикацијата треба да ги преземете од тековната документација на UPS. Не ставајте клиентски тајни во код на прелистувач, мобилни апликации, јавни складишта или страници видливи за клиентите.
3. Валиден број за следење за тестирање. Тестирајте со пратки до кои вашата организација е овластена да пристапи и избегнувајте изложување лични или деловни податоци за пратките во дневниците.
4. Серверска точка за интеграција. Backend услуга обично е побезбедна од директно повикување на превозникот од јавна веб-страница, бидејќи може да ги чува акредитивите приватни и да го контролира бројот на барањата.
5. План за зачувување на одговорите. Одлучете кои полиња ви се потребни, колку долго ќе ги чувате и како ќе поврзете настан на превозникот со внатрешна нарачка.

Работен процес за интеграција погоден за почетници

1. Потврдете го деловното барање

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

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

2. Регистрирајте ја апликацијата

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

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

3. Имплементирајте автентикација

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

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

4. Испратете барање за следење

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

Концептуалното барање изгледа вака:

POST /tracking-operation
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "trackingNumber": "YOUR_TRACKING_NUMBER"
}

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

5. Нормализирајте го одговорот

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

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

Кога е можно, зачувајте го оригиналниот статус на превозникот. Нормализирана ознака како „Во транзит“ е корисна за корисничкиот интерфејс, но необработениот опис може да му помогне на персоналот за поддршка да истражи необичен настан.

6. Одлучете како ќе ги преземате ажурирањата

Некои системи користат планирано анкетирање: backend проверува подобни пратки во избрани интервали и ги зачувува промените. Други користат известувања за настани кога релевантната платформа ги поддржува. Не претпоставувајте дека секој UPS производ за следење нуди ист механизам за известување. Потврдете ја тековната документација и комерцијалните услови пред да дизајнирате работен процес базиран на webhook.

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

Вообичаени грешки и како да постапите со нив

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

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

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

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

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

Список за проверка на подготвеноста за продукција

• Акредитивите се зачувани во управувач на тајни и никогаш не се изложени во прелистувачот.
• Тестната и продукциската околина се јасно одделени.
• Барањата имаат временски ограничувања, контролирани повторни обиди и корисно евидентирање на грешките.
• Броевите за следење се потврдуваат пред испраќање.
• Системот го зачувува последното успешно ажурирање и избегнува да го замени со празен одговор.
• Необработените пораки на превозникот и ознаките видливи за клиентите се обработуваат одделно.
• Фреквенцијата на анкетирање ги следи објавените ограничувања на давателот и вашите оперативни потреби.
• Следењето може да открие неуспешни автентикации, зголемени стапки на грешки и застарени пратки.
• Персоналот за поддршка може да види доволно детали за да истражи прашање од клиент.
• Интеграцијата повторно се тестира кога UPS ќе ја промени документацијата, акредитивите, крајните точки или полињата во одговорот.

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

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

Дали ми треба API ако следам само неколку пакети?

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

Може ли да го повикам UPS Tracking API од Shopify тема или прелистувач?

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

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

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

Зошто валиден број за следење може да врати малку информации?

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

Дали треба да изберам директно UPS или API за следење со повеќе превозници?

Изберете директна врска кога UPS е главниот превозник и сакате фокусирана интеграција. Разгледајте услуга за повеќе превозници кога оперативната цел е еден работен процес за следење низ повеќе превозници. Тестирајте ги потребните превозници и сценаријата со настани пред да донесете конечна одлука.

Извори

• UPS Developer Portal
• Документација и ресурси за производот UPS Tracking API
• 17TRACK Tracking API
• Документација за 17TRACK API