Skip to main content
ГоловнаБлогПосібникиВаш перший запит до Tracking API: покроковий посібник із використання REST-клієнта з Postman і Curl

Ваш перший запит до Tracking API: покроковий посібник із використання REST-клієнта з Postman і Curl

17TRACK

Щоб виконати свій перший запит до API відстеження, налаштуйте кінцеву точку, заголовок автентифікації та тіло JSON у REST-клієнті, надішліть запит і перевірте як статус HTTP, так і тіло відповіді. У цьому посібнику використовується Tracking API від 17TRACK, щоб продемонструвати однаковий робочий процес у Postman і curl: зареєструвати відправлення, запросити інформацію про його відстеження та перевірити, чи готовий результат до використання у вашому застосунку.

Ваш перший запит до API відстеження: покроковий огляд у REST-клієнті

Мета — невеликий відтворюваний інтеграційний тест, а не розгортання у виробничому середовищі. Вам знадобляться облікові дані API та номер відстеження, який ви маєте право обробляти. У наведених нижче командах використовується шаблон кінцевої точки v2.2; перед запуском перевірте версію кінцевої точки та вимоги для вашого облікового запису в документації API 17TRACK.

Зрозумійте, що має виконувати ваш перший запит

Інтеграція відстеження відправлення має два окремі завдання: повідомити сервісу, яке відправлення потрібно відстежувати, і отримати інформацію про відстеження, пов’язану з цим відправленням. У продемонстрованому тут робочому процесі це окремі запити. Реєстрація не означає, що посилка вже переміщується, а успішна реєстрація не гарантує, що події перевізника будуть доступні негайно.

Для першого тесту використовуйте одне відправлення, а не пакет. Це спрощує ізоляцію помилок автентифікації, недійсних номерів відстеження та інтерпретації відповіді. Перший корисний етап — не просто «я отримав HTTP 200». Це «API прийняв потрібну мені операцію, і я можу пояснити результат на рівні відправлення».

Postman надає візуальний інтерфейс для редагування запитів і перевірки відповідей. curl робить той самий обмін HTTP відтворюваним із термінала. Жоден із них не змінює правила автентифікації API, дані відправлення чи поведінку обробки. Використовуйте інструмент, який допомагає чіткіше досліджувати запит, а потім відтворіть робочу конфігурацію в іншому інструменті.

Підготуйте облікові дані, відправлення та параметри запиту

Перед відкриттям будь-якого клієнта підготуйте таке:

  • Авторизовані облікові дані API: отримайте їх під час налаштування облікового запису 17TRACK API. Сеанс споживчого відстеження не замінює облікові дані API.
  • Справжній номер відстеження: використовуйте відправлення, яким ви володієте або до якого маєте дозвіл на доступ. Нещодавно активне відправлення зазвичай корисніше за вигаданий номер під час тестування реальних даних відстеження.
  • Перевізник, якщо відомий: зберігайте назву перевізника для діагностики. Якщо для вашого випадку потрібен ідентифікатор перевізника, використовуйте значення та поле, визначені в документації API, а не вгадуйте їх.
  • Актуальний контракт запиту: підтвердьте версію API, заголовок автентифікації, схему запиту та будь-які обмеження облікового запису.
  • Безпечне робоче середовище: не розміщуйте облікові дані, дані клієнтів або повні відповіді відстеження у відкритих репозиторіях, знімках екрана чи спільних повідомленнях до служби підтримки.

У мінімальних прикладах запитів використовуються такі параметри:

ПараметрПриклад конфігурації
Базова URL-адресаhttps://api.17track.net/track/v2.2
Операція реєстраціїPOST /register
Операція отримання інформації про відстеженняPOST /gettrackinfo
Заголовок автентифікації17token: YOUR_API_TOKEN
Формат тілаContent-Type: application/json, із масивом JSON-об’єктів відправлень

Зберігайте номери відстеження як рядки. Перетворення номера на числовий тип може видалити початкові нулі або іншим чином змінити його значення. Заповнювач YOUR_TRACKING_NUMBER нижче потрібно замінити фактичним тестовим відправленням; це не робочий приклад номера.

Виконайте запит реєстрації в Postman

1. Створіть невелике тестове середовище

У Postman створіть середовище з трьома змінними: base_url, tracking_token і tracking_number. Установіть для base_url наведену вище базову URL-адресу, а в інших змінних укажіть облікові дані та номер відправлення. Перед надсиланням запиту виберіть це середовище.

Використовуйте доступні в Postman засоби роботи із секретами для токена та перевірте, чим ділиться або що синхронізує ваше робоче середовище. Приховування значення в інтерфейсі не замінює контроль доступу до нього. Не експортуйте заповнені облікові дані разом із колекцією, призначеною для колег або відкритої документації.

2. Налаштуйте метод, URL-адресу та заголовки

