Skip to main content
Басты бетБлогНұсқаулықтарСіздің алғашқы Tracking API сұрауыңыз: Postman және Curl көмегімен Rest Client бойынша нұсқаулық

Сіздің алғашқы Tracking API сұрауыңыз: Postman және Curl көмегімен Rest Client бойынша нұсқаулық

17TRACK

Алғашқы tracking API сұрауын жіберу үшін REST клиентінде endpoint, аутентификация тақырыбын және JSON body параметрлерін баптап, сұрауды жіберіңіз де, HTTP күйін және жауап body бөлігін тексеріңіз. Бұл нұсқаулықта 17TRACK’s Tracking API арқылы Postman және curl құралдарында бірдей жұмыс процесі көрсетіледі: жөнелтімді тіркеу, оның tracking ақпаратын сұрату және нәтиже қолданбаңызда пайдалануға дайын екенін тексеру.

Your First Tracking API Request a Rest Client Walkthrough with

Мақсат — production жүйесіне орналастыру емес, шағын әрі қайталанатын интеграциялық тест жасау. Сізге API credential және өңдеуге рұқсатыңыз бар tracking number қажет болады. Төмендегі командалар v2.2 endpoint үлгісін пайдаланады; оларды іске қоспас бұрын endpoint нұсқасын және есептік жазбаға қатысты талаптарды 17TRACK API documentation ішінен растаңыз.

Алғашқы сұрауыңыз не орындауы керегін түсініңіз

Жөнелтімді tracking интеграциясында екі бөлек міндет бар: қызметке қай жөнелтімді бақылау керегін хабарлау және сол жөнелтімге қатысты tracking ақпаратын алу. Бұл жұмыс процесінде олар бөлек сұраулар ретінде орындалады. Тіркеу сәлемдеме қозғала бастады дегенді білдірмейді, ал сәтті тіркеу тасымалдаушы оқиғалары бірден қолжетімді болатынына кепілдік бермейді.

Алғашқы тест үшін топтама емес, бір жөнелтімді пайдаланыңыз. Бұл аутентификация қателерін, жарамсыз tracking number мәндерін және жауапты түсіндіруді бөлек талдауды жеңілдетеді. Алғашқы пайдалы нәтиже жай ғана «HTTP 200 алдым» емес. Ол — «API жоспарлаған операциямды қабылдады және жөнелтім деңгейіндегі нәтижені түсіндіре аламын» дегенді білдіреді.

Postman сұрауларды өңдеуге және жауаптарды тексеруге арналған визуалды интерфейс береді. curl сол HTTP алмасуын терминалдан қайталауға мүмкіндік береді. Екеуі де API аутентификация ережелерін, жөнелтім деректерін немесе өңдеу тәртібін өзгертпейді. Сұрауды анығырақ зерттеуге көмектесетін құралды пайдаланыңыз, кейін жұмыс істейтін конфигурацияны екіншісінде қайталаңыз.

Credential, жөнелтім және сұрау деректерін дайындаңыз

Клиенттердің бірін ашпас бұрын мыналарды дайындаңыз:

  • Рұқсаты бар API credential: оны 17TRACK API есептік жазбасын баптау арқылы алыңыз. Consumer tracking session API credential орнына жүрмейді.
  • Нақты tracking number: өзіңізге тиесілі немесе кіруге рұқсатыңыз бар жөнелтімді пайдаланыңыз. Нақты tracking деректерін тексергенде жақында белсенді болған жөнелтім ойдан шығарылған нөмірден пайдалырақ.
  • Белгілі болса, тасымалдаушы: диагностика үшін тасымалдаушы атауын сақтаңыз. Егер сіздің жағдайыңызда carrier identifier қажет болса, болжам жасамай, API documentation ішінде көрсетілген мән мен field пайдаланыңыз.
  • Ағымдағы request contract: API нұсқасын, аутентификация тақырыбын, request schema және есептік жазба шектеулерін растаңыз.
  • Қауіпсіз жұмыс кеңістігі: credential, тұтынушы деректері немесе толық tracking жауаптарын жалпыға ашық репозиторийлерге, скриншоттарға не ортақ қолдау хабарламаларына енгізбеңіз.

Минималды сұрау мысалдарында мына параметрлер қолданылады:

