Как да проследявате пратки от Китай до Европа и САЩ с един API

За да проследявате пратки от Китай до Европа и САЩ с един API, свържете системата си за поръчки с услуга за проследяване на пратки от множество превозвачи, регистрирайте всеки пакет с неговия номер за проследяване и всички необходими данни за превозвача и добавяйте актуализациите за проследяване в общ запис на пратката. Интеграцията трябва да отчита международните предавания между превозвачи, забавеното сканиране и отделните номера за проследяване на доставката до крайния получател. Един API може да обедини достъпа до информацията за проследяване, но не може да създава събития, които превозвачът не е подал.

За разработчиците и екипите, управляващи електронната търговия, целта не е просто да се показва статус. Тя е всеки физически пакет да бъде свързан с правилната поръчка, клиентите да бъдат информирани, без да получават подвеждащи актуализации, и да се идентифицират пратките, които изискват намеса. Това ръководство обяснява как да изградите този работен процес и как да оцените услуга като 17TRACK Tracking API спрямо действителните ви маршрути за доставка.

Започнете с маршрута на доставка, а не само с държавата на местоназначение

Пакет, пътуващ от Китай до адрес в Европа или САЩ, може да премине през услуга за събиране, международна транспортна мрежа, митническа обработка и превозвач за доставка в държавата на местоназначение. Някои услуги за доставка показват тези движения под един номер за проследяване. Други предоставят отделен референтен номер за доставката на по-късен етап от пътуването.

Ето защо покритието на ниво държава не е достатъчно за валидиране на интеграция за проследяване. Доставчикът може да разпознава превозвача, без да връща всяко събитие, от което се нуждаете за конкретен продукт за доставка. По същия начин сканирането при изпращане не доказва, че ще са налични сканиранията при доставката в местоназначението.

Преди интеграцията създайте инвентар на маршрутите, като използвате пратки, които бизнесът ви действително изпраща. Запишете логистичния доставчик в началната точка, услугата за доставка, пазара на местоназначение, известния превозвач за доставка и форматите на номерата за проследяване. Тествайте европейските пазари поотделно, вместо да приемате, че успешната доставка в една държава доказва покритие в целия регион.

• За оперативните екипи: идентифицирайте къде пропуските в проследяването създават ръчна работа или контакти с клиенти.
• За инженерните екипи: идентифицирайте кои системи създават пратки и кои системи се нуждаят от актуализации.
• За екипите по снабдяване: проверете поддръжката на конкретните превозвачи и услуги в инвентара на маршрутите.

Какво трябва да прави един API за проследяване — и какво не може да прави

API за проследяване на множество превозвачи предоставя на приложението ви общ интеграционен слой, вместо да изисква отделна връзка с всеки превозвач. В зависимост от услугата и метода на интеграция приложението ви може да извлича актуализации, да получава обратни извиквания или да използва комбинация от двете. Потвърдете поддържаните механизми в документацията на доставчика, преди да проектирате работния процес за продукционна среда.

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

Обединеното проследяване не гарантира непрекъсната физическа видимост, оценка на времето за доставка или пълна митническа история. API връзката може да работи нормално, докато превозвачът няма ново сканиране за отчитане. Проследяването също е отделно от закупуването на етикети за доставка, подготовката на митнически декларации и организирането на услуги за доставка. Не приемайте, че тези функции са включени.

Изградете интеграцията около запис на ниво пакет

1. Разделяйте поръчките, пратките и идентификаторите за проследяване

Една поръчка от електронен магазин може да съдържа няколко пакета и тези пакети могат да пристигнат по различно време. Използвайте вътрешен идентификатор на пакет или пратка като стабилен идентификатор. Свържете поръчката на клиента с този запис, след което добавете към него идентификаторите за проследяване на превозвача.

Практическият вътрешен модел трябва да включва:

• Вътрешен идентификатор на поръчката и пакета.
• Оригиналния номер за проследяване и идентификатора на превозвача, използван от API.
• Всеки потвърден номер за проследяване на превозвача в местоназначението.
• Услугата за доставка и държавата на местоназначение.
• Текущия нормализиран статус и оригиналното описание на превозвача.
• Час на събитието, местоположение на събитието, когато е предоставено, и часа, в който системата ви е получила актуализацията.
• Състояние на регистрацията, последната успешна синхронизация и неразрешените интеграционни грешки.

Това са препоръчителни полета на приложението, а не твърдение, че всеки доставчик ги връща. Поддържайте вътрешната си схема отделно от формата на отговора на доставчика, така че бъдеща промяна в API да не изисква преработване на базата данни за поръчките.

2. Регистрирайте пакетите въз основа на надеждно бизнес събитие

Регистрирайте проследяването, когато на пакета е присвоен валиден номер, а не всеки път, когато някой преглежда страницата на поръчката. Събитие за създадена пратка от склада или системата за поръчки обикновено е по-добър тригер. Ако етикетът бъде анулиран или заменен, актуализирайте връзките между идентификаторите на пакета, вместо да оставяте изоставения номер като единствен референтен номер за проследяване.

