Вашата първа заявка към Tracking API: ръководство за Rest Client с Postman и Curl
За да направите първата си заявка към Tracking API, конфигурирайте крайна точка, заглавка за удостоверяване и JSON тяло в REST клиент, изпратете заявката и проверете както HTTP статуса, така и тялото на отговора. Това ръководство използва Tracking API на 17TRACK, за да демонстрира същия работен процес в Postman и curl: регистриране на пратка, заявяване на информация за проследяването ѝ и проверка дали резултатът е готов за използване от приложението ви.
Целта е малък, възпроизводим интеграционен тест, а не внедряване в продукционна среда. Ще ви бъдат нужни 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 token само защото друг API използва този модел. Проверете също дали наследените настройки на колекцията не добавят непреднамерена заглавка Authorization.
3. Добавете JSON тялото
Отворете Body, изберете raw и след това JSON. Въведете:
[
{
"number": "{{tracking_number}}"
}
]
Външните квадратни скоби са важни: тази заявка използва масив, дори когато съдържа само една пратка. Използвайте двойни кавички, премахнете крайните запетаи и не поставяйте коментари в JSON. Ако документацията изисква допълнителна информация за вашия превозвач или пратка, добавете документираните полета, преди да изпратите заявката.
4. Изпратете и проверете резултата
Натиснете Send. Първо проверете дали изобщо сте получили HTTP отговор. DNS грешка, TLS грешка, проблем с прокси или изтичане на времето се различават от отговор, който обяснява, че заявката е невалидна. След това проверете тялото на отговора за резултата от операцията и всяка информация за приемане или отхвърляне на ниво пратка.
Запазете заявката като „Register test shipment“. Запишете HTTP статуса, резултата от API и всяко съобщение за грешка, без да копирате токена. Ако регистрацията е неуспешна, отстранете проблема, преди да продължите. Повторното изпращане на непроменена заявка затруднява диагностиката и може да изразходва ресурси на акаунта.
Възпроизведете заявката с curl
Следващите команди използват shell в POSIX стил, например Bash или Zsh. PowerShell и Windows Command Prompt имат различни правила за кавички и променливи. В PowerShell използвайте curl.exe, когато е необходимо да извикате изпълнимия файл curl вместо специфичен за shell псевдоним.
Задайте основния URL и заредете идентификационните си данни в променлива на средата чрез обичайния си процес за работа със секрети:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Set TRACKING_API_TOKEN securely before continuing.
Променливата на средата държи идентификационните данни извън повторно използваемия пример, но не е цялостна система за управление на секрети. При локално тестване избягвайте въвеждането на реален токен в команда, която shell историята ви ще запази. За автоматизация използвайте хранилището за секрети на платформата си и ограничете изхода в логовете.
Създайте файл с име 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, действителните заглавки и байтовете на тялото. Цитирането в shell и непосочените променливи на средата са чести причини заявките да се различават.
Променяйте по една променлива на тест и водете кратък запис на резултата. Ако проверявате конзолата на Postman или използвате подробен изход на curl, третирайте изхода като чувствителен: заглавките на заявката могат да разкрият идентификационни данни. Заличавайте секретите и клиентската информация, преди да споделяте диагностични данни.
Знайте кога ръководството е завършено
Завършили сте смислен първи интеграционен тест, когато и двата клиента изпращат желаната заявка, регистрацията е разбрана, извличането връща интерпретируем резултат и можете да различите грешка на API от пратка без нова информация. Само съвпадащите HTTP статус кодове не доказват, че двата клиента са се държали идентично.
Преди да преместите работния процес в приложение, съхранявайте идентификационните данни на сървъра, валидирайте входовете и използвайте структурирана обработка на грешки. Направете справка с документираните ограничения за честота, ограниченията за партиди, указанията за повторни опити и опциите за доставяне на актуализации за вашия акаунт. Не приемайте, че е безопасно сляпо да повторите регистрацията след изтичане на времето: сървърът може да е обработил заявката, въпреки че клиентът ви не е получил отговора.
Добавете тестове за невалидни идентификационни данни, неправилен JSON, невалиден номер на пратка, вече регистрирана пратка, недостъпни данни за проследяване и мрежово изтичане на времето. Всеки случай трябва да води до преднамерен резултат в приложението, а не до необработено изключение или подвеждащ статус за клиента.
ЧЗВ
Мога ли да тествам без реален номер за проследяване?
Можете да тествате някои поведения при валидиране на заявки с невалидна стойност, но това не проверява проследяването на пратка. За да тествате реални събития, използвайте упълномощена пратка или документиран тестов набор, ако услугата предоставя такъв. Не приемайте, че произволни примерни номера принадлежат към sandbox среда.
Защо HTTP 200 отговор все още съдържа грешка?
HTTP статусът и резултатите от приложението описват различни нива. Сървърът може успешно да получи и обработи заявка, като същевременно съобщи, че отделна пратка е отхвърлена. Прочетете тялото на отговора и документирания резултат на ниво пратка, а не само HTTP статуса.
Защо се използва POST за извличане на информация за проследяване?
Използвайте метода, посочен в договора на крайната точка. Този пример за извличане приема идентификатори на пратки в JSON тяло на заявката чрез POST. Промяната му на GET, понеже операцията чете данни, не запазва документираната заявка.
Трябва ли да поставя API токена в JavaScript в браузъра?
Не вграждайте частни API идентификационни данни във фронтенд код, доставян публично. Насочвайте заявките през упълномощен бекенд, който защитава идентификационните данни, валидира входовете и контролира до коя информация за пратки има достъп всеки потребител.
Необходими ли са ми и Postman, и curl за продукционна среда?
Не. Те са полезни инструменти за тестване и диагностика. Продукционното ви приложение може да използва подходящ HTTP клиент. Съхранявайте пречистена заявка в Postman или curl команда като възпроизводим справочник, без активен токен или ненужни клиентски данни.
Източници
- Документация за API на 17TRACK — справочник за удостоверяване, договори на крайни точки, полета на заявки, интерпретация на отговори и изисквания за интеграция.
- Документация на Postman: Изпращане на API заявки — конфигуриране на заявки и проверка на отговори.
- Документация на Postman: Променливи — конфигуриране на заявки чрез променливи.
- Ръководство за curl — опции за команди за заглавки, тела на заявки, времеви ограничения, запазени отговори и извеждане на HTTP статус.


