Skip to main content
ДомаБлогВодичиКако да регистрирате број за следење преку API: полиња на барањето, кодови на превозниците и одговори

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

17TRACK

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

Како да регистрирате број за следење преку API полиња за барање

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

Што прави регистрацијата — а што не прави

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

Во вашата апликација одделно чувајте ги овие три настани:

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

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

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

Подгответе ги полињата на барањето пред да го напишете API повикот

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

Поле или вредностНаменаПравило за имплементација
Број за следењеЈа идентификува пратката што треба да се следи.Чувајте го и испраќајте го како текст; зачувајте ги почетните нули.
Идентификатор на превозникотГо идентификува превозникот во системот на давателот на следење.Користете го идентификаторот наведен од давателот, а не интерниот магацински код.
Интерна референцаЈа поврзува регистрацијата со записот за вашата пратка.Користете поддржано референтно поле ако е достапно; во секој случај задржете го сопственото мапирање во базата.
Дополнителни податоци за идентификацијаМоже да помогнат при идентификација на пратка кога превозникот бара повеќе од бројот за следење.Испраќајте само полиња документирани за таа интеграција и превозник.
API акредитивЈа автентифицира сметката што го испраќа барањето.Чувајте го на серверот и исклучете го од дневниците на апликацијата.

Однесувајте се кон бројот за следење како кон идентификатор

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

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

Чувајте ги референците на нарачките одделно од идентитетите на пратките

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

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

Изберете го точниот код на превозникот

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

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

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

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

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

Пример: испратете барање за регистрација до 17TRACK

Следниот пример ја прикажува крајната точка за регистрација на 17TRACK v2.2, заглавјето за автентикација 17token и низа што содржи еден објект со број за следење. Пред пуштање во употреба, потврдете дека оваа верзија и нејзините барања за испраќање се совпаѓаат со вашата сметка и официјалната документација. Бројот за следење е резервирана вредност и мора да се замени со вистински идентификатор на пратка.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

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

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

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

Читајте го одговорот на три нивоа

Сигурен обработувач на одговори одговара на три одделни прашања: дали барањето стигнало до сервисот, дали сервисот ја прифатил операцијата и што се случило со секоја пратка?

1. HTTP и транспортен резултат

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

2. Резултат на ниво на барање

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

Не претпоставувајте дека нумеричкиот код на апликацијата има исто значење како HTTP статусниот код. Нивните значења доаѓаат од различни слоеви и мора да се толкуваат одделно.

3. Резултат на ниво на пратка

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

Нормализирајте ги одговорите на давателот во сопствени стабилни состојби на апликацијата. На пример, вашата база може да користи accepted, rejected и uncertain. Ова се предложени интерни состојби, а не буквални вредности на одговорот од 17TRACK. Чувајте го оригиналниот одговор на давателот достапен според соодветна политика за задржување и пристап, за програмерите да можат да ги истражат несогласувањата.

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

Обработувајте повторни обиди без создавање бесконечна јамка

Политиката за повторни обиди треба да зависи од неуспехот, а не само од тоа дали се појавил исклучок.

  • Невалиден внес: поправете го полето пред повторниот обид. Повторувањето на непроменето невалидно барање веројатно нема да помогне.
  • Неуспех при автентикација: проверете ги акредитивите и конфигурацијата на сметката. Избегнувајте постојано испраќање на истата неуспешна серија.
  • Ограничување на стапката: следете ги документираните ограничувања и сите применливи упатства за повторување. Користете ограничено постепено зголемување на интервалот, наместо непосредни паралелни обиди.
  • Привремен неуспех на сервисот: повторете во рамките на дефиниран буџет на обиди и време.
  • Истек на времето по испраќањето: усогласете ја состојбата на регистрација на пратката користејќи го документираното однесување на API пред да претпоставите дека првиот обид не успеал.
  • Одговор поврзан со дупликат: проверете дали пратката веќе е регистрирана и правилно поврзана со записот во вашата апликација.

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

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

Следете ја регистрацијата одделно од ажурирањата за следење

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

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

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

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

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

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

Може ли да регистрирам број за следење пред првото скенирање од превозникот?

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

Дали секогаш треба да доставам код на превозник?

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

Зошто API врати HTTP успех, а пратката не успеа?

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

Што треба да направам кога барањето за регистрација ќе истече?

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

Дали регистрацијата автоматски ги конфигурира известувањата за следење?

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

Извори

  • 17TRACK API документација — референца за крајните точки за регистрација, автентикацијата, полињата на барањето, идентификаторите на превозниците, шемите на одговори и обработката на грешки. Усогласете ги деталите на имплементацијата со верзијата на API што ја распоредувате.
  • Преглед на 17TRACK Tracking API — официјална почетна точка за производот Tracking API и ресурсите за интеграција на програмери.