Skip to main content
ДомаБлогВодичиВашето прво барање до Tracking API: водич за Rest Client со Postman и Curl

Вашето прво барање до Tracking API: водич за Rest Client со Postman и Curl

17TRACK

За да го направите вашето прво барање до API за следење, конфигурирајте ја крајната точка, заглавието за автентикација и JSON-телото во REST-клиент, испратете го барањето и проверете ги и HTTP-статусот и телото на одговорот. Овој водич го користи Tracking API на 17TRACK за да го прикаже истиот тек на работа во Postman и curl: регистрирајте пратка, побарајте ги нејзините информации за следење и проверете дали резултатот е подготвен за користење во вашата апликација.

Your First Tracking API Request a Rest Client Walkthrough with

Целта е мал, репродуцибилен интеграциски тест — не продукциско распоредување. Ќе ви бидат потребни API-податоци за пристап и број за следење што сте овластени да го обработувате. Командите подолу го користат образецот на крајната точка v2.2; пред да ги извршите, потврдете ја верзијата на крајната точка и барањата специфични за сметката во документацијата за API на 17TRACK.

Разберете што треба да постигне вашето прво барање

Интеграцијата за следење пратки има две одделни задачи: да му кажете на сервисот која пратка да ја следи и да ги преземете информациите за следење поврзани со таа пратка. Во текот прикажан овде, тоа се одделни барања. Регистрацијата не значи дека пакетот веќе се движел, а успешната регистрација не гарантира дека настаните од превозникот веднаш ќе бидат достапни.

За вашиот прв тест, користете една пратка наместо серија. Така полесно ќе ги изолирате грешките во автентикацијата, невалидните броеви за следење и толкувањето на одговорот. Вашата прва корисна пресвртница не е само „Добив HTTP 200“. Таа е „API-то ја прифати планираната операција и можам да го објаснам резултатот на ниво на пратка“.

Postman ви обезбедува визуелен интерфејс за уредување барања и проверка на одговорите. curl ја прави истата HTTP-размена репродуцибилна од терминал. Ниту една од алатките не ги менува правилата за автентикација на API-то, податоците за пратката или однесувањето при обработка. Користете ја онаа што ви помага појасно да го истражите барањето, а потоа репродуцирајте ја функционалната конфигурација во другата алатка.

Подгответе ги податоците за пристап, пратката и деталите за барањето

Пред да отворите кој било клиент, подгответе го следново:

  • Овластени API-податоци за пристап: добијте ги преку поставувањето на вашата API-сметка на 17TRACK. Потрошувачка сесија за следење не е замена за API-податоци за пристап.
  • Вистински број за следење: користете пратка што е ваша или до која имате дозвола за пристап. Неодамна активна пратка обично е покорисна од измислен број при тестирање на вистински податоци за следење.
  • Превозникот, ако е познат: имајте го името на превозникот при рака за дијагностика. Ако за вашиот случај е потребен идентификатор на превозникот, користете ја вредноста и полето дефинирани во документацијата за API, наместо да погодувате.
  • Тековниот договор за барањето: потврдете ја верзијата на API-то, заглавието за автентикација, шемата на барањето и сите ограничувања на сметката.
  • Безбедно работно место: избегнувајте да ставате податоци за пристап, детали за клиенти или целосни одговори за следење во јавни складишта, слики од екранот или споделени пораки до поддршката.

Минималните примери за барање ги користат следните поставки:

ПоставкаПример-конфигурација
Основен URLhttps://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-грешка, проблем со прокси или истек на времето се разликуваат од одговор што објаснува дека барањето било невалидно. Потоа проверете го телото на одговорот за резултатот од операцијата и сите информации за прифаќање или одбивање на ниво на пратка.

Зачувајте го барањето како „Register test shipment“. Забележете го 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'
# Поставете го TRACKING_API_TOKEN безбедно пред да продолжите.

Променливата на окружувањето ги задржува податоците за пристап надвор од примерот што може повторно да се користи, но не е целосен систем за управување со тајни. При локално тестирање, избегнувајте да внесувате вистински токен во команда што историјата на школката ќе ја зачува. За автоматизација, користете го складиштето за тајни на вашата платформа и ограничете го излезот во дневниците.

Создајте датотека со име 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-команда како репродуцибилна референца, без активен токен или непотребни податоци за клиенти.

Извори