Как да интегрирате API за проследяване на пратки във вашия магазин за електронна търговия
За да интегрирате API за проследяване на пратки във вашия онлайн магазин, свържете системата си за поръчки с доставчика на проследяване, изпращайте данните за пратката и превозвача чрез защитена заявка от страна на сървъра, съхранявайте нормализирани събития за проследяване и показвайте получения статус в интерфейсите за клиенти и поддръжка. Надеждната реализация е нещо повече от добавяне на поле за номер за проследяване: тя трябва да обработва избора на превозвач, актуализациите на статуса, изключенията при доставката, повторните опити, поверителността и начина, по който клиентите действително използват информацията след покупката.
Това ръководство обяснява практически подход за интеграция за собственици на магазини, разработчици и оперативни екипи. То използва официалната документация на 17TRACK за Tracking API като отправна точка, но същите принципи за планиране се прилагат и при оценяването на друг доставчик с поддръжка на множество превозвачи.
Определете какво трябва да постигне интеграцията
Започнете от бизнес резултата, а не от API крайната точка. Повечето магазини искат да намалят запитванията „Къде е поръчката ми?“, да предоставят на купувачите ясна информация за доставката и да помогнат на оперативните екипи да идентифицират забавените пратки, преди клиентът да се оплаче. Тези цели изискват различни данни и работни процеси.
- Видимост за клиента: показвайте текущия статус на пратката, информация за очакваната доставка, когато е налична, данни за превозвача и последното значимо събитие.
- Оперативна видимост: позволете на служителите да намират забавени, блокирани, върнати или проблемни пратки при различни превозвачи.
- Автоматизирана комуникация: задействайте одобрени имейл, SMS или други известия, когато пратката достигне определено състояние.
- Съгласуваност на данните: преобразувайте различните обозначения на събитията от превозвачите в по-малък набор от статуси, които магазинът ви може да използва надеждно.
Определете тези резултати, преди да изберете метод за реализация. API за проследяване може да предоставя данни за пратките, но не решава автоматично кои събития заслужават известие до клиента или как магазинът ви трябва да обработи проблем с адреса.
Изберете подходяща архитектура за интеграция
Типичната архитектура има четири слоя: платформа за електронна търговия, интеграционна услуга, доставчик на проследяване и интерфейс за клиента. Интеграционната услуга може да бъде бекенд приложение, система за управление на поръчки или безсървърен работен процес. Обикновено е по-безопасно тази логика да се поддържа на сървъра, вместо API идентификационните данни да се поставят в кода на браузъра.
Основният поток изглежда така:
- Платената поръчка се изпълнява и получава номер за проследяване и превозвач.
- Вашият бекенд изпраща данните за пратката до доставчика на проследяване.
- Доставчикът връща идентификатор за проследяване или данни за проследяването според дизайна на своя API.
- Системата ви съхранява референцията към доставчика и съпоставя събитията на пратката с вътрешни статуси.
- Планиран процес за актуализация или поддържано известие за събитие обновява пратката.
- Вашият магазин, страницата на поръчката, инструментите за поддръжка и услугата за известия четат от вашите собствени нормализирани данни.
Не карайте всяко зареждане на страница да извиква API на превозвача или за проследяване. Такава архитектура може да създаде бавно клиентско изживяване, дублирани заявки, проблеми с ограниченията на честотата и несъгласувани резултати. Съхранявайте последното прието състояние на проследяването в базата си данни и го обновявайте чрез контролирани фонови задачи или поддържания от доставчика механизъм за актуализация.
Потвърдете документацията на доставчика, преди да започнете програмирането
Преди реализацията прегледайте официалната API документация на доставчика относно удостоверяването, форматите на заявките, полетата в отговорите, поддържаните превозвачи, поведението при грешки, механизмите за актуализация и изискванията към акаунта. 17TRACK предоставя специална продуктова страница на Tracking API и документация за разработчици. Приемайте тези страници като авторитетен източник за текущото поведение на API, вместо да разчитате на примери, копирани от форуми или стари ръководства за интеграция.
Създайте кратък списък с изисквания въз основа на документацията:
- Как се издават, съхраняват, подменят и оттеглят API идентификационните данни?
- Изисква ли заявката код на превозвача или услугата може да го определи по номера за проследяване?
- Кои полета в отговора идентифицират пратката, статуса, местоположението, времевите маркери и съобщението за изключение?
- Как се доставят асинхронните актуализации, ако акаунтът ги поддържа?
- Какви са документираните ограничения на заявките, правилата за таксуване, очакванията за изчакване и кодовете за грешки?
- Как трябва да се обработват дублирани номера за проследяване, невалидни номера, неизвестни превозвачи и доставени пратки?
Не правете извод за дадена функция само от името на продукта. Например „в реално време“ може да описва позиционирането на продукта, а не гаранция, че всяко събитие от превозвача ще се появи незабавно. Реализацията ви трябва да обяснява, че сканиранията от превозвача могат да се забавят и че API не може да създаде сканиране, което превозвачът не е отчел.
Подгответе данните за поръчките и пратките
Най-подходящият момент за създаване на проследяване обикновено е изпълнението на пратката, а не създаването на поръчката. Поръчката може да е платена, но все още да не е опакована, а номерът за проследяване може да бъде генериран, преди пратката да бъде приета от превозвача. Определете кое събитие в работния процес по изпълнение трябва да създава записа за проследяване.
Най-малкото вътрешният запис за пратката трябва да различава следните стойности:
- Вътрешен идентификатор на поръчката и идентификатор на изпълнението
- Номер за проследяване
- Име или код на превозвача
- Държава или регион на местоназначението, когато е необходимо от оперативна гледна точка
- Идентификатор за проследяване при доставчика или референция за абонамент, ако е върнат
- Текущ нормализиран статус
- Времеви маркер на последното събитие и на последната синхронизация
- Необработен отговор от доставчика или контролиран одитен запис
Съхранявайте отделно данните за поръчката и пратката. Една поръчка може да съдържа няколко пакета, разделени пратки или различни превозвачи. Предположението за съответствие „една поръчка — един номер за проследяване“ често се проваля, когато складът изпраща артикулите поотделно.
Използвайте идемпотентен процес. Ако системата за изпълнение повтори същата заявка, интеграцията трябва да обнови съществуващата пратка, вместо да създаде дублирани абонаменти или дублирани съобщения до клиента. Практически идемпотентен ключ може да комбинира вътрешния идентификатор на изпълнението, идентификатора на превозвача и номера за проследяване, в зависимост от собствените изисквания на доставчика.
Нормализирайте статусите на превозвачите за клиентите
Превозвачите използват различни обозначения и последователности от събития. Вашият магазин трябва да поддържа малък вътрешен модел на статусите, например Информацията е получена, В транзит, Извънредена за доставка, Доставена, Изключение и Върната. Запазете оригиналното събитие на превозвача за служителите по поддръжката, но използвайте нормализирания статус за логиката на магазина.
Правилата за нормализация трябва да бъдат изрични. Събитие „етикетът е създаден“ не трябва да се представя като доказателство, че пратката се движи. „Доставена“ трябва да се разглежда като събитие, съобщено от превозвача, а не като гаранция, че клиентът физически е намерил пратката. Изключение не трябва мълчаливо да се преобразува в „в транзит“ само защото пратката може да продължи по-късно.
Определете също приоритета на статусите и обработката на връщането към предишен статус. Забавен поток от данни от превозвача може да пристигне в неправилен ред. Сравнявайте времевите маркери на събитията, когато са налични, записвайте необработеното събитие и не заменяйте по-ново състояние „доставена“ с по-старо състояние „в транзит“. Ако времевите маркери липсват или са нееднозначни, маркирайте записа за консервативна актуализация, вместо да измисляте последователност.
Изградете потока на заявките от страна на сървъра
Вашият бекенд трябва да валидира входящите данни за изпълнение, преди да извика доставчика на проследяване. Проверете дали номерът за проследяване е наличен, премахнете случайните интервали, валидирайте очаквания формат, когато е подходящо, и потвърдете, че стойността на превозвача е приемлива. Не отхвърляйте необичайни, но валидни номера за проследяване само защото не съответстват на тесен локален шаблон.
Неутрален спрямо доставчика поток на заявките може да бъде представен така:
получаване на събитие за изпълнение
валидиране на полетата на поръчката и пратката
проверка за съществуващ идемпотентен ключ
изпращане на документираната заявка за проследяване от сървъра
съхраняване на отговора от доставчика и вътрешния запис за пратката
поставяне на опресняване на опашка или обработване на поддържаното събитие за актуализация
публикуване само на одобрени полета в магазинаИзползвайте кратки периоди на изчакване, ограничен брой повторни опити и експоненциално отстъпване при временни повреди. Не повтаряйте всяка грешка. Грешка при удостоверяване, невалидна заявка или неподдържан превозвач обикновено изискват корекция, а не многократни извиквания. Записвайте идентификатор за корелация, резултата от заявката и категорията на грешката от доставчика, но избягвайте да записвате API ключове, пълни адреси на клиенти или ненужна лична информация в логовете на приложението.
Съхранявайте отговора на доставчика отделно от модела, предназначен за клиента. Така ще бъде по-лесно да смените доставчика, да коригирате правило за съпоставяне и да ограничите информацията, изложена чрез публична страница на поръчката.
Проектирайте изживяването за проследяване на клиента
Страницата за проследяване трябва бързо да отговаря на три въпроса: какво е текущото състояние, какво се е случило последно и какво трябва да направи клиентът след това? Показвайте референцията на поръчката, номера на пратката във форма, съобразена с поверителността, името на превозвача, часа на последното събитие и ясно обяснение на изключенията.
Не показвайте празна времева линия така, сякаш става дума за техническа повреда. Преди първото сканиране от превозвача обяснете, че информацията за доставката е получена и че движението все още може да не е видимо. При изключение предоставяйте обяснение на разбираем език само когато изходните данни го подкрепят. Ако превозвачът съобщи за проблем с адреса, поставете връзка към процеса за поддръжка или действие от страна на обслужването на клиенти, което бизнесът ви действително може да предостави.
За магазини, изградени върху Shopify или друга платформа за електронна търговия, проверете как платформата предоставя събитията за изпълнение, клиентските акаунти, страниците със статус на поръчките и шаблоните за известия. Официалната документация за разработчици на Shopify включва ресурси за webhooks и данни за изпълнение. API на платформата и документацията с версии могат да се променят, затова потвърдете версията, използвана от приложението ви, преди работа в продукционна среда.
Използвайте известията внимателно
Събитията за пратките са полезни задействания, но изпращането на съобщение за всяко сканиране от превозвача може да доведе до умора от известия. Определете бизнес правила, например известяване при създаване на пратка, значим напредък в транзита, предстояща доставка, доставка и избрани изключения. Потискайте дублираните съобщения и добавете минимален интервал за повтарящи се съобщения за забавяне.
Разделяйте оперативните сигнали от известията до клиентите. Екипът за поддръжка може да трябва да знае, че пратката не се е променяла от няколко дни, докато клиентът може да има нужда от съобщение само когато превозвачът съобщи за конкретно изключение. Прагът за време трябва да отразява нивото на услугата, местоназначението, превозвача и метода на доставка, а не универсално число без оперативна обосновка.
Тествайте с реални сценарии за доставка
Успешният отговор за един номер за проследяване не е достатъчен за продукционно стартиране. Създайте тестова матрица, включваща множество превозвачи, държави, типове пратки и състояния на събитията. Тествайте най-малко:
- Ново създадена пратка без сканиране от превозвача
- Пратка, която нормално е в транзит
- Пратка, излязла за доставка
- Доставена пратка
- Изключение или събитие, свързано с адреса
- Върната пратка
- Невалиден номер за проследяване
- Дублирано събитие за изпълнение
- Забавен отговор или изтичане на времето за изчакване на доставчика
- Събитие, пристигнало в неправилен ред
Измервайте повече от наличността на API. Проверявайте дали е обновена правилната поръчка, дали клиентът вижда разбираем език, дали дублираните известия са потиснати и дали служителите по поддръжката могат да идентифицират оригиналното събитие от превозвача. Първоначално направете ограничено внедряване, запазете оперативна резервна процедура и наблюдавайте категориите грешки след пускането.
Сигурност, поверителност и поддръжка
Съхранявайте идентификационните данни в мениджър на тайни или защитена променлива на средата, а не в кода на темата, мобилния код, системата за контрол на версиите или заявките от браузъра. Ограничете достъпа до данните за пратките според ролите, използвайте HTTPS и преглеждайте колко дълго се съхраняват необработените отговори и полетата, свързани с клиентите.
Редовно преглеждайте документацията на доставчика и версията на API на платформата за електронна търговия. Поддръжката на превозвачи, имената на събитията, изискванията за удостоверяване и поведението на webhook-овете на платформата могат да се променят. Поддържайте правилата за съпоставяне на статуси конфигурируеми, документирайте предположенията зад тях и осигурете възможност за повторно обработване или съгласуване на пратка, без да изпращате ново съобщение до клиента.
API на 17TRACK е подходяща опция за оценяване, когато магазинът ви се нуждае от специализирана интеграция за проследяване при различни превозвачи. Подходящият избор все пак зависи от използваните превозвачи, държавите, в които работите, поведението на актуализациите, документирано за вашия акаунт, очаквания обем заявки и оперативните контроли, от които екипът ви се нуждае. Потвърдете тези точки в официалната документация и чрез контролиран proof of concept, преди да се ангажирате с продукционен дизайн.
Често задавани въпроси
Трябва ли проследяването да се създава, когато е направена поръчка?
Обикновено не. Създайте или активирайте записа за пратката, когато работният ви процес по изпълнение разполага с превозвач и номер за проследяване. Създаването му при плащане може да доведе до записи за поръчки, които по-късно са анулирани, неизпълнени или разделени.
Може ли API за проследяване да гарантира информация за доставката в реално време?
Не. Никое API не може да гарантира, че всяко сканиране от превозвача ще бъде видимо незабавно. Доставчикът зависи от данните на превозвача, а системите на превозвачите могат да съобщават събития със закъснения или пропуски. Представяйте времевите маркери и езика на статусите точно и не обещавайте конкретно време за обновяване, освен ако съответната документация и споразумението за услугата не подкрепят такова обещание.
Трябва ли браузърът да извиква API за проследяване директно?
В повечето реализации — не. Използвайте интеграция от страна на сървъра, така че идентификационните данни да останат защитени, отговорите да могат да бъдат нормализирани, повторните опити да се контролират и данните, показвани на клиентите, да се филтрират. Обикновено магазинът трябва да чете одобрен изглед на пратката от вашето приложение.
Как магазинът трябва да обработва множество пакети в една поръчка?
Моделирайте всяко изпълнение или пакет като отделна пратка, като запазите идентификатора на родителската поръчка. Страницата на поръчката може да показва общо обобщение и отделни времеви линии за всеки пакет. Така забавеният пакет няма да бъде скрит зад статус „доставена“ за друг пакет.
Коя е първата продукционна метрика, която трябва да наблюдаваме?
Наблюдавайте целия поток — от създаването на изпълнението до правилната актуализация, видима за клиента. Самият успех на API не е достатъчен. Проследявайте дублираните записи, остарелите пратки, несъпоставените събития, неуспешните известия и процента пратки, които изискват ръчна корекция.