Проверете дали номерът е наличен и не е повреден от форматирането на електронна таблица. Запазвайте значимите водещи нули. Когато системата ви за доставка знае превозвача, съхранете тази информация, вместо да разчитате изцяло на автоматично разпознаване: форматите на номерата могат да се припокриват.

Прочетете отговора при регистрация на ниво отделна пратка. Успешната HTTP заявка не означава непременно, че всеки елемент от пакет е приет. Съхранявайте неуспешните заявки в опашка за повторен опит и осигурете на оперативния екип начин да разрешава невалидни или двусмислени подавания.

3. Проектирайте доставката на актуализациите, преди да свържете известията към клиентите

Ако избраната услуга поддържа webhooks, използвайте документирания ѝ механизъм за обратни извиквания, за да получавате актуализации. Проверете наличния метод за удостоверяване или подписване, вместо да измисляте собствен хедър за проверка. Съхранявайте идентификационните данни на сървъра, изисквайте HTTPS и не включвайте API тайни в браузърен код или връзки, предназначени за клиенти.

Получателят ви трябва надеждно да приеме актуализацията, преди да я потвърди, след което да я обработи асинхронно. Проектирайте системата за дублирани доставки и събития, които пристигат в неправилен ред. Използвайте идентификатор на събитието от доставчика, когато е наличен; в противен случай дефинирайте документирано правило за премахване на дубликати чрез стабилни атрибути на събитието.

Ако е необходимо периодично извличане, планирайте го в рамките на документираните ограничения на доставчика и оперативните си нужди. Намалявайте честотата след отговори за ограничение на заявките, избягвайте синхронизирани пикове от повторни опити и прекратявайте ненужните проверки на завършени пратки съгласно политиката си за съхранение и съгласуване. Планирана задача за съгласуване може също да помогне за откриването на пропуснати актуализации, когато услугата позволява извличането им.

4. Нормализирайте статусите, без да губите смисъла

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

Съхранявайте подробното събитие на превозвача заедно с нормализирания статус. Неуспешен опит за доставка, проблем с адреса и забавяне, свързано с митницата, може да изискват внимание, но не изискват една и съща реакция. Преобразуването на всичко в общо изключение би улеснило съхранението на данните, но би намалило полезността им за предприемане на действия.

Не превръщайте създаването на етикет във физическо получаване на пратката. По същия начин не обозначавайте пакет като освободен от митницата само защото дадено събитие споменава митнически обект. Използвайте формулировки, които съответстват на действителното значение на събитието.

Обработвайте международните предавания между превозвачи изрично

Най-важният интеграционен тест често е преходът между мрежата в началната точка и доставката в местоназначението. Запазвайте както оригиналния референтен номер, така и всеки потвърден референтен номер за последната миля. Новият номер за проследяване трябва да стане още един идентификатор за същия пакет, а не автоматично втора пратка.

Свързвайте идентификатори само когато връзката идва от надежден източник, например логистичния доставчик, отговора за проследяване или системата ви за доставка. Подобните часове на събитията или съвпадащите държави на местоназначение не са достатъчни, за да докажат, че два номера принадлежат на един и същ пакет.

Разделяйте часа на събитието от часа на приемане. По-старо събитие може да достигне системата ви след по-ново, особено когато информацията се движи между мрежи. Запазвайте предоставените отмествания на часовите зони, нормализирайте времевите маркери за обработка и съхранявайте неясните стойности от източника, вместо да им задавате неподдържана часова зона.

За клиентите показвайте последния смислен статус с ясно видим час на актуализацията. Ако превозвачът в местоназначението все още не е отчел сканиране, обяснете, че проследяването очаква друга актуализация. Не правете извода, че пакетът е изгубен, все още физически се намира на последното място на сканиране или вече е в държавата на местоназначение.

Къде се вписва 17TRACK в този работен процес

Предложението на 17TRACK за Tracking API е подходящо, когато приложението ви се нуждае от интеграция за проследяване на множество превозвачи. Неговата официална API документация трябва да ръководи реализацията на удостоверяването, регистрацията, обработката на отговорите и поддържаните работни процеси за актуализации. Използвайте документирания API договор, вместо да третирате потребителска страница за проследяване като интеграционен интерфейс.

Оценявайте го със същите оперативни изисквания, които бихте приложили към собствената си реализация: правилно идентифициране на превозвача, полезни събития по маршрутите ви, непрекъснатост при предаването, възстановяване от грешки и управляемо доставяне на актуализациите. Потвърдете търговските условия, отчитането на използването, ограниченията на заявките и необходимата конфигурация на акаунта, преди да се ангажирате с продукционен дизайн.

Най-силната причина да изберете обединен API е намаляването на сложността на интеграцията за маршрутите, по които действително работите. Тази полза все пак трябва да бъде валидирана с представителни пакети. Не избирайте доставчик само защото общото му описание на покритието звучи широко.

Проведете пилотен проект по маршрути преди внедряването

Използвайте тестов набор, който включва нормални доставки и трудни случаи. Историческите пратки помагат за тестване на съпоставянето на статуси, докато текущите пратки разкриват начина на доставяне на актуализациите и оперативното време. Нито един от двата теста сам по себе си не дава отговор на всички въпроси.