ПараметрМысал конфигурация
Base URLhttps://api.17track.net/track/v2.2
Registration operationPOST /register
Tracking information operationPOST /gettrackinfo
Authentication header17token: YOUR_API_TOKEN
Body formatContent-Type: application/json, жөнелтім объектілерінің JSON array түрі

Tracking number мәндерін string ретінде сақтаңыз. Оны сандық типке түрлендіру бастапқы нөлдерді өшіруі немесе мәнді өзгертуі мүмкін. Төмендегі YOUR_TRACKING_NUMBER placeholder мәнін нақты тест жөнелтіміңізбен ауыстыру керек; бұл жұмыс істейтін үлгі нөмір емес.

Postman ішінде тіркеу сұрауын жасаңыз

1. Шағын тест ортасын жасаңыз

Postman ішінде үш айнымалысы бар environment жасаңыз: base_url, tracking_token және tracking_number. base_url мәнін жоғарыдағы base URL ретінде орнатып, басқа екі айнымалыға credential мен жөнелтім нөмірін енгізіңіз. Сұрауды жібермес бұрын осы environment таңдаңыз.

Token үшін Postman қолжетімді құпияны өңдеу құралдарын пайдаланыңыз және workspace нені бөлісетініне немесе синхрондайтынына назар аударыңыз. Интерфейсте мәнді жасыру оған кім кіре алатынын бақылауды алмастырмайды. Әріптестерге немесе жалпы құжаттамаға арналған collection ішіне толтырылған credential енгізіп экспорттамаңыз.

2. Method, URL және headers параметрлерін баптаңыз

HTTP request жасап, POST таңдаңыз және URL ретінде {{base_url}}/register енгізіңіз. Headers қойындысында мыналарды қосыңыз:

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

Бұл мысалда credential арнайы 17token header ішінде беріледі. Басқа API осы үлгіні пайдаланғаны үшін оны Bearer token конфигурациясымен ауыстырмаңыз. Сондай-ақ мұраға алынған collection параметрлері күтпеген Authorization header қосып қоймағанын тексеріңіз.

3. JSON body қосыңыз

Body ашып, raw таңдаңыз да, JSON белгілеңіз. Мынаны енгізіңіз:

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

Сыртқы квадрат жақшалар маңызды: бұл сұрау бір ғана жөнелтім болса да array пайдаланады. Қос тырнақша қолданыңыз, соңындағы үтірлерді алып тастаңыз және JSON ішіне түсініктемелер қоспаңыз. Егер documentation тасымалдаушыңыз немесе жөнелтіміңіз үшін қосымша ақпарат талап етсе, жібермес бұрын құжатталған field мәндерін қосыңыз.

4. Жіберіп, нәтижені тексеріңіз

Send түймесін басыңыз. Алдымен HTTP response мүлде алынғанын тексеріңіз. DNS ақауы, TLS қатесі, proxy мәселесі немесе timeout — сұраудың жарамсыз екенін түсіндіретін жауаптан бөлек жағдай. Содан кейін response body ішінен операция нәтижесін және жөнелтім деңгейіндегі қабылдау не бас тарту ақпаратын тексеріңіз.

Сұрауды «Register test shipment» атауымен сақтаңыз. HTTP status, API нәтижесі және қате туралы хабарды token көшірмей жазып алыңыз. Тіркеу сәтсіз болса, келесі қадамға өтпей тұрып қатені түзетіңіз. Өзгеріссіз сұрауды қайта-қайта жіберу диагностикаға кедергі келтіреді және есептік жазба ресурстарын жұмсауы мүмкін.

Сұрауды curl арқылы қайталаңыз

Келесі командалар Bash немесе Zsh сияқты POSIX үлгісіндегі shell пайдаланады. PowerShell мен Windows Command Prompt ішінде quotation және айнымалы ережелері өзгеше. PowerShell ішінде қажет болса shell-ге тән command alias орнына curl executable шақыру үшін curl.exe қолданыңыз.

Base URL орнатыңыз және credential мәнін әдеттегі құпияны басқару жұмыс процесі арқылы environment variable ішіне жүктеңіз:

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

Environment variable credential мәнін қайта пайдаланылатын мысалдан бөлек ұстайды, бірақ бұл толық құпияны басқару жүйесі емес. Жергілікті тест кезінде shell history сақтайтын командаға нақты token енгізбеңіз. Автоматтандыруда платформаңыздың secret store құралын пайдаланып, log шығысын шектеңіз.

