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

Кои податоци треба да ги враќа API-то за следење? 12 полиња покрај тековниот статус?

17TRACK

A tracking API треба да враќа повеќе од ознака како „Во транзит“. Покрај тековниот статус, побарајте идентификатори на пратката, идентитет на превозникот, детални информации за статусот, оригинални пораки од превозникот, историја на настани, временски ознаки на настаните, локации, проценки за испорака, исклучоци, предавања меѓу превозници, детали за испораката и метаподатоци за свежината на податоците. Заедно, овие 12 групи податоци им помагаат на програмерите да изградат сигурни работни процеси и им даваат на оперативните тимови доволно контекст за да дејствуваат.

Кои податоци треба да ги враќа Tracking API: 12 полиња покрај статусот

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

Што ги прави податоците за следење корисни?

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

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

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

12 полиња што треба да се оценат покрај тековниот статус

1. Идентификатори на пратката и следењето

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

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

2. Идентитет на превозникот

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

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

3. Нормализирани детали за статусот

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

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

4. Оригинални пораки и кодови од превозникот

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

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

5. Историја на настаните за следење

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

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

6. Временски ознаки на настаните и информации за временската зона

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

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

7. Локации на настаните и географија на пратката

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

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

8. Проценет датум или временски прозорец за испорака

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

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

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

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

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

10. Предавања меѓу превозници и поврзани броеви за следење

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

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

11. Резултат од испораката и референци за доказ

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

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

12. Свежина, состојба на преземањето и метаподатоци за одговорот

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

Успешното барање до API само по себе не утврдува дека превозникот објавил ново скенирање. Семантиката на HTTP одговорот го опишува исходот од барањето; напредокот на пратката припаѓа во податоците на апликацијата. Чувајте ги грешките при преземање одделно од исклучоците на пратката за привремен проблем со поврзувањето да не стане лажно известување за испорака.

На податоците што недостасуваат им треба дефинирано значење

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

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

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

Како да го тестирате одговорот пред интеграцијата

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

  1. Изградете репрезентативен примерок. Вклучете новорегистрирани пратки, активни пратки, обиди за испорака, завршени испораки и достапни случаи на предавање.
  2. Поврзете ги полињата со настаните. Потврдете дека прикажаниот статус, последниот настан и деталите за испораката опишуваат конзистентен запис. Истражете ги несогласувањата наместо да ги криете.
  3. Тестирајте одложени и повторени ажурирања. Повторно обработете ист податок и примете постар настан по понов. Потврдете дека ниту еден случај не создава дупликатни известувања или неправилно не ја враќа прикажаната состојба.
  4. Тестирајте недостасувачки и неправилно форматирани вредности. Вклучете отсутни проценки, непознати локации, непознати кодови на статус и нецелосни временски ознаки. Апликацијата треба да остане употреблива без измислување замени.
  5. Одделете ги транспортните неуспеси од резултатите од следењето. Неуспехот на автентикација, истекувањето на времето или неправилниот одговор треба да влезат во патека за интеграциски грешки, а не во работен процес за исклучок на пратка.
  6. Потврдете го приказот за клиентот. Проверете дали внатрешните референци, необработените дијагностички детали и личните информации не протекуваат на јавни страници или во известувања.

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

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

ЧПП

Дали секоја пратка треба да ги има пополнети сите 12 групи податоци?

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

Дали треба да го чуваме необработениот одговор или само нормализираните полиња?

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

Која временска ознака треба да го одреди најновиот настан?

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

Може ли Tracking API да потврди дека пакетот е изгубен?

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

Дали статусот „Испорачано“ е доволен за затворање жалба на клиент?

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

Извори