Ваш первый запрос к Tracking API: пошаговое руководство по REST-клиенту с Postman и Curl
Чтобы выполнить свой первый запрос к API отслеживания, настройте конечную точку, заголовок аутентификации и тело JSON в REST-клиенте, отправьте запрос и проверьте как статус HTTP, так и тело ответа. В этом руководстве используется Tracking API 17TRACK, чтобы продемонстрировать один и тот же рабочий процесс в Postman и curl: зарегистрировать отправление, запросить информацию о его отслеживании и проверить, готов ли результат к использованию вашим приложением.
Цель — небольшой воспроизводимый интеграционный тест, а не развертывание в рабочей среде. Вам понадобятся учетные данные API и номер отслеживания, обработку которого вы имеете право выполнять. В приведенных ниже командах используется шаблон конечной точки v2.2; перед запуском подтвердите версию конечной точки и требования для вашей учетной записи в документации API 17TRACK.
Поймите, чего должен достичь ваш первый запрос
Интеграция отслеживания отправлений включает две отдельные задачи: указать сервису, какое отправление нужно отслеживать, и получить информацию об отслеживании, связанную с этим отправлением. В представленном здесь рабочем процессе это отдельные запросы. Регистрация не означает, что посылка уже перемещается, а успешная регистрация не гарантирует, что события перевозчика будут доступны немедленно.
Для первого теста используйте одно отправление, а не пакет. Так будет проще изолировать ошибки аутентификации, недействительные номера отслеживания и проблемы интерпретации ответа. Первый полезный этап — это не просто «я получил HTTP 200». Это «API принял запрошенную мной операцию, и я могу объяснить результат на уровне отправления».
Postman предоставляет визуальный интерфейс для редактирования запросов и проверки ответов. curl делает тот же обмен HTTP воспроизводимым из терминала. Ни один из инструментов не меняет правила аутентификации API, данные отправления или поведение обработки. Используйте тот инструмент, который помогает яснее исследовать запрос, а затем воспроизведите рабочую конфигурацию в другом.
Подготовьте учетные данные, отправление и сведения о запросе
Перед открытием любого из клиентов соберите следующее:
- Авторизованные учетные данные API: получите их при настройке учетной записи API 17TRACK. Сессия потребительского отслеживания не заменяет учетные данные 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'
Не предполагайте, что недавно зарегистрированное отправление сразу вернет полную историю событий. Доступность данных зависит от отправления и обработки сервисом. Если информация еще недоступна, следуйте документированным рекомендациям по получению и обновлению данных, а не регистрируйте один и тот же номер повторно и не запускайте слишком частый цикл опроса.
Читайте ответ на трех уровнях
- Передача: удалось ли клиенту подключиться и получить HTTP-ответ?
- Операция: принял ли API запрос и успешно ли обработал отдельное отправление?
- Информация об отправлении: идентифицируют ли возвращенные данные нужную посылку и что именно подтверждают ее статус или история событий?
Используйте официальную схему ответа, чтобы найти поля статуса, перевозчика и событий. Различайте нормализованный статус отправления и исходное описание события перевозчиком. Успешный поиск не является доказательством доставки, а отсутствие событий не является доказательством потери посылки.
При сохранении временных меток сохраняйте предоставленную информацию о часовом поясе или смещении. Не сортируйте необработанные строки дат из разных форматов, предполагая, что они образуют правильную хронологическую последовательность. Также различайте время получения записи вашим приложением и время, когда произошло событие отправления.
Устраняйте неполадки, не меняя все сразу
- Нет ответа: проверьте имя хоста, доступ к сети, настройки прокси, конфигурацию 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 в общедоступный код интерфейсной части. Направляйте запросы через авторизованный сервер, который защищает учетные данные, проверяет входные данные и контролирует, к какой информации об отправлениях может получить доступ каждый пользователь.
Нужны ли мне и Postman, и curl для рабочей среды?
Нет. Это полезные инструменты тестирования и диагностики. Рабочее приложение может использовать подходящий HTTP-клиент. Сохраните очищенный запрос Postman или команду curl в качестве воспроизводимого справочного примера без действующего токена и лишних данных клиентов.
Источники
- Документация API 17TRACK — справочная информация об аутентификации, контрактах конечных точек, полях запросов, интерпретации ответов и требованиях к интеграции.
- Документация Postman: отправка запросов API — настройка запросов и проверка ответов.
- Документация Postman: переменные — настройка запросов на основе переменных.
- Руководство curl — параметры команд для заголовков, тел запросов, тайм-аутов, сохранения ответов и вывода статуса HTTP.


