Skip to main content
НачалоБлогРъководстваКак да използвате API за проследяване на пратки за изпращане на проактивни известия за доставка

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

17TRACK

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

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

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

Проектирайте процеса за известия, преди да свържете API

API за проследяване на пратки предоставя информация за проследяване; вашето приложение решава как да я използва. Разглеждайте видимостта на пратката и комуникацията с клиента като отделни отговорности, дори ако избраната от вас услуга предлага и двете.

Практическата архитектура има шест етапа:

  1. Свързване с поръчката: свържете номера за проследяване и идентификатора на превозвача, когато е необходимо, с вътрешен запис на пратката.
  2. Регистриране на проследяването: изпратете или регистрирайте пратката съгласно изискванията за интеграция на доставчика.
  3. Приемане на актуализации: получавайте обратни извиквания чрез webhook, извличайте актуализации чрез API заявки или комбинирайте двата подхода.
  4. Обработка на събития: валидирайте, нормализирайте, премахвайте дублиранията и оценявайте входящите събития.
  5. Решение за известяване: изберете дали да изпратите известие, с кого да се свържете и кой канал и шаблон да използвате.
  6. Доставка на съобщението: изпратете известието и запишете отговора на услугата за съобщения.

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

1. Потвърдете договора за интеграция

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

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

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

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

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

2. Изградете запис на пратката, който издържа на реални поръчки

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

Полезният вътрешен запис включва:

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

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

При разделени поръчки свързвайте известията със засегнатия пакет. „Един пакет от поръчката ви пристигна“ е по-точно от „Поръчката ви пристигна“, когато друг пакет все още пътува.

3. Свържете събитията за проследяване с решенията на клиента

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

Следните категории са предложени концепции за приложения, а не универсален речник на статусите на API:

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

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

4. Получавайте актуализации, без да губите или дублирате работа

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

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

Опростеният процес на обработка изглежда така. Това са операции на ниво приложение, а не работещ пример със SDK:

получи обратното извикване
  провери заявката чрез документирания механизъм на доставчика
  валидирай полезния товар
  запази приетия полезен товар и атомарно добави обработката в опашката
  върни документираното потвърждение

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

изпрати задачата за известие
  провери предпочитанията на получателя и правилата за потискане
  изпрати съобщението към услугата за съобщения
  запиши резултата и повтори само когато е подходящо

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

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

5. Добавете защита от дублиране и хронологични проверки

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

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

Определете идентичността на известието около бизнес събитието. Потвърждението за доставка може да използва идентификатора на пратката и етапа „доставено“. При опит за доставка може да е необходима идентичност, специфична за опита, тъй като по-късен опит може да бъде действително ново събитие.

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

6. Пишете съобщения, които обясняват какво следва

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

Например:

  • Излязла за доставка: „Вашият пакет по поръчка {order_reference} е излязъл за доставка. Проследете движението му тук: {tracking_link}.“
  • Направен е опит за доставка: „Превозвачът съобщи за опит за доставка на вашия пакет. Проверете страницата за проследяване за наличните следващи стъпки: {tracking_link}.“
  • Доставено: „Превозвачът е отбелязал пакета по поръчка {order_reference} като доставен. Вижте наличните подробности за доставката: {tracking_link}.“

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

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

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

7. Определете какво се случва, когато проследяването замлъкне

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

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

Когато правилото се задейства, проверете за пропусната обработка, съгласувайте с източника на проследяване, когато това се поддържа, и решете дали да откриете вътрешна задача за поддръжка. Ако уведомите клиента, използвайте формулировка, която отразява известното: „Не сме получили нова актуализация за проследяване“ е различно от „Вашият пакет е изгубен.“

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

8. Тествайте целия процес, преди да активирате автоматичното изпращане

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

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

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

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

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

API за проследяване на пратки изпраща ли автоматично имейли или SMS съобщения?

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

Трябва ли да уведомявам клиентите за всяко сканиране при проследяване?

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

Мога ли да гарантирам известия за доставка в реално време?

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

Как мога да предотвратя дублирани съобщения за доставка?

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

Какво трябва да се случи, ако превозвачът коригира статус „доставено“?

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

Източници

Следните официални ресурси са референциите за реализация на интеграцията с 17TRACK, разгледана по-горе. Вътрешната схема, правилата за известия и процесът на обработка в това ръководство са архитектурни препоръки, а не цитирани API договори.

  • 17TRACK Tracking API — официална отправна точка за оценка на интеграцията с API.
  • Документация за 17TRACK API — справочник за специфичните за доставчика формати на заявки, удостоверяване, операции за проследяване и изисквания за интеграция.