Як використовувати API відстеження відправлень для надсилання проактивних сповіщень про доставку
Щоб надсилати проактивні сповіщення про доставку за допомогою API відстеження відправлень, пов’яжіть кожну посилку із замовленням, отримуйте оновлення відстеження, перетворюйте ці оновлення на події, важливі для клієнта, і запускайте повідомлення через службу електронної пошти, SMS або сповіщень у застосунку. Додайте надійну чергу та перевірки дублікатів між вхідними даними відстеження й вихідними повідомленнями, щоб повторні або запізнілі оновлення не створювали заплутаних сповіщень.
Цей посібник призначений для розробників і команд, що займаються операціями в електронній комерції та створюють такий робочий процес. Мета полягає не в пересиланні кожного сканування перевізника, а в тому, щоб повідомляти клієнтам, коли відбувається щось важливе, що саме це означає та чи потрібно їм діяти.
Спроєктуйте робочий процес сповіщень до підключення API
API відстеження відправлень надає інформацію про відстеження, а ваш застосунок вирішує, як її використовувати. Розглядайте видимість відправлення та комунікацію з клієнтами як окремі обов’язки, навіть якщо вибраний вами сервіс пропонує обидві функції.
Практична архітектура складається із шести етапів:
- Пов’язування із замовленням: за потреби пов’яжіть номер відстеження та ідентифікатор перевізника з внутрішнім записом про відправлення.
- Реєстрація відстеження: передайте або зареєструйте відправлення відповідно до вимог інтеграції постачальника.
- Отримання оновлень: отримуйте callback-виклики webhook, одержуйте оновлення через API-запити або поєднуйте обидва підходи.
- Обробка подій: перевіряйте, нормалізуйте, дедуплікуйте та оцінюйте вхідні події.
- Рішення щодо сповіщення: визначайте, чи потрібно надсилати сповіщення, кого контактувати, а також який канал і шаблон використовувати.
- Доставка повідомлення: надсилайте сповіщення та записуйте відповідь служби обміну повідомленнями.
Зберігайте контактну інформацію клієнтів у власній системі замовлень або обміну повідомленнями, якщо інтеграція справді не потребує її передавання. Сервісу відстеження зазвичай не потрібна адреса електронної пошти клієнта лише для того, щоб ваш застосунок пов’язав подію відстеження із замовленням.
1. Підтвердьте умови інтеграції
Перш ніж створювати приймач, перевірте в документації постачальника автентифікацію, реєстрацію відправлень, ідентифікацію перевізника, підтримувані методи оновлення, формати відповідей, обмеження запитів і обробку помилок. Для інтеграцій webhook також перевірте, як автентифікуються callback-виклики, яка відповідь підтверджує отримання та як обробляються невдалі доставки.
Для реалізації на базі 17TRACK почніть зі сторінки API відстеження 17TRACK та його офіційної документації API. Використовуйте задокументовані умови для інтеграції, а не сприймайте ілюстративні назви полів у цьому посібнику як поля запитів або відповідей 17TRACK. Перед реалізацією підтвердьте налаштування callback-викликів, вимоги безпеки та ліміти, що залежать від облікового запису.
Вибирайте метод оновлення відповідно до умов інтеграції:
- Webhooks: використовуйте callback-виклики, якщо вони підтримуються та підходять для вашої інфраструктури. Вони дають змогу застосунку обробляти оновлення, коли постачальник їх надсилає, без повторного запитування того самого відправлення.
- Опитування: отримуйте інформацію про відстеження за розкладом, коли callback-виклики недоступні або непридатні. Дотримуйтеся задокументованих обмежень на запити.
- Комбінований підхід: використовуйте callback-виклики для звичайної обробки та вибіркове отримання даних через API для узгодження відправлень, оновлення яких, схоже, застаріли, якщо постачальник підтримує такий робочий процес.
Не обіцяйте клієнтам миттєві сповіщення лише тому, що використовуєте webhooks. Ваш застосунок не може повідомити про подію перевізника раніше, ніж вихідні дані відстеження стануть доступними.
2. Створіть запис про відправлення, здатний витримати реальні замовлення
Використовуйте внутрішній ідентифікатор відправлення як основне посилання, а не лише номер відстеження. Замовлення може містити кілька посилок, і не слід вважати, що номери відстеження назавжди є глобально унікальними.
Корисний внутрішній запис містить:
- Внутрішній ідентифікатор замовлення та відправлення.
- Номер відстеження та ідентифікатор перевізника, якщо вони відомі.
- Посилання на відправлення, надане постачальником, якщо воно є.
- Поточний нормалізований статус і останню важливу подію.
- Час події перевізника, включно з часовим поясом або зміщенням, якщо вони доступні.
- Час отримання оновлення вашою системою.
- Посилання на налаштування комунікації клієнта.
- Історію сповіщень і будь-який активний процес обробки винятків.
Зберігайте час події окремо від часу отримання. Сканування, яке відбулося раніше, може надійти після новішого сканування. Якщо застосунок сортує події лише за порядком надходження, він може помилково змінити статус доставленого відправлення назад на «у дорозі».
Для розділених замовлень пов’язуйте сповіщення з відповідною посилкою. Повідомлення «Одна посилка з вашого замовлення прибула» точніше за «Ваше замовлення прибуло», якщо інша посилка ще в дорозі.
3. Пов’яжіть події відстеження з рішеннями клієнта
Описи перевізника — це операційні дані, а не готові повідомлення для клієнтів. Створіть рівень нормалізації, який зберігає початкову подію та призначає їй внутрішню категорію, зрозумілу вашим правилам сповіщень.
Наведені нижче категорії є рекомендованими поняттями для застосунку, а не універсальним словником статусів API:
| Внутрішня категорія | Рішення щодо сповіщення | Межа у формулюванні повідомлення |
|---|---|---|
| Інформацію про відправлення отримано | Надсилайте оновлення про підготовку лише за потреби. | Не створюйте враження, що перевізник фізично отримав посилку, лише на підставі створення етикетки. |
| У дорозі | Розгляньте можливість сповіщення про перше важливе переміщення. | Пригнічуйте звичайні сканування на об’єктах, якщо вони не змінюють наступний крок для клієнта. |
| Передано кур’єру для доставки | Сповіщайте, коли підтримувана подія вказує на цей статус. | Не перетворюйте статус на гарантований час прибуття. |
| Спроба доставки або потрібне отримання | Надсилайте сповіщення, яке містить конкретну дію. | Додавайте кінцеві терміни або інструкції щодо отримання лише після перевірки. |
| Виняток під час доставки | Оцініть причину та визначте, чи потрібно клієнту діяти. | Не описуйте кожен виняток як втрачену посилку. |
| Доставлено | Надсилайте підтвердження на рівні посилки. | Не вигадуйте отримувача, місце доставки або підтвердження доставки. |
Зберігайте невизначеність. Нерозпізнана подія має потрапляти на перевірку або до резервного процесу, а не примусово відноситися до найближчої знайомої категорії. Зберігайте вихідний опис, щоб служба підтримки могла використовувати його для усунення проблем.
4. Отримуйте оновлення, не втрачаючи та не дублюючи роботу
Ваш endpoint webhook має перевірити запит, надійно зберегти прийняте оновлення та повернути підтвердження, якого вимагає постачальник. Виконуйте генерацію повідомлень асинхронно, а не очікуйте відповіді служби електронної пошти або SMS під час callback-запиту.
Реалізуйте задокументований постачальником метод перевірки callback-викликів. Не вигадуйте заголовок підпису та не припускайте, що кожен постачальник використовує однакову схему автентифікації. Також застосовуйте HTTPS, обмеження розміру запиту, перевірку корисного навантаження та відповідні засоби контролю доступу.
Спрощений процес обробки може виглядати так. Це операції на рівні застосунку, а не робочий приклад SDK:
receive callback
verify request using documented provider mechanism
validate payload
persist accepted payload and enqueue processing atomically
return documented acknowledgment
process queued update
find internal shipment
normalize relevant events
ignore already-processed events
evaluate chronology and state transition
create notification job if policy permits
commit state and job together
send notification job
check recipient preferences and suppression rules
submit message to messaging service
record result and retry only when appropriate
Атомарні кроки мають значення. Якщо застосунок зберігає зміну статусу, але аварійно завершує роботу до створення завдання сповіщення, клієнт може ніколи не отримати повідомлення. Транзакційний outbox — один із варіантів проєктування: зберігайте зміну стану та завдання в одній транзакції бази даних, а потім дозвольте робітнику відправити завдання.
Обробляйте невідомі посилання на відправлення явно. Ізолюйте їх для розслідування або узгодження, замість того щоб вгадувати, якому клієнту слід надіслати сповіщення.
5. Додайте захист від дублікатів і перевірки хронології
Спроєктуйте приймач так, щоб він витримував повторні callback-виклики та повторні спроби робітників. Якщо це задокументовано, надавайте перевагу стабільному ідентифікатору події постачальника. В іншому разі створіть детермінований відбиток події з відповідних полів, наприклад внутрішнього ідентифікатора відправлення, коду події, часу події та місця. Перевірте цей відбиток на реальних корисних навантаженнях, перш ніж покладатися на нього.
Дедуплікація подій і придушення сповіщень вирішують різні проблеми. Дедуплікація не дає обробити ту саму подію двічі. Придушення не дозволяє кільком різним скануванням створювати фактично однакове повідомлення для клієнта.
Визначте ідентичність сповіщення навколо бізнес-події. Для підтвердження доставки можна використовувати ідентифікатор відправлення та етап доставки. Для спроби доставки може знадобитися ідентичність, специфічна для спроби, оскільки пізніша спроба може бути справді новою подією.
Для оновлень, що надходять не по порядку, порівнюйте часові мітки подій і оцінюйте дозволені переходи станів. Не припускайте, що callback містить лише нове сканування; перевіряйте, чи його задокументована структура представляє окрему подію, знімок або історію. Суперечливі оновлення спрямовуйте на узгодження, а не мовчки відкидайте всі виправлення.
6. Пишіть повідомлення, які пояснюють наступний крок
Кожне сповіщення має містити інформацію про відповідну посилку, підтверджену зміну та наступний крок для клієнта. Додавайте безпечне посилання для відстеження та зрозуміле посилання на замовлення. Не розкривайте повні адреси або зайву персональну інформацію в SMS-повідомленнях і попередніх переглядах на заблокованому екрані.
Наприклад:
- Передано кур’єру для доставки: «Ваша посилка із замовленням {order_reference} передана кур’єру для доставки. Слідкуйте за її переміщенням тут: {tracking_link}.»
- Здійснено спробу доставки: «Перевізник повідомив про спробу доставки вашої посилки. Перевірте сторінку відстеження, щоб дізнатися про доступні подальші кроки: {tracking_link}.»
- Доставлено: «Перевізник позначив вашу посилку із замовленням {order_reference} як доставлену. Перегляньте доступні відомості про доставку: {tracking_link}.»
Відображайте заповнювачі лише на основі перевірених даних. Якщо доступна оцінка доставки і її доречно показувати, позначте її як оцінку. Якщо її немає, не додавайте її замість вигаданої дати.
Для винятків відрізняйте проблему з відправленням від завдання для клієнта. Перешкода може вимагати лише пояснення, тоді як підтверджена проблема з адресою може потребувати дії. Не спрямовуйте клієнтів на сторінку оплати або завантаження документів, спираючись лише на ненадійний текст відстеження у довільній формі.
Вибирайте канали з урахуванням уподобань клієнта, дозволів каналу, терміновості та чинних правил. Перевірте вимоги щодо згоди, відмови від отримання та тихих годин для юрисдикцій і каналів обміну повідомленнями, які ви використовуєте. Відокремлюйте сповіщення про доставку від рекламних кампаній, а не припускайте, що на них поширюються однакові дозволи.
7. Визначте, що відбувається, коли відстеження припиняється
Проактивна комунікація має охоплювати як відсутність прогресу, так і нові події, але сама по собі тиша не доводить, що відправлення затримується або загублене.
Створіть правило застарілого відстеження з урахуванням рівня обслуговування, маршруту, останньої важливої події та будь-якої доступної оцінки доставки. Встановлюйте пороги на основі операційних даних і процесу підтримки, а не застосовуйте один універсальний період очікування до кожного відправлення.
Коли це правило спрацьовує, перевірте пропущену обробку, за можливості узгодьте дані з джерелом відстеження та вирішіть, чи потрібно створити внутрішнє завдання для підтримки. Якщо ви повідомляєте клієнта, використовуйте формулювання, що відповідає відомим фактам: «Ми не отримали нового оновлення відстеження» — це не те саме, що «Ваша посилка загублена».
Призначайте відповідального за невирішені винятки. Система сповіщень, яка багаторазово повідомляє про проблему, але не створює шляху до її вирішення, може посилити невдоволення клієнтів.
8. Перевірте весь процес перед увімкненням автоматичних надсилань
Спочатку запустіть робочий процес у тіньовому режимі: отримуйте реальні або схвалені тестові події, створюйте запропоновані сповіщення та перевіряйте результати, не контактуючи з клієнтами.
- Повторно відтворіть ідентичний callback і переконайтеся, що він не створює ще одного повідомлення.
- Обробіть старішу подію перебування в дорозі після події доставки та перевірте отриманий стан.
- Перевірте відсутні часові мітки, невідомі статуси та неправильно сформовані корисні навантаження.
- Зімітуйте збій бази даних до підтвердження та збій робітника після збереження.
- Перевірте тайм-аути обміну повідомленнями, зокрема невизначену відповідь, коли служба могла вже прийняти повідомлення.
- Переконайтеся, що розділені відправлення створюють формулювання для конкретної посилки.
- Перевірте одержувачів, які відмовилися від отримання, недійсні контактні дані та обробку тихих годин.
- Переконайтеся, що посилання для відстеження не розкривають інформацію про замовлення іншого клієнта.
Відстежуйте прийняті callback-виклики, помилки обробки, вік черги, завдання сповіщень, придушення дублікатів і результати обміну повідомленнями. Вимірюйте затримку обробки від часу отримання вашою системою окремо від віку події перевізника. Це допомагає визначити, чи повільне сповіщення було спричинене доступністю вихідних даних або вашим власним конвеєром.
Почніть із невеликого набору зрозумілих етапів. Розширюйте правила лише після того, як команди підтримки та операцій погодяться, що повідомлення є точними, корисними й вартими отримання.
FAQ
Чи надсилає API відстеження відправлень електронні листи або SMS автоматично?
Не обов’язково. Доступ до даних відстеження та обмін повідомленнями з клієнтами — це окремі можливості. Перевірте задокументовану сферу застосування сервісу. У власній інтеграції ваш застосунок може обробляти оновлення відстеження та надсилати сповіщення через окрему службу обміну повідомленнями.
Чи слід повідомляти клієнтів про кожне сканування відстеження?
Зазвичай ні. Надавайте пріоритет важливим етапам і подіям, що потребують дії. Кілька сканувань на об’єктах можуть означати звичайне транспортування, не змінюючи того, що клієнту потрібно знати. Детальну історію залишайте на сторінці відстеження.
Чи можу я гарантувати сповіщення про доставку в реальному часі?
Ви можете встановити та контролювати цільовий час обробки після отримання оновлення вашою системою. Ви не можете гарантувати, коли перевізник запише або опублікує сканування. Описуйте сервіс з урахуванням цієї залежності.
Як запобігти дублюванню повідомлень про доставку?
Використовуйте постійну дедуплікацію подій, окрему ідентичність сповіщення для кожного бізнес-етапу та транзакційне створення завдань. Якщо служба обміну повідомленнями підтримує ідемпотентність, використовуйте її як додатковий захист. Однієї перевірки дублікатів у пам’яті недостатньо, оскільки вона не переживе перезапуск або роботу кількох робітників.
Що має відбутися, якщо перевізник виправить статус «доставлено»?
Збережіть обидві події та узгодьте стан відправлення. Якщо виправлення істотно впливає на клієнта, надішліть чітке виправлення або передайте випадок до служби підтримки відповідно до вашої політики. Не робіть статус «доставлено» назавжди незворотним лише для спрощення коду.
Джерела
Наведені нижче офіційні ресурси є довідковими матеріалами для реалізації інтеграції 17TRACK, описаної вище. Внутрішня схема, правила сповіщень і процес обробки в цьому посібнику є архітектурними рекомендаціями, а не цитованими умовами API.
- API відстеження 17TRACK — офіційна відправна точка для оцінювання інтеграції API.
- Документація API 17TRACK — довідник щодо форматів запитів постачальника, автентифікації, операцій відстеження та вимог інтеграції.