Створіть HTTP-запит, виберіть POST і введіть {{base_url}}/register як URL-адресу. На вкладці Headers додайте:

17token: {{tracking_token}}
Content-Type: application/json

У цьому прикладі облікові дані потрібно передати в спеціальному заголовку 17token. Не замінюйте його конфігурацією токена Bearer лише тому, що інший API використовував такий шаблон. Також перевірте, чи успадковані налаштування колекції не додають ненавмисний заголовок Authorization.

3. Додайте тіло JSON

Відкрийте Body, виберіть raw, а потім JSON. Введіть:

[
  {
    "number": "{{tracking_number}}"
  }
]

Зовнішні квадратні дужки важливі: цей запит використовує масив, навіть якщо він містить лише одне відправлення. Використовуйте подвійні лапки, видаляйте кінцеві коми та не додавайте коментарі до JSON. Якщо документація вимагає додаткової інформації для вашого перевізника або відправлення, додайте задокументовані поля перед надсиланням.

4. Надішліть запит і перевірте результат

Натисніть Send. Спочатку перевірте, чи взагалі отримали відповідь HTTP. Помилка DNS, помилка TLS, проблема з проксі або тайм-аут відрізняються від відповіді, яка пояснює, що запит недійсний. Потім перевірте тіло відповіді на результат операції та інформацію про прийняття або відхилення на рівні відправлення.

Збережіть запит під назвою «Тестове відправлення реєстрації». Запишіть статус HTTP, результат API та будь-яке повідомлення про помилку, не копіюючи токен. Якщо реєстрація не вдалася, усуньте цю проблему перед переходом далі. Повторне надсилання незміненого запиту ускладнює діагностику та може використати ресурси облікового запису.

Відтворіть запит за допомогою curl

У наведених нижче командах використовується оболонка у стилі POSIX, наприклад Bash або Zsh. PowerShell і Windows Command Prompt мають інші правила лапок і змінних. У PowerShell за потреби використовуйте curl.exe, щоб викликати виконуваний файл curl, а не специфічний для оболонки псевдонім команди.

Установіть базову URL-адресу та завантажте облікові дані в змінну середовища за допомогою звичайного процесу роботи із секретами:

export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.

Змінна середовища не дає обліковим даним потрапити до багаторазово використовуваного прикладу, але не є повноцінною системою керування секретами. Для локального тестування не вводьте справжній токен у команду, яку збереже історія оболонки. Для автоматизації використовуйте сховище секретів своєї платформи та обмежте виведення журналів.

Створіть файл із назвою shipment.json і замініть заповнювач тестовим номером відстеження:

[
  {
    "number": "YOUR_TRACKING_NUMBER"
  }
]

Надішліть запит реєстрації:

curl --request POST \
  --url "$TRACKING_BASE_URL/register" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output register-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Це зберігає тіло відповіді у register-response.json і виводить статус HTTP окремо. Тайм-аути підключення та загальний тайм-аут є параметрами локального тестування, а не гарантіями сервісу 17TRACK. Відкрийте збережений файл, щоб перевірити результат API; одного рядка статусу недостатньо.

curl може успішно завершити передавання, навіть якщо сервер повертає відповідь HTTP з помилкою. І навпаки, помилка транспорту може перешкодити отриманню будь-якої придатної відповіді API. Під час написання сценаріїв розглядайте код завершення curl, статус HTTP і результат на рівні застосунку як окремі сигнали.

Запросіть інформацію про відстеження відправлення

Після підтвердження реєстрації продублюйте запит Postman і змініть URL-адресу на {{base_url}}/gettrackinfo. Збережіть метод POST, заголовок автентифікації, тип вмісту та тіло відправлення. Збережіть його окремо, щоб випадково не зареєструвати відправлення повторно, коли ви маєте намір отримати дані.

Еквівалентний запит curl:

curl --request POST \
  --url "$TRACKING_BASE_URL/gettrackinfo" \
  --header "17token: $TRACKING_API_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @shipment.json \
  --connect-timeout 10 \
  --max-time 30 \
  --silent --show-error \
  --output tracking-response.json \
  --write-out 'HTTP status: %{http_code}\n'

Не припускайте, що щойно зареєстроване відправлення одразу поверне повну історію подій. Доступність даних залежить від відправлення та обробки сервісом. Якщо інформація ще недоступна, дотримуйтеся задокументованих рекомендацій щодо отримання та оновлення, а не реєструйте той самий номер повторно й не запускайте надто часте опитування.

Читайте відповідь на трьох рівнях

  1. Транспорт: чи підключився клієнт і отримав відповідь HTTP?
  2. Операція: чи прийняв API запит і чи успішно оброблено окреме відправлення?
  3. Інформація про відправлення: чи ідентифікують повернуті дані потрібну посилку та що насправді підтверджує її статус або історія подій?