• Доставка от Китай до САЩ: проверете събитията в началната точка, всяко международно предаване и крайното събитие за доставка.
• Доставки от Китай до Европа: тествайте държавите на местоназначение и услугите за доставка, които действително използвате.
• Нов етикет: уверете се, че пакет без физическо сканиране не се представя като движещ се.
• Променен референтен номер за доставка: потвърдете, че връзката остава прикрепена към правилния пакет.
• Проблем при доставката: проверете дали подробната причина достига до подходящата оперативна опашка.
• Разделена поръчка: потвърдете, че доставката на един пакет не затваря цялата поръчка.
• Дублирана или забавена актуализация: потвърдете, че тя не генерира повтарящи се съобщения и не заменя неправилно по-нов статус.
• Временна интеграционна повреда: проверете повторните опити, съгласуването и видимостта за екипа по поддръжката.

Задайте критериите за приемане, преди да прегледате резултатите. Измервайте успешните регистрации, неправилно зададените превозвачи, липсващите ключови събития, забавянията при обработката на актуализациите и дублираните съобщения към клиентите. Определете приемливи прагове за своя бизнес, вместо да използвате неподкрепен универсален критерий. Проучете липсващо събитие в собствения запис на превозвача, преди да припишете пропуска на API.

Наблюдавайте свежестта на данните отделно от наличността на API

Мониторингът на API трябва да отговаря на два различни въпроса: функционира ли интеграцията и полезна ли е информацията за пратката? Успешните заявки отговарят само на първия въпрос. Трябва също да знаете дали регистрациите натрупват грешки, обратните извиквания се провалят или даден маршрут е спрял да генерира очакваните ключови събития.

• Здраве на интеграцията: грешки при удостоверяване, грешки на заявките, отговори за ограничение на честотата, неуспешни обратни извиквания и натрупване на задачи в опашките.
• Качество на данните: неизвестни статуси, неправилно форматирани времеви маркери, неразрешени идентичности на превозвачи и неочаквани промени в идентификаторите.
• Свежест на пратките: времето от последното събитие на превозвача, разделено по маршрут и услуга за доставка.
• Въздействие върху бизнеса: натоварване от изключения, неуспешни известия и поръчки, неправилно маркирани като завършени.

Дълъг период без сканиране може да е нормален при една услуга за доставка и необичаен при друга. Използвайте специфични за маршрута очаквания и наблюдаваната история на пратките, за да приоритизирате проучванията. Поддържайте предупреждението за интеграционна грешка отделно от предупреждението за забавена пратка, така че да го получи правилният екип.

Известията към клиентите трябва да следват потвърдени ключови етапи, а не всяко необработено събитие. Потискайте дубликатите, различавайте опит за доставка от завършена доставка и не обещавайте дати на пристигане, които основните данни не подкрепят. Ограничете достъпа до данните за проследяване и съхранявайте лична информация само там, където работният ви процес го изисква.

Често задавани въпроси

Може ли един API да проследява както превозвача в Китай, така и превозвача за доставка в местоназначението?

Услуга за множество превозвачи може да обедини събитията от двете части на пътуването, когато съответните услуги и връзките между идентификаторите се поддържат. Валидирайте целия маршрут с реални пакети. Самото разпознаване на номера за проследяване в началната точка не доказва, че ще бъде налична информация за доставката в местоназначението.

Защо проследяването спира да се актуализира, след като пакетът напусне Китай?

Възможните причини включват празнина между физическите сканирания, забавено отчитане или предаване към друг референтен номер за доставка. Проверете необработените събития и предоставения номер за последната миля, след което сравнете с данните на съответния превозвач. Самата празнина в проследяването не доказва, че пакетът е изгубен или задържан от митницата.

Трябва ли приложението да използва webhooks или периодично извличане?

Използвайте механизмите, описани от вашия доставчик. Когато се поддържат, webhooks могат да намалят повтарящите се проверки, докато разрешените заявки за извличане могат да подпомогнат съгласуването. И при двата подхода изградете обработка на дубликати, контрол на повторните опити и мониторинг, преди да разчитате на актуализациите за комуникация с клиентите.

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

Данните за проследяване не са гаранция за нито едното. Ако е предоставена прогнозна дата на доставка, запазете нейния източник и я представете като прогноза. Митническите сканирания трябва да се описват според действителната им формулировка, а не да се тълкуват като освобождаване, освен ако изрично не посочват такъв резултат.

Какво трябва да се провери, преди да изберете API план?

Потвърдете своите превозвачи и услуги за доставка, изискванията за регистрация, методите за актуализация, отчитането на използването, ограниченията на заявките, наличността на данните и условията за поддръжка. Попитайте как се третират търговски заместващите номера, повторните регистрации и историческите справки. Използвайте актуалната документация и писмено потвърждение за изискванията, които влияят върху бюджета или архитектурата ви.

Източници

• 17TRACK Tracking API — официален продуктов справочник за предложението на tracking API.
• 17TRACK API documentation — официален технически справочник за реализиране на интеграцията. Потвърдете тук точните формати на заявките, поддържаните работни процеси и ограниченията преди разработката.