Работен процес на API за проследяване на пратки: от регистриране на пратка до извличане на данните за проследяване
Работният процес на API за проследяване на пратки започва с подаване на номер за проследяване и необходимата информация за превозвача, проверка дали регистрацията е успешна, изчакване на наличността на данните за проследяване и извличане на статуса и историята на събитията на пратката. При производствена интеграция разработчиците трябва също да свържат всеки запис за проследяване с поръчка, да обработват частични грешки, да обработват безопасно актуализациите и да разграничават приета регистрация от реално сканиране от превозвача.
Това ръководство обяснява този работен процес за разработчици, които свързват платформа за електронна търговия, система за управление на поръчки, складово приложение или инструмент за обслужване на клиенти. То отделя препоръките за проектиране на приложения от специфичните за доставчика изисквания към API. При интеграция с 17TRACK използвайте официалната API документация, за да потвърдите схемата на заявките, удостоверяването, поддържаните операции и полетата в отговорите, преди да реализирате примерите по-долу.
Разберете какво прави регистрацията — и какво не прави
Регистрирането на пратка в услуга за проследяване означава подаване на идентификатор, така че услугата да може да проследява или управлява тази пратка съгласно своя API договор. Това не е същата операция като закупуване на пощенска услуга, генериране на товарителница, резервиране на вземане или предаване на пратка на превозвач.
Разграничете три резултата в приложението си:
- Заявката е получена: API върна отговор на вашата HTTP заявка.
- Регистрацията е приета: Услугата е приела отделния запис за проследяване за обработка.
- Информацията за проследяване е налична: Услугата разполага с информация за пратката, която приложението ви може да извлече или получи.
Тези резултати не трябва да се обединяват в един флаг „успешно“. Приетият номер за проследяване може все още да няма събития от превозвача. По същия начин успешният HTTP отговор на пакетна заявка не доказва, че всеки елемент от пакета е приет; проверете структурата на резултата на ниво приложение, определена от доставчика.
1. Подгответе идентичността на пратката и конфигурацията на API
Преди да изпратите заявка за регистрация, решете как пратката ще бъде идентифицирана във вашата система. Само идентификаторът на поръчката обикновено не е достатъчен, тъй като една поръчка може да бъде разделена на няколко пакета. Създайте отделен вътрешен запис за всяка пратка или пакет и свържете този запис със съответната поръчка.
Полезният вътрешен запис включва следната информация. Това са предложени полета на приложението, а не схема на заявка към 17TRACK.
- Вътрешен идентификатор на пратката: Вашият постоянен идентификатор на пакета.
- Референция на поръчката: Поръчката или записът за изпълнение, към който принадлежи.
- Номер за проследяване: Идентификаторът, издаден от превозвача, съхраняван като текст за запазване на водещите нули.
- Информация за превозвача: Идентичността на превозвача, предоставена от системата ви за изпълнение, ако е известна.
- Референция на доставчика: Всеки идентификатор, върнат от услугата за проследяване и необходим за последващи операции.
- Състояние на регистрацията: Вашият запис дали подаването е изчакващо, прието, отхвърлено или очакващо съгласуване.
- Състояние на проследяването: Последният статус на пратката, поддържан отделно от състоянието на регистрацията.
Проверявайте входните данни преди подаване. Премахвайте случайните интервали в началото и края, но не променяйте номера за проследяване въз основа на предположения за формата на превозвача. Запазвайте оригиналната стойност за отстраняване на проблеми. Ако превозвачът е известен, преобразувайте го към документирания идентификатор на превозвача от доставчика, вместо да изпращате неофициално име за показване.
Конфигурирайте удостоверяването от страна на сървъра. Съхранявайте идентификационните данни извън контрола на версиите, отделяйте конфигурациите за разработка и производство и маскирайте секретите в журналите. Потвърдете документираната версия на API, ограниченията на заявките, ограниченията за пакетите и изискванията към акаунта, вместо да използвате стойности от несвързана интеграция.
2. Регистрирайте пратката и запишете резултата за всеки елемент
Изпратете записа за проследяване чрез операцията за регистрация, описана в документацията на вашия доставчик. Включвайте само задължителните полета и допълнителната информация, която има ясно определена цел. Избягвайте да изпращате имена, адреси или други лични данни на клиенти само защото са налични във вашата база данни за поръчки.
Следният псевдокод илюстрира последователността в приложението. Имената на функциите са примерни; те не са крайни точки на API или методи на SDK.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Запазвайте достатъчно информация, за да обясните какво се е случило: вътрешния идентификатор на пратката, часа на подаване, номера на опита, резултата на ниво елемент и всяка референция към заявката от доставчика. Не разчитайте само на временен журнал от работния процес. Екипите за обслужване на клиенти и операции се нуждаят от устойчив отговор дали пратката е била успешно регистрирана.
Обработвайте пакетните подавания поотделно
Ако API поддържа пакетна регистрация, свържете всеки върнат елемент с оригиналната му пратка. Не маркирайте целия пакет като приет само защото HTTP заявката е приключила успешно. Запазете приетите елементи, изолирайте отхвърлените и проучете отделно неясните резултати.
Това предотвратява ситуацията, при която един неправилно форматиран номер за проследяване налага ненужни повторни опити за вече успешно обработени записи. Освен това предоставя на оперативния персонал списък с конкретни записи, които изискват корекция.
Третирайте изчакванията като неизвестен резултат
Изтичането на времето не доказва, че регистрацията е неуспешна. Доставчикът може да е приел заявката, преди връзката ви да бъде прекъсната. Използвайте документираното поведение за идемпотентност, обработката на дубликати или операциите за търсене, за да съгласувате резултата, преди да изпратите заявката отново на сляпо.
Когато поведението на доставчика при дубликати не е ясно, тествайте го с контролирани записи и потвърдете договора, преди да активирате автоматични повторни опити. Вътрешното премахване на дубликати от задачите за регистрация все още е полезно, но не заменя разбирането как отдалечената услуга обработва повтарящи се заявки.
3. Предвидете пристигането на първата информация за проследяване
След като регистрацията бъде приета, подробностите за проследяване може да не са налични веднага. Етикетът може да съществува, преди превозвачът да е записал физическо събитие по обработката. Липсващата информация може също да изисква проверка на номера за проследяване, избора на превозвач или специфичните изисквания за търсене на пратката.
Представяйте това състояние изрично. „Регистрирана; очаква информация за проследяване“ е по-точно от „В транзит“ или „Регистрацията е неуспешна“. Не измисляйте оценка за доставка или събитие за движение, за да запълните празен интерфейс.
Когато записът остане празен, проучвайте в следния практичен ред:
- Потвърдете, че отделната регистрация е била приета.
- Сравнете подадения номер за проследяване със записа за изпълнение.
- Проверете съпоставянето на превозвача и всички документирани допълнителни изисквания за търсене.
- Проверете собствената страница за проследяване на превозвача за същата пратка.
- Ако превозвачът има събития, но интеграцията ви няма, проверете отговорите при извличане и се свържете с доставчика на API с редактирана диагностична информация.
Избягвайте универсален период на изчакване без доказателства. Правилата за ескалация трябва да отразяват услугата за доставка, очаквания процес на предаване и собствените ви оперативни ангажименти.
4. Извличайте подробности за проследяване и ги интерпретирайте правилно
След като записът стане наличен, извикайте документираната операция за подробности за проследяване, като използвате необходимите идентификатори. Не приемайте, че регистрацията и извличането приемат идентични полета. Някои API договори разграничават номерата за проследяване, идентификаторите на превозвача и генерираните от доставчика референции към записите.
Приложението ви трябва да разграничава три слоя информация:
- Обобщение на пратката: Общото състояние, използвано в табла, страници на поръчки и оперативни филтри.
- История на събитията: Отделните наблюдения, включително описания на събитията, времеви отметки и местоположения, когато са предоставени.
- Метаданни за извличането: Кога приложението ви е получило или извлякло информацията и дали заявката е завършила успешно.
Успешното търсене означава, че операцията по извличане е завършила успешно. То не означава, че пакетът се е придвижил след предишното търсене. Сравнете върнатата информация за проследяване със съхранения запис, преди да генерирате известие или последващ работен процес.
Дръжте времето на събитието отделно от времето на извличане
Съхранявайте времето, свързано със събитие от превозвача, отделно от времето, когато системата ви го е получила. Събитие, извлечено този следобед, може да описва по-ранно сканиране. Замяната на времето на събитието с времето на извличане би накарала стара актуализация да изглежда като ново физическо движение.
Запазвайте оригиналната времева отметка и предоставеното отместване. Нормализирайте времевите отметки за сравнение само когато часовата зона е известна. Ако събитието няма информация за часова зона, запазете тази несигурност, вместо мълчаливо да задавате часовата зона на сървъра.
Запазвайте първоначалното значение заедно с нормализирания статус
Нормализираният статус е полезен за групиране на пратки между различни превозвачи, но оригиналното описание на събитието може да обясни по-точно оперативен проблем. Когато е налично, запазвайте и двете. Само обща категория за изключение може да не каже на служителя по поддръжката дали следващото действие е проверка на адрес, свързване с получателя или изчакване на друга актуализация.
Не извеждайте гаранция за доставка, потвърдена загуба или конкретен митнически резултат от неясен статус. Ескалирайте според основната информация и оперативната си политика.
5. Поддържайте записите актуални чрез периодично извличане или уебкуки
Еднократното извличане на подробности е достатъчно за тестване на свързаността, но не и за поддържане на видимост върху пратките. Производственият ви дизайн се нуждае от механизъм за актуализации. Потвърдете механизмите, поддържани от избрания доставчик, и условията, свързани с тях.
При периодично извличане приложението ви заявява подробности за проследяване по график. Планирайте заявките в рамките на документираните ограничения, избягвайте многократно запитване на непроменени записи без причина и използвайте отстъпващи интервали при грешки, подлежащи на повторение. Отварянето на страница на поръчка от клиент не трябва автоматично да задейства неограничена заявка към външната услуга; съхранен изглед на проследяването може да обслужи страницата, докато контролираният фонов процес го обновява.
Ако използвате уебкуки, валидирайте входящите заявки чрез документирания механизъм за проверка на доставчика. Запазете приетите съобщения или ги поставете в устойчива опашка, преди да ги потвърдите съгласно договора за уебкуки, след което обработвайте събитията асинхронно.
Изградете приемника така, че да понася дубликати и неочакван ред на пристигане, освен ако документираният договор за доставка не гарантира обратното. Когато е наличен, използвайте идентификатор на събитието от доставчика за премахване на дубликати. В противен случай дефинирайте и тествайте отпечатък въз основа на подходящи полета на събитието, като имате предвид, че може да са необходими корекции за вашите данни.
Интеграцията, базирана на уебкуки, може да използва и контролирано извличане за съгласуване. Например задача за възстановяване може да провери записите, засегнати от прекъсване на приемника. Това е модел за устойчивост, а не разрешение да се пренебрегват ограниченията на честотата или специфичните указания на доставчика.
6. Превръщайте информацията за проследяване в безопасни бизнес действия
Актуализирайте вътрешния запис на пратката, преди да задействате действия, насочени към клиента. Поддържайте устойчив запис на известията и преходите в работния процес, така че повторно събитие да не генерира повторни съобщения.
Свързвайте бизнес действията със значими промени, а не с всеки отговор от API. Новонаблюдавано събитие за доставка може да оправдае известие за доставена пратка. Повторен отговор със същото събитие не трябва да го прави. Изключение може да оправдае вътрешен преглед, но съобщението към клиента трябва да отразява това, което събитието действително казва.
Определете как обработвате събития, получени след като пратката е била считана за завършена. Не изтривайте историята на събитията и не блокирайте окончателно всички последващи актуализации само защото обобщението е достигнало крайно състояние. Правилата ви за съхранение, съгласуване и известия трябва да отчитат легитимни корекции, без постоянно да отварят отново завършени работни процеси.
Прилагане на работния процес към интеграция с 17TRACK
За персонализирана интеграция за проследяване подходящите начални точки са страницата на 17TRACK Tracking API и нейната документация за разработчици. Използвайте продуктовата страница, за да оцените предложението, а документацията — за да установите действителния договор за интеграция. Страниците за потребителско проследяване не заменят спецификациите на API.
Преди да напишете адаптера, потвърдете формата на удостоверяване, операциите за регистрация и извличане, правилата за идентифициране на превозвача, обработката на отговорите на ниво елемент и приложимите ограничения на заявките. При обработка чрез уебкуки потвърдете също схемата на полезния товар, процеса на проверка, изискванията за потвърждение и поведението при повторни опити.
Дръжте тези специфични за доставчика подробности в адаптер, вместо да разпространявате предположения за полетата на отговорите из цялата система за поръчки. Така останалата част от приложението ви може да работи с вътрешни понятия като резултат от регистрацията, статус на пратката, история на събитията и последна успешна синхронизация.
Проверки преди стартиране, които предотвратяват скъпи грешки
- Приет, но празен запис: Интерфейсът показва, че информацията за проследяване се очаква, а не че пакетът се движи.
- Смесен резултат от пакет: Всяка пратка получава собствен съхранен резултат.
- Изтичане на времето след подаване: Работният процес съгласува несигурния резултат, вместо да приема неуспех.
- Повторено събитие: Хронологията на пратката и известието към клиента остават без дубликати.
- По-старо събитие, получено по-късно: Събитието се запазва, без сляпо да заменя по-новото обобщение.
- Недостъпна външна услуга: Страницата за клиента може да покаже последния съхранен резултат с подходящо указание за актуалността.
- Неправилно съпоставяне на превозвача: Записът може да бъде коригиран чрез документиран път за възстановяване.
- Разделена поръчка: Всеки пакет запазва собственото си състояние на проследяване и история на събитията.
- Изтичане на идентификационни данни или полезен товар: Журналите съдържат диагностични референции, без да разкриват секрети или ненужна лична информация.
Практическият критерий за завършеност не е просто получаването на успешен отговор за регистрация. Той е възможността да проследите пакет от подаването през актуализациите, да обясните празен или неуспешен резултат и да се възстановите от прекъсната обработка, без да губите събития или да дублирате действията към клиентите.
Често задавани въпроси
Създава ли регистрацията на номер за проследяване пратка?
Не и в описания тук работен процес. Регистрацията за проследяване изпраща съществуващ идентификатор към услуга за проследяване. Създаването на етикет, закупуването на пощенска услуга и резервирането на превозвач са отделни операции, освен ако конкретен API изрично не ги комбинира.
Защо подробностите за проследяване са празни след успешна регистрация?
Приемането на регистрацията и наличността на данните за проследяване са различни условия. Превозвачът може все още да не е записал събитие или да е необходимо да се провери номерът за проследяване, съпоставянето на превозвача или допълнителната информация за търсене. Проверете резултата на ниво елемент, преди да приемете, че записът е успешно регистриран.
Трябва ли да регистрирам пратката всеки път, когато извличам статуса ѝ?
Не използвайте повторната регистрация като механизъм за обновяване по подразбиране. Съхранявайте приетото състояние на регистрацията и използвайте документирания механизъм за извличане или актуализация. Следвайте изричните правила на доставчика за корекции, повторно активиране или дублиращи се подавания.
Трябва ли да използвам периодично извличане или уебкуки?
Използвайте механизма, който съответства на документирания договор на API и оперативните ви изисквания. Периодичното извличане изисква контролиран график на заявките. Уебкуките изискват защитен, устойчив приемник и обработка, безопасна спрямо дубликати. Когато се поддържат, актуализациите чрез уебкуки с целево съгласуване могат да осигурят практичен път за възстановяване.
Мога ли да използвам номер за проследяване като единствен идентификатор на пратката в базата си данни?
Вместо това използвайте вътрешен идентификатор на пратката. Съхранявайте номера за проследяване и съответния контекст на превозвача като атрибути на този запис. Така разделените поръчки, коригираните номера за проследяване и специфичните за доставчика референции се управляват по-лесно, без да се променя идентичността на вътрешната ви пратка.
Източници
- 17TRACK Tracking API — официална отправна точка за оценка на интеграция с 17TRACK API.
- 17TRACK API documentation — официална справка за специфичните за реализацията формати на заявките, операциите, отговорите и изискванията за интеграция. Псевдокодът и предложенията за вътрешни полета в това ръководство са примери за проектиране на приложение, а не цитати от този API договор.