Використовуйте офіційну схему відповіді, щоб знайти поля статусу, перевізника та подій. Розрізняйте нормалізований статус відправлення та оригінальний опис події перевізника. Успішний пошук не є доказом доставки, а відсутність подій не є доказом втрати посилки.

Під час збереження часових міток зберігайте надані дані про часовий пояс або зміщення. Не сортуйте необроблені рядки дат у різних форматах, припускаючи, що вони утворюють правильну хронологічну послідовність. Також розрізняйте час отримання запису вашим застосунком і час виникнення події відправлення.

Усувайте проблеми, не змінюючи все одночасно

  • Немає відповіді: перевірте ім’я хоста, доступ до мережі, налаштування проксі, конфігурацію TLS і локальний тайм-аут. Не вимикайте перевірку сертифікатів як звичайне виправлення.
  • Помилка автентифікації: переконайтеся, що токен активний, заголовок 17token присутній, а вибране середовище Postman правильно розгортає змінну. Перевірте випадкові пробіли.
  • Недійсний запит: перевірте версію API, шлях операції, метод POST, тип вмісту та структуру масиву JSON за документацією.
  • Відправлення відхилено: прочитайте помилку конкретного відправлення. Перевірте номер і необхідну інформацію про перевізника, а не вважайте кожне відхилення проблемою автентифікації.
  • Немає подій відстеження: підтвердьте реєстрацію та ідентичність потрібного відправлення. Перевірте, чи потрібна інформація про перевізника та чи доступні оновлення перед повторною спробою.
  • Postman працює, а curl — ні: порівняйте розгорнуту URL-адресу, фактичні заголовки та байти тіла. Лапки оболонки й невстановлені змінні середовища часто спричиняють розбіжності між запитами.

Змінюйте одну змінну за тест і ведіть короткий запис результату. Якщо ви перевіряєте консоль Postman або використовуєте докладне виведення curl, вважайте його конфіденційним: заголовки запиту можуть розкрити облікові дані. Перед поширенням діагностики видаляйте секрети та інформацію про клієнтів.

Знайте, коли посібник завершено

Ви виконали змістовний перший інтеграційний тест, коли обидва клієнти надсилають потрібний запит, реєстрація зрозуміла, отримання повертає інтерпретований результат, а ви можете відрізнити помилку API від відправлення без нової інформації. Однакові коди статусу HTTP самі по собі не доводять, що два клієнти працювали ідентично.

Перед перенесенням процесу до застосунку зберігайте облікові дані на сервері, перевіряйте вхідні дані та використовуйте структуровану обробку помилок. Ознайомтеся із задокументованими обмеженнями швидкості, пакетними обмеженнями, рекомендаціями щодо повторних спроб і варіантами доставки оновлень для вашого облікового запису. Не припускайте, що реєстрацію безпечно повторювати без перевірки після тайм-ауту: сервер міг обробити запит, навіть якщо ваш клієнт не отримав відповіді.

Додайте тести для недійсних облікових даних, некоректного JSON, недійсного номера відправлення, уже зареєстрованого відправлення, недоступних даних відстеження та тайм-ауту мережі. Кожен випадок має призводити до визначеного результату застосунку, а не до необробленого винятку чи оманливого статусу для клієнта.

Поширені запитання

Чи можна тестувати без справжнього номера відстеження?

Ви можете перевірити деякі варіанти перевірки запиту за допомогою недійсного значення, але це не перевіряє відстеження відправлення. Для тестування реальних подій використовуйте авторизоване відправлення або задокументований тестовий об’єкт, якщо сервіс його надає. Не припускайте, що довільні приклади номерів належать до пісочниці.

Чому відповідь HTTP 200 все ще містить помилку?

Статус HTTP і результати застосунку описують різні рівні. Сервер може успішно отримати й обробити запит, одночасно повідомивши, що окреме відправлення відхилено. Читайте тіло відповіді та задокументований результат на рівні відправлення, а не лише статус HTTP.

Чому для отримання інформації про відстеження використовується POST?

Використовуйте метод, визначений контрактом кінцевої точки. Цей приклад отримання приймає ідентифікатори відправлень у тілі JSON-запиту через POST. Заміна його на GET лише тому, що операція читає дані, не зберігає задокументований запит.

Чи слід розміщувати токен API у JavaScript браузера?

Не вбудовуйте приватні облікові дані API у відкрито доставлений frontend-код. Перенаправляйте запити через авторизований backend, який захищає облікові дані, перевіряє вхідні дані та контролює, до якої інформації про відправлення має доступ кожен користувач.

Чи потрібні мені і Postman, і curl для виробничого середовища?

Ні. Це корисні інструменти тестування та діагностики. Ваш виробничий застосунок може використовувати відповідний HTTP-клієнт. Зберігайте очищений запит Postman або команду curl як відтворюваний довідник, без дійсного токена чи зайвих даних клієнтів.

Джерела