Какви данни трябва да връща един API за проследяване? 12 полета отвъд текущия статус?
Един API за проследяване трябва да връща повече от етикет като „В транзит“. Освен текущия статус потърсете идентификатори на пратката, самоличност на превозвача, подробна информация за статуса, оригинални съобщения от превозвача, история на събитията, времеви отметки на събитията, местоположения, прогнози за доставка, изключения, предаване между превозвачи, подробности за доставката и метаданни за актуалността на данните. Заедно тези 12 групи данни помагат на разработчиците да изграждат надеждни работни процеси и дават на оперативните екипи достатъчно контекст за предприемане на действия.

Това е препоръчителен договор за отговор за разработчици, технически купувачи и екипи за електронна търговия, а не твърдение, че всеки превозвач или API предоставя всяко поле. Някои стойности основателно може да не са налични. По-добрият дизайн прави тези пропуски явни, вместо да ги запълва с предположения.
Какво прави данните за проследяване полезни?
Текущият статус отговаря на един конкретен въпрос: какво е обобщеното състояние на пратката? Той не обяснява непременно какво се е случило, кога се е случило, дали информацията е актуална или какво трябва да направи някой след това.
Например две пратки могат и двете да показват „В транзит“, но да изискват различни реакции. Едната може да има скорошно сканиране в логистичен обект и да няма съобщен проблем. При другата в историята на събитията може да е записан неразрешен проблем с адреса. Приложение, което отчита само основния статус, може да пропусне тази разлика.
Оценете отговора спрямо три практически задачи: свързване на пратката с правилната поръчка, точно обяснение на нейното движение и преценка дали дадено действие е оправдано. Следващите полета подпомагат тези задачи. Имената на полетата са илюстративни; те не представляват универсален стандарт или схема на конкретен доставчик.
12 полета за оценка извън текущия статус
1. Идентификатори на пратката и проследяването
Отговорът трябва да идентифицира описваната пратка. Полезните стойности включват изпратения номер за проследяване, идентификатора на записа за проследяване в API и клиентска референция, която системата ви може да свърже със запис за изпълнение или пакет.
Не приемайте, че една поръчка е равна на една пратка. Поръчката може да бъде разделена на няколко пакета, а замяната може да създаде друга пратка. Съхранявайте записите за проследяване на ниво пакет или изпълнение, след което ги свързвайте с поръчката. Съхранявайте номерата за проследяване като низове, за да не се губят форматирането и водещите нули.
2. Самоличност на превозвача
Потърсете стабилен идентификатор на превозвача заедно с разбираемо име. Когато е налично, отговорът трябва да различава превозвач, посочен изрично от приложението ви, от превозвач, избран чрез автоматично разпознаване.
Контекстът за превозвача е важен при интерпретирането на номера за проследяване и неговите събития. Ако разпознаването е нееднозначно, интеграцията ви трябва да има начин да го разреши, вместо мълчаливо да представя несигурното съвпадение като потвърдено. Съхранявайте информацията за нивото на услугата отделно: самото име на превозвача не показва дали пратката използва експресна, пощенска или друга услуга.
3. Нормализирани подробности за статуса
Наред с основния статус поискайте документиран код за подробност или подстатус. Широка категория може да описва пратката като изключение, докато подробността уточнява неуспешен опит за доставка, проблем с адреса или задържане, свързано с митницата.
Използвайте стабилни кодове за бизнес логика и разбираеми етикети за представяне. Уточнете как доставчикът преобразува събитията на превозвача в тези кодове, включително как обработва неизвестни или несъпоставени събития. Нормализираният етикет улеснява използването на данни от различни превозвачи, но не трябва да заличава разликите, от които екипът за поддръжка се нуждае.
4. Оригинални съобщения и кодове на превозвача
Запазвайте оригиналното описание на събитието и кода на събитието от превозвача, когато са предоставени. Тези стойности дават на служителите по поддръжката контекст, който може да липсва в нормализирания статус, особено когато превозвачът използва специфична оперативна формулировка.
Съхранявайте оригиналния текст отделно от преведени или преработени описания. В противен случай обяснение за клиента може да бъде сбъркано с точната формулировка на превозвача. Третирайте текста на превозвача като ненадежден вход при показването му: екранирайте го правилно и не го визуализирайте като изпълним HTML.
5. История на събитията за проследяване
Полезният отговор трябва да показва времевата линия на пратката, а не само последното ѝ събитие. В идеалния случай всяко събитие трябва да включва идентификатор, статус или код, описание, времева отметка и налична информация за местоположението.
Проверете дали API връща пълната история, ограничен период или страницирани резултати. Уточнете също как се представят корекциите и дублиращите се наблюдения. Приложението ви не трябва да приема, че първият елемент винаги е най-новият, освен ако договорът за отговор изрично не гарантира този ред.
6. Времеви отметки на събитията и информация за часовата зона
Времето на настъпване на дадено събитие се различава от времето, когато API го е получило или върнало. Запазвайте и двете, когато са налични. Това разграничение помага да се обясни защо току-що получена актуализация може да описва нещо, случило се по-рано.
Искайте времеви отметки с изрични отмествания спрямо UTC или UTC обозначение. RFC 3339 определя формат за времеви отметки, подходящ за интернет протоколи, включително цифрови отмествания на часовата зона. Ако източникът предоставя само местно време без известно отместване, запазете тази несигурност, вместо мълчаливо да го третирате като UTC. Никога не внушавайте точност до секунди, когато източникът предоставя само дата.
7. Местоположения на събитията и география на пратката
Потърсете структурирани компоненти на местоположението като град, регион, държава и пощенски код, когато са предоставени. Запазете и необработен низ за местоположението, ако преобразуването му в структурирани полета може да доведе до загуба на смисъл.
Местоположението на сканиране не е непременно текущото местоположение на пакета. По същия начин последният отчетен логистичен обект не доказва, че пратката все още се намира там. Страниците за клиенти трябва да го описват като последното отчетено местоположение. Избягвайте извеждането на координати или точен адрес за доставка от непълен текст на сканиране.
8. Прогнозна дата или интервал за доставка
Полето за прогнозна доставка трябва да показва дали съдържа конкретна дата или интервал, кой го е изчислил и кога е актуализирано за последен път. Прогноза, предоставена от превозвача, и отделно изчислена прогноза трябва да останат различими.
Не превръщайте прогноза, съдържаща само дата, в точно време на пристигане. Интеграцията ви трябва да обработва и променени или оттеглени прогнози, без да запазва остаряло обещание на страницата за проследяване. Ако няма прогноза, покажете, че тя не е налична, вместо да я изчислявате въз основа на неподкрепено предположение.
9. Причина за изключението и необходимо действие
Информацията за изключението трябва да обяснява проблема и, когато източникът го поддържа, да посочва действие, отговорна страна или краен срок. Общото известие за закъснение е оперативно различно от искането за информация от получателя.
Съхранявайте отчетените факти отделно от решенията в собствения ви работен процес. Например бизнесът ви може да създаде задача за поддръжка след определен период без актуализация. Това е вътрешно правило за ескалация, а не доказателство, че превозвачът е обявил пратката за изгубена. Не генерирайте инструкции за плащане или искания за чувствителна информация от нееднозначен текст за проследяване.
10. Предаване между превозвачи и свързани номера за проследяване
Когато пратката преминава между оператори, полезните данни включват следващия превозвач, свързан номер за проследяване и връзката между оригиналния и последващия запис. Това може да помогне за запазване на непрекъснатостта, когато етапът на доставката използва различен идентификатор.
Третирайте отчетеното предаване като връзка, вместо да заменяте оригиналния превозвач. Не обединявайте записи само защото дестинациите или номерата им за проследяване изглеждат сходни. Ако връзката не е предоставена или потвърдена по друг начин, оставете я нерешена, вместо да измисляте непрекъснат маршрут.
11. Резултат от доставката и референции за доказателство
Когато е отчетена доставка, отговорът трябва да предоставя записаното време на доставката и всички налични подробности, например описание на безопасно място или категория на получателя. Референция към доказателство за доставка също може да бъде полезна, когато превозвачът и услугата я предоставят.
Статусът „Доставено“ не трябва да се приема като доказателство, че самият предвиден получател е приел пратката. Подписите, снимките, имената и точните местоположения могат да съдържат лична информация. Ограничете достъпа, избягвайте показването на тези подробности на публични страници за проследяване и потвърдете всички изисквания за упълномощаване или изтичане на връзките към доказателства.
12. Актуалност, състояние на извличането и метаданни на отговора
Искайте достатъчно метаданни, за да различавате последното събитие за пратката от последното успешно извличане на данни. Полезните стойности включват последната успешна проверка, последния неуспешен опит, времето на генериране на отговора и дали върнатите данни са кеширани или частични.
Успешната заявка към API сама по себе си не доказва, че превозвачът е публикувал ново сканиране. Семантиката на HTTP отговора описва резултата от заявката; движението на пратката принадлежи към данните на приложението. Съхранявайте грешките при извличане отделно от изключенията на пратката, така че временен проблем със свързването да не се превърне във фалшиво известие за доставка.
Липсващите данни трябва да имат определено значение
Наличието на поле е само част от договора. Екипът ви трябва също да разбира какво означава липсваща стойност. Прогнозата за доставка може да не е налична от източника, все още да не е извлечена или да не е приложима след доставката. Тези ситуации не трябва автоматично да водят до едно и също клиентско съобщение.
- Неизвестно: Стойността не е установена.
- Непредоставено: Източникът не е предоставил стойността в извлечените данни.
- Неприложимо: Полето не се отнася за този запис или състояние.
- Неуспешно извличане: Системата не е успяла да завърши съответната справка.
Това са препоръчителни разграничения, а не задължителни буквални стойности. Каквото и представяне да изберете, документирайте го. Избягвайте фиктивни дати, празни обекти, които изглеждат като валидни записи, и координати по подразбиране, които могат да бъдат сбъркани с реални местоположения.
Как да тествате отговора преди интеграция
Оценете реални полезни товари от превозвачите, услугите и маршрутите за доставка, които бизнесът ви използва. Схемата може да изброява незадължително поле, без да гарантира, че всеки основен източник го попълва. За интеграция с 17TRACK използвайте официалната документация на Tracking API, за да проверите договора за отговор, вместо да приемате концептуалните имена на полетата в това ръководство като готови параметри.
- Създайте представителна извадка. Включете наскоро регистрирани пратки, активни пратки, опити за доставка, завършени доставки и налични случаи на предаване.
- Свържете полетата обратно към събитията. Потвърдете, че показваният статус, последното събитие и подробностите за доставката описват съгласуван запис. Проучвайте несъответствията, вместо да ги скривате.
- Тествайте забавени и повтарящи се актуализации. Обработете повторно същия полезен товар и получете по-старо събитие след по-ново. Потвърдете, че нито един от случаите не създава дублирани известия или неправилно връща показваното състояние назад.
- Тествайте липсващи и неправилно форматирани стойности. Включете липсващи прогнози, неизвестни местоположения, непознати кодове на статуса и непълни времеви отметки. Приложението трябва да остане използваемо, без да измисля заместители.
- Разделяйте транспортните грешки от резултатите от проследяването. Грешка при удостоверяване, изтичане на времето или неправилно форматиран отговор трябва да попадне в пътя за интеграционни грешки, а не в работен процес за изключение на пратка.
- Проверете клиентския изглед. Уверете се, че вътрешни референции, необработени диагностични подробности и лична информация не изтичат в публични страници или известия.
При актуализации, базирани на webhook, проверете също идентификаторите на доставката, удостоверяването, поведението при повторен опит и обработката на повторно възпроизвеждане в документацията на доставчика. Това са изисквания за интеграцията, а не факти за пратката. Получателят ви трябва безопасно да обработва повтарящи се доставки и не трябва да приема, че редът на пристигане е равен на реда на събитията.
Критерият за приемане трябва да е практичен: може ли приложението ви да обясни пратката, без да прави неподкрепени твърдения, и може ли оперативният екип да определи следващото оправдано действие? По-малък, добре дефиниран полезен товар може да бъде по-полезен от по-голям отговор, пълен с необяснени незадължителни стойности.
Често задавани въпроси
Трябва ли всяка пратка да има попълнени и 12-те групи данни?
Не. Доказателства за доставка, последващи номера за проследяване и прогнозни дати за доставка може да не са налични или да не са приложими. Изисквайте ясни дефиниции на полетата и предвидимо поведение при липсващи стойности, вместо универсално попълване. Проверете най-важните полета спрямо реалния ви набор от пратки.
Трябва ли да съхраняваме необработения отговор или само нормализираните полета?
Съхранявайте нормализираните полета за логиката на приложението. Запазването на релевантни полезни товари от източника може също да помогне при отстраняване на грешки и промени в съпоставянето, при спазване на изискванията ви за поверителност, сигурност, договори и съхранение. Ограничете достъпа и не запазвайте чувствително съдържание само защото се появява в отговор.
Коя времева отметка трябва да определя последното събитие?
Използвайте документираната хронология на събитията и правилата за подреждане на доставчика, като отчитате часовите зони и корекциите. Времето на получаване показва кога системата ви е научила за събитието, а не непременно кога то е настъпило. Ако времевите отметки са непълни или противоречиви, запазете нееднозначността, вместо да твърдите, че последователността е точна.
Може ли API за проследяване да потвърди, че пакетът е изгубен?
Третирайте пратката като изгубена, съобщена от превозвача, само когато източникът изрично поддържа това тълкуване. Дълъг период без сканирания може да оправдае разследване съгласно оперативните ви правила, но самото мълчание не доказва загуба. Поддържайте „неактуално проследяване“ и „съобщено като изгубено“ като отделни понятия.
Достатъчен ли е статусът „Доставено“, за да приключим оплакване на клиент?
Не автоматично. Той установява отчетения резултат от проследяването, но може да не разреши спора на получателя. Прегледайте наличните подробности за доставката, клиентския профил и процеса ви за поддръжка. Не третирайте етикета на статуса като заместител на проучването на противоречива информация.
Източници
- Документация на 17TRACK Tracking API — специфичната за продукта справка за проверка на документираните полета и поведението на интеграцията; 12-те групи по-горе са редакционни препоръки, а не възпроизвеждане на неговата схема.
- RFC 3339: Дата и час в интернет: времеви отметки — представяне на времеви отметки и конвенции за отместване на часовата зона.
- RFC 9110: HTTP семантика — семантика на HTTP отговорите, различна от бизнес статуса на ниво пратка.