shipment.json атты файл жасап, placeholder орнына тест tracking number мәнін қойыңыз:

[
  {
    "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'

Бұл response body бөлігін register-response.json файлына сақтап, HTTP status мәнін бөлек шығарады. Connection және жалпы timeout мәндері — жергілікті тест таңдаулары, 17TRACK қызметінің кепілдіктері емес. Сақталған файлды ашып, API нәтижесін тексеріңіз; status жолының өзі жеткіліксіз.

Сервер HTTP error response қайтарса да, curl transfer операциясын сәтті аяқтауы мүмкін. Керісінше, transport қатесі қолдануға жарамды API response алынуына кедергі келтіруі мүмкін. Скрипт жазғанда curl exit status, HTTP status және application-level result мәндерін бөлек сигнал ретінде өңдеңіз.

Жөнелтімнің tracking ақпаратын сұратыңыз

Тіркеу расталғаннан кейін Postman сұрауын көшіріп, URL мәнін {{base_url}}/gettrackinfo етіп өзгертіңіз. POST method, authentication header, content type және жөнелтім body мәндерін сақтаңыз. Дерек алғыңыз келгенде жөнелтімді кездейсоқ қайта тіркеп қоймау үшін оны бөлек сақтаңыз.

Оған сәйкес 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'

Жаңа тіркелген жөнелтім бірден толық оқиғалар тарихын қайтарады деп күтпеңіз. Деректің қолжетімділігі жөнелтімге және қызметтің өңдеуіне байланысты. Ақпарат әлі қолжетімді болмаса, бір нөмірді қайта-қайта тіркеудің немесе тым жиі polling loop іске қосудың орнына құжатталған алу және жаңарту нұсқаулығын орындаңыз.

Жауапты үш қабатта оқыңыз

  1. Transport: клиент қосылып, HTTP response алды ма?
  2. Operation: API сұрауды қабылдады ма және жеке жөнелтім сәтті өңделді ме?
  3. Shipment information: қайтарылған дерек жоспарланған сәлемдемені анықтай ма және оның status немесе event history нақты нені көрсетеді?

Status, carrier және event field мәндерін табу үшін ресми response schema пайдаланыңыз. Нормаланған жөнелтім status пен тасымалдаушының бастапқы event сипаттамасының айырмашылығын сақтаңыз. Сәтті lookup жеткізілгенін дәлелдемейді, ал оқиғалардың болмауы сәлемдеме жоғалды дегенді білдірмейді.

Timestamp сақтағанда берілген timezone немесе offset ақпаратын сақтаңыз. Әртүрлі форматтағы raw date string мәндерін сұрыптап, олар дұрыс хронологиялық ретте деп есептемеңіз. Сондай-ақ қолданба жазбаны алған уақыт пен жөнелтім оқиғасы болған уақытты ажыратыңыз.

Бәрін бірден өзгертпей ақауларды түзетіңіз

  • Жауап жоқ: hostname, network access, proxy параметрлері, TLS конфигурациясы және жергілікті timeout мәнін тексеріңіз. Certificate verification параметрін әдеттегі түзету ретінде өшірмеңіз.
  • Аутентификация қатесі: token белсенді екенін, 17token header бар екенін және таңдалған Postman environment айнымалыны дұрыс шешетінін растаңыз. Кездейсоқ бос орындарды тексеріңіз.
  • Жарамсыз сұрау: API нұсқасын, operation path, POST method, content type және JSON array құрылымын documentation арқылы тексеріңіз.
  • Жөнелтім қабылданбады: жөнелтімге тән қатені оқыңыз. Әрбір rejection жағдайын authentication мәселесі деп қабылдамай, нөмірді және қажет carrier ақпаратын тексеріңіз.
  • Tracking оқиғалары жоқ: тіркеуді және жоспарланған жөнелтім identity мәнін растаңыз. Қайта әрекет етпес бұрын carrier ақпараты қажет пе және жаңартулар қолжетімді ме, тексеріңіз.
  • Postman жұмыс істейді, curl жұмыс істемейді: шешілген URL, нақты headers және body bytes мәндерін салыстырыңыз. Shell quotation мен орнатылмаған environment variable — сұраулардың алшақтауына жиі себеп болатын орындар.

Әр тестте бір ғана айнымалыны өзгертіп, нәтижені қысқаша жазып отырыңыз. Postman console тексерсеңіз немесе curl verbose output пайдалансаңыз, оны құпия дерек деп санаңыз: request headers credential мәндерін ашуы мүмкін. Диагностиканы бөлісер алдында құпиялар мен тұтынушы ақпаратын бүркемелеңіз.

Нұсқаулықтың қашан аяқталғанын біліңіз

Екі клиент те жоспарланған сұрауды жібергенде, тіркеу түсінілгенде, алу операциясы түсіндірілетін нәтиже қайтарғанда және API қатесін жаңа ақпарат жоқ жөнелтімнен ажырата алғанда, алғашқы мағыналы интеграциялық тест аяқталды деп есептеуге болады. HTTP status кодтарының сәйкес келуі ғана екі клиенттің бірдей жұмыс істегенін дәлелдемейді.

Жұмыс процесін қолданбаға көшірмес бұрын credential мәндерін server ішінде сақтаңыз, input мәндерін тексеріңіз және құрылымдалған error handling қолданыңыз. Есептік жазбаңызға қатысты rate limits, batch limits, retry нұсқаулығы және update delivery опцияларын documentation арқылы қараңыз. Timeout-тан кейін тіркеуді ойланбастан қайталау қауіпсіз деп есептемеңіз: клиент response алмаса да, server сұрауды өңдеп қойған болуы мүмкін.

Жарамсыз credential, қате JSON, жарамсыз жөнелтім нөмірі, бұрын тіркелген жөнелтім, қолжетімсіз tracking деректері және network timeout жағдайларына арналған тесттер қосыңыз. Әр жағдай өңделмеген exception немесе тұтынушыға көрсетілетін жаңсақ status емес, әдейі таңдалған қолданба нәтижесіне әкелуі керек.

FAQ

Нақты tracking number жоқ болса, тест жасай аламын ба?

Жарамсыз мән арқылы request-validation әрекетінің бір бөлігін тексеруге болады, бірақ бұл жөнелтімді tracking функциясын растамайды. Нақты оқиғаларды тексеру үшін рұқсатыңыз бар жөнелтімді немесе қызмет ұсынса, құжатталған test fixture пайдаланыңыз. Кездейсоқ үлгі нөмірлері sandbox-қа тиесілі деп есептемеңіз.

HTTP 200 response ішінде неге failure бар?

HTTP status пен application result әртүрлі қабаттарды сипаттайды. Server сұрауды сәтті қабылдап, өңдей отырып, жеке жөнелтімнің қабылданбағанын хабарлауы мүмкін. Тек HTTP status емес, response body мен құжатталған shipment-level result мәнін оқыңыз.

Tracking ақпаратын алу үшін неге POST қолданылады?

Endpoint contract көрсеткен method пайдаланыңыз. Бұл алу мысалы shipment identifier мәндерін POST арқылы JSON request body ішінде қабылдайды. Операция дерек оқитындықтан оны GET-ке өзгерту құжатталған сұрауды сақтамайды.

API token мәнін browser JavaScript ішіне орналастыруым керек пе?

Жеке API credential мәнін көпшілікке жеткізілетін frontend code ішіне енгізбеңіз. Credential қорғайтын, input мәндерін тексеретін және әр пайдаланушы кіре алатын жөнелтім ақпаратын басқаратын рұқсаты бар backend арқылы сұрауларды бағыттаңыз.

Production үшін Postman мен curl екеуі де қажет пе?

Жоқ. Олар тестілеу және диагностика құралдары. Production қолданбаңыз сәйкес HTTP client пайдалана алады. Live token немесе қажетсіз тұтынушы деректерін қоспай, тазартылған Postman request немесе curl command мәнін қайталанатын анықтама ретінде сақтаңыз.

Дереккөздер

  • 17TRACK API documentation — аутентификация, endpoint contract, request field, response interpretation және интеграция талаптарына арналған анықтама.
  • Postman documentation: Send API requests — сұрауды баптау және жауапты тексеру.
  • Postman documentation: Variables — айнымалыға негізделген request конфигурациясы.
  • curl manual — headers, request body, timeout, сақталған response және HTTP status шығарылымына арналған command опциялары.