Як інтегрувати API відстеження відправлень у ваш інтернет-магазин
Щоб інтегрувати API відстеження відправлень у свій інтернет-магазин, підключіть систему замовлень до постачальника послуг відстеження, надсилайте дані про відправлення та перевізника через захищений серверний запит, зберігайте нормалізовані події відстеження та відображайте отриманий статус в інтерфейсах для клієнтів і служби підтримки. Надійна реалізація — це більше, ніж додавання поля номера відстеження: вона має обробляти вибір перевізника, оновлення статусу, винятки доставки, повторні спроби, конфіденційність і те, як клієнти фактично використовують інформацію після покупки.
У цьому посібнику описано практичний підхід до інтеграції для власників магазинів, розробників і операційних команд. Як орієнтир використано офіційну документацію 17TRACK Tracking API, але ті самі принципи планування застосовуються під час оцінювання іншого постачальника послуг для кількох перевізників.
Визначте, чого має досягти інтеграція
Починайте з бізнес-результату, а не з кінцевої точки API. Більшість магазинів прагнуть зменшити кількість звернень «Де моє замовлення?», надати покупцям чітке уявлення про доставку та допомогти операційним командам виявляти затримані відправлення до того, як клієнт поскаржиться. Для досягнення цих цілей потрібні різні дані та робочі процеси.
- Видимість для клієнтів: показуйте поточний статус відправлення, орієнтовну інформацію про доставку, якщо вона доступна, дані про перевізника та останню важливу подію.
- Операційна видимість: надайте співробітникам можливість знаходити затримані, призупинені, повернені відправлення або відправлення з винятками серед різних перевізників.
- Автоматизовані повідомлення: запускайте схвалені сповіщення електронною поштою, SMS або іншими каналами, коли відправлення досягає визначеного стану.
- Узгодженість даних: перетворюйте різні назви подій перевізників на менший набір статусів, які ваш магазин може надійно використовувати.
Визначте ці результати до вибору способу реалізації. API відстеження може надавати дані про відправлення, але він автоматично не визначає, які події заслуговують на повідомлення клієнту або як ваш магазин має обробляти проблему з адресою.
Виберіть правильну архітектуру інтеграції
Типова архітектура складається з чотирьох рівнів: платформи електронної комерції, сервісу інтеграції, постачальника послуг відстеження та клієнтського інтерфейсу. Сервісом інтеграції може бути серверна програма, система керування замовленнями або безсерверний робочий процес. Зберігати цю логіку на сервері зазвичай безпечніше, ніж розміщувати облікові дані API в коді браузера.
Основний потік виглядає так:
- Оплачене замовлення обробляється та отримує номер відстеження і перевізника.
- Ваша серверна частина надсилає дані про відправлення постачальнику послуг відстеження.
- Постачальник повертає ідентифікатор відстеження або дані відстеження відповідно до дизайну свого API.
- Ваша система зберігає посилання постачальника та зіставляє події відправлення з внутрішніми статусами.
- Запланований процес оновлення або підтримуване сповіщення про подію оновлює інформацію про відправлення.
- Вітрина магазину, сторінка замовлення, інструменти підтримки та сервіс сповіщень зчитують дані з вашого власного нормалізованого сховища.
Не змушуйте кожен перегляд сторінки звертатися до перевізника або API відстеження. Така схема може спричинити повільну роботу для клієнтів, дублювання запитів, проблеми з обмеженнями частоти та неузгоджені результати. Зберігайте останній прийнятий стан відстеження у своїй базі даних і оновлюйте його за допомогою контрольованих фонових завдань або підтримуваного постачальником механізму оновлення.
Перевірте документацію постачальника до початку кодування
Перед реалізацією перегляньте офіційну документацію API постачальника щодо автентифікації, форматів запитів, полів відповіді, підтримуваних перевізників, обробки помилок, механізмів оновлення та вимог до облікового запису. 17TRACK надає окрему сторінку продукту Tracking API та документацію для розробників. Вважайте ці сторінки джерелом актуальної інформації про поведінку API, а не покладайтеся на приклади, скопійовані з форумів або старих посібників з інтеграції.
Складіть короткий список вимог на основі документації:
- Як видаються, зберігаються, змінюються та відкликаються облікові дані API?
- Чи потрібен для запиту код перевізника, чи сервіс може визначити перевізника за номером відстеження?
- Які поля відповіді ідентифікують відправлення, статус, місцезнаходження, часові позначки та повідомлення про виняток?
- Як доставляються асинхронні оновлення, якщо обліковий запис їх підтримує?
- Які задокументовані обмеження запитів, правила тарифікації, очікування щодо тайм-аутів і коди помилок?
- Як обробляти дублікати номерів відстеження, недійсні номери, невідомих перевізників і доставлені відправлення?
Не робіть висновків про функцію лише з назви продукту. Наприклад, «у реальному часі» може описувати позиціонування продукту, а не гарантувати, що кожна подія перевізника з’являється негайно. Ваша реалізація має пояснювати, що сканування перевізника може затримуватися, а API не може створити сканування, про яке перевізник не повідомив.
Підготуйте дані про замовлення та відправлення
Найчастіше найкращий момент для створення відстеження — це виконання відправлення, а не створення замовлення. Замовлення може бути оплаченим, але ще не упакованим, а номер відстеження може бути створений до прийняття посилки перевізником. Визначте, яка подія у вашому робочому процесі виконання має створювати запис відстеження.
Щонайменше внутрішній запис відправлення має розрізняти такі значення:
- Внутрішній ідентифікатор замовлення та ідентифікатор виконання
- Номер відстеження
- Назва або код перевізника
- Країна або регіон призначення, якщо це операційно необхідно
- Ідентифікатор відстеження постачальника або посилання на підписку, якщо повертається
- Поточний нормалізований статус
- Часова позначка останньої події та часова позначка останньої синхронізації
- Необроблена відповідь постачальника або контрольоване посилання на аудит
Зберігайте дані замовлення та дані відправлення окремо. Одне замовлення може містити кілька посилок, розділені відправлення або різних перевізників. Припущення, що одному замовленню відповідає один номер відстеження, часто не працює, коли склад відправляє товари окремо.
Використовуйте ідемпотентний процес. Якщо система виконання повторно надсилає той самий запит, інтеграція має оновити наявне відправлення, а не створити дублікати підписок або повідомлень клієнтам. Практичний ключ ідемпотентності може поєднувати ваш внутрішній ідентифікатор виконання, ідентифікатор перевізника та номер відстеження з урахуванням власних вимог постачальника.
Нормалізуйте статуси перевізників для клієнтів
Перевізники використовують різні назви та послідовності подій. Ваш магазин має підтримувати невелику внутрішню модель статусів, наприклад Інформацію отримано, У дорозі, Передано для доставки, Доставлено, Виняток і Повернено. Зберігайте оригінальну подію перевізника для співробітників служби підтримки, але використовуйте нормалізований статус для логіки вітрини.
Правила нормалізації мають бути чіткими. Подію «етикетку створено» не слід подавати як доказ того, що посилка рухається. «Доставлено» слід розглядати як подію, про яку повідомив перевізник, а не як гарантію того, що клієнт фізично знайшов посилку. Виняток не слід мовчки перетворювати на «у дорозі» лише тому, що відправлення може продовжити рух пізніше.
Також визначте пріоритет статусів і обробку регресій. Дані перевізника із затримкою можуть надходити не в порядку подій. Порівнюйте часові позначки подій, якщо вони доступні, записуйте необроблену подію та не замінюйте новіший стан «доставлено» старішим станом «у дорозі». Якщо часові позначки відсутні або неоднозначні, позначте запис для обережного оновлення, а не вигадуйте послідовність.
Створіть серверний потік запитів
Ваша серверна частина має перевіряти вхідні дані про виконання перед викликом постачальника послуг відстеження. Перевірте наявність номера відстеження, видаліть випадкові пробіли, перевірте очікуваний формат, де це доречно, і переконайтеся, що значення перевізника допустиме. Не відхиляйте незвичні, але дійсні номери відстеження лише тому, що вони не відповідають вузькому локальному шаблону.
Потік запитів, незалежний від постачальника, можна представити так:
отримати подію виконання
перевірити поля замовлення та відправлення
перевірити наявність наявного ключа ідемпотентності
надіслати задокументований запит відстеження із сервера
зберегти відповідь постачальника та внутрішній запис відправлення
поставити оновлення в чергу або обробити підтримувану подію оновлення
опублікувати у вітрині лише схвалені поляВикористовуйте короткі тайм-аути, обмежені повторні спроби та експоненційне збільшення інтервалу між спробами для тимчасових збоїв. Не повторюйте кожну помилку. Помилка автентифікації, недійсний запит або непідтримуваний перевізник зазвичай потребують виправлення, а не повторних викликів. Записуйте ідентифікатор кореляції, результат запиту та категорію помилки постачальника, але не зберігайте в журналах застосунку ключі API, повні адреси клієнтів або зайву персональну інформацію.
Зберігайте відповідь постачальника окремо від моделі, орієнтованої на клієнта. Це спрощує зміну постачальників, виправлення правила зіставлення та обмеження інформації, доступної через загальнодоступну сторінку замовлення.
Спроєктуйте клієнтський інтерфейс відстеження
Сторінка відстеження має швидко відповідати на три запитання: який поточний стан, що сталося востаннє та що клієнту робити далі? Показуйте посилання на замовлення, номер відправлення у формі, що враховує конфіденційність, назву перевізника, час останньої події та зрозуміле пояснення винятків.
Не показуйте порожню часову шкалу так, ніби це технічна помилка. До першого сканування перевізником поясніть, що інформацію про відправлення отримано, але рух може ще не відображатися. Для винятку надавайте зрозуміле пояснення лише тоді, коли вихідні дані це підтверджують. Якщо перевізник повідомляє про проблему з адресою, додайте посилання на процес підтримки або дію служби роботи з клієнтами, яку ваш бізнес справді може запропонувати.
Для магазинів, створених на Shopify або іншій платформі електронної комерції, перевірте, як платформа надає доступ до подій виконання, облікових записів клієнтів, сторінок статусу замовлень і шаблонів сповіщень. Офіційна документація для розробників Shopify містить ресурси для вебхуків і даних про виконання. API платформи та версійована документація можуть змінюватися, тому підтвердьте версію, яку використовує ваша програма, до початку роботи в робочому середовищі.
Обережно використовуйте сповіщення
Події відправлення є корисними тригерами, але надсилання повідомлення про кожне сканування перевізника може спричинити втому від сповіщень. Визначте бізнес-правила, наприклад сповіщення про створення відправлення, важливий прогрес у дорозі, передачу для доставки, доставку та вибрані винятки. Пригнічуйте дублікати та встановіть мінімальний інтервал для повторних повідомлень про затримку.
Розділяйте операційні сповіщення та повідомлення клієнтам. Команді підтримки може бути потрібно знати, що відправлення не змінювалося кілька днів, тоді як клієнту може знадобитися повідомлення лише тоді, коли перевізник повідомляє про конкретний виняток. Часовий поріг має враховувати рівень обслуговування, пункт призначення, перевізника та спосіб доставки, а не універсальне число без операційного обґрунтування.
Тестуйте на реальних сценаріях доставки
Успішної відповіді для одного номера відстеження недостатньо для запуску в робочому середовищі. Створіть матрицю тестування, що охоплює кількох перевізників, країни, типи відправлень і стани подій. Протестуйте щонайменше:
- Нещодавно створене відправлення без сканування перевізником
- Звичайне відправлення в дорозі
- Відправлення, передане для доставки
- Доставлене відправлення
- Виняток або подію, пов’язану з адресою
- Повернене відправлення
- Недійсний номер відстеження
- Дубльовану подію виконання
- Затриману відповідь постачальника або тайм-аут
- Подію, що надійшла не в порядку
Оцінюйте не лише доступність API. Перевіряйте, чи оновлюється правильне замовлення, чи бачить клієнт зрозумілий текст, чи придушуються дубльовані сповіщення та чи можуть співробітники підтримки визначити оригінальну подію перевізника. Спочатку виконайте обмежений запуск, збережіть операційний резервний процес і контролюйте категорії помилок після випуску.
Безпека, конфіденційність і обслуговування
Зберігайте облікові дані в менеджері секретів або захищеній змінній середовища, а не в коді теми, мобільному коді, системі контролю версій чи запитах браузера. Обмежуйте доступ до даних про відправлення відповідно до ролей, використовуйте HTTPS і перевіряйте, як довго зберігаються необроблені відповіді та поля, пов’язані з клієнтами.
Регулярно переглядайте документацію постачальника та версію API вашої платформи електронної комерції. Підтримка перевізників, назви подій, вимоги до автентифікації та поведінка вебхуків платформи можуть змінюватися. Зробіть правила зіставлення статусів налаштовуваними, задокументуйте припущення, на яких вони ґрунтуються, і забезпечте можливість повторно обробити або узгодити відправлення без повторного надсилання повідомлення клієнту.
API 17TRACK є доречним варіантом для оцінювання, коли вашому магазину потрібна спеціалізована інтеграція відстеження для різних перевізників. Відповідний вибір усе одно залежить від перевізників, яких ви використовуєте, країн, до яких здійснюєте доставку, поведінки оновлень, задокументованої для вашого облікового запису, очікуваного обсягу запитів та операційних засобів контролю, потрібних вашій команді. Підтвердьте ці моменти в офіційній документації та під час контрольованого підтвердження концепції до затвердження проєкту для робочого середовища.
Поширені запитання
Чи слід створювати відстеження під час розміщення замовлення?
Зазвичай ні. Створюйте або активуйте запис відправлення, коли у вашому робочому процесі виконання вже визначені перевізник і номер відстеження. Створення запису під час оформлення замовлення може призвести до появи записів для замовлень, які пізніше скасовуються, не виконуються або розділяються.
Чи може API відстеження гарантувати інформацію про доставку в реальному часі?
Ні. Жоден API не може гарантувати, що кожне сканування перевізника буде негайно видимим. Постачальник залежить від даних перевізника, а системи перевізників можуть повідомляти про події із затримками або пропусками. Точно відображайте часові позначки та формулювання статусів і не обіцяйте точний час оновлення, якщо відповідна документація та угода про обслуговування не підтверджують таку обіцянку.
Чи має браузер безпосередньо викликати API відстеження?
У більшості реалізацій — ні. Використовуйте серверну інтеграцію, щоб облікові дані залишалися захищеними, відповіді можна було нормалізувати, повторні спроби — контролювати, а дані для клієнтів — фільтрувати. Вітрина зазвичай має зчитувати схвалене представлення відправлення з вашої програми.
Як магазину обробляти кілька посилок в одному замовленні?
Моделюйте кожне виконання або посилку як окреме відправлення, зберігаючи ідентифікатор батьківського замовлення. На сторінці замовлення можна показувати загальний підсумок і окремі часові шкали для кожної посилки. Це не дозволить приховати затриману посилку за статусом «доставлено» іншої посилки.
Який перший робочий показник слід контролювати?
Контролюйте весь потік — від створення виконання до правильного оновлення, видимого клієнту. Самого успіху API недостатньо. Відстежуйте дублікати записів, застарілі відправлення, невідображені події, помилки сповіщень і відсоток відправлень, які потребують ручного виправлення.
