İlk Tracking API sorğunuz: Postman və Curl ilə Rest Client üzrə bələdçi
İlk izləmə API sorğunuzu göndərmək üçün REST müştərisində endpoint-i, autentifikasiya başlığını və JSON gövdəsini konfiqurasiya edin, sorğunu göndərin və həm HTTP statusunu, həm də cavab gövdəsini yoxlayın. Bu izah eyni iş axınını Postman və curl-də nümayiş etdirmək üçün 17TRACK’s Tracking API-dən istifadə edir: göndərişi qeydiyyata alın, onun izləmə məlumatlarını istəyin və nəticənin tətbiqiniz tərəfindən istifadəyə hazır olub-olmadığını yoxlayın.
Məqsəd istehsal mühitinə yerləşdirmə deyil, kiçik və təkrarlana bilən inteqrasiya testidir. Sizə API məlumatı və emal etməyə icazəniz olan izləmə nömrəsi lazım olacaq. Aşağıdakı əmrlər v2.2 endpoint nümunəsindən istifadə edir; onları işə salmazdan əvvəl endpoint versiyasını və hesaba xas tələbləri 17TRACK API documentation bölməsində təsdiqləyin.
İlk sorğunuzun nə etməli olduğunu anlayın
Göndəriş izləmə inteqrasiyasının iki ayrı məqsədi var: xidmətə hansı göndərişin izlənəcəyini bildirmək və həmin göndərişlə əlaqəli izləmə məlumatlarını əldə etmək. Burada nümayiş etdirilən iş axınında bunlar ayrı sorğulardır. Qeydiyyat bağlamanın artıq hərəkətə başladığı demək deyil və uğurlu qeydiyyat daşıyıcı hadisələrinin dərhal əlçatan olacağına zəmanət vermir.
İlk testiniz üçün paket əvəzinə bir göndərişdən istifadə edin. Bu, autentifikasiya xətalarını, etibarsız izləmə nömrələrini və cavabın şərh edilməsini daha asan təcrid etməyə imkan verir. İlk faydalı mərhələ sadəcə “HTTP 200 aldım” deyil. Bu, “API nəzərdə tutduğum əməliyyatı qəbul etdi və göndəriş səviyyəsindəki nəticəni izah edə bilirəm” deməkdir.
Postman sorğuları redaktə etmək və cavabları yoxlamaq üçün vizual interfeys təqdim edir. curl isə eyni HTTP mübadiləsini terminaldan təkrarlana bilən edir. Bunların heç biri API-nin autentifikasiya qaydalarını, göndəriş məlumatlarını və ya emal davranışını dəyişmir. Sorğunu daha aydın araşdırmağa kömək edən alətdən istifadə edin, sonra işlək konfiqurasiyanı digər alətdə də təkrarlayın.
Məlumatlarınızı, göndərişinizi və sorğu təfərrüatlarını hazırlayın
Hər iki müştərini açmazdan əvvəl aşağıdakıları toplayın:
- Səlahiyyətli API məlumatı: onu 17TRACK API hesabınızın qurulması vasitəsilə əldə edin. İstehlakçı izləmə sessiyası API məlumatını əvəz etmir.
- Həqiqi izləmə nömrəsi: sahib olduğunuz və ya daxil olmaq icazəniz olan göndərişdən istifadə edin. Həqiqi izləmə məlumatlarını test edərkən yaxın zamanda aktiv olmuş göndəriş uydurma nömrədən ümumiyyətlə daha faydalıdır.
- Daşıyıcı, məlumdursa: diaqnostika üçün daşıyıcının adını hazır saxlayın. Sizin halınızda daşıyıcı identifikatoru tələb olunursa, təxmin etmək əvəzinə API sənədlərində müəyyən edilmiş dəyər və sahədən istifadə edin.
- Aktual sorğu müqaviləsi: API versiyasını, autentifikasiya başlığını, sorğu sxemini və hesaba qoyulan məhdudiyyətləri təsdiqləyin.
- Təhlükəsiz iş sahəsi: məlumatları, müştəri detallarını və ya tam izləmə cavablarını açıq repozitorilərə, ekran görüntülərinə və ya paylaşılan dəstək mesajlarına yerləşdirməyin.
Minimal sorğu nümunələri bu parametrlərdən istifadə edir:
| Parametr | Nümunə konfiqurasiya |
|---|---|
| Əsas URL | https://api.17track.net/track/v2.2 |
| Qeydiyyat əməliyyatı | POST /register |
| İzləmə məlumatı əməliyyatı | POST /gettrackinfo |
| Autentifikasiya başlığı | 17token: YOUR_API_TOKEN |
| Gövdə formatı | Content-Type: application/json, göndəriş obyektlərindən ibarət JSON massivi ilə |
İzləmə nömrələrini sətir kimi saxlayın. Onlardan birini ədədi tipə çevirmək başlanğıcdakı sıfırları silə və ya dəyəri başqa şəkildə dəyişə bilər. Aşağıdakı YOUR_TRACKING_NUMBER yer tutucusu faktiki test göndərişinizlə əvəz edilməlidir; bu, işlək nümunə nömrəsi deyil.
Postman-də qeydiyyat sorğusunu yaradın
1. Kiçik test mühiti yaradın
Postman-də üç dəyişənlə mühit yaradın: base_url, tracking_token və tracking_number. base_url dəyişənini yuxarıdakı əsas URL-ə təyin edin və digər dəyişənlərə məlumatınızı və göndəriş nömrənizi daxil edin. Sorğunu göndərməzdən əvvəl həmin mühiti seçin.
Token üçün Postman-in mövcud məxfi məlumatların idarə edilməsi nəzarətlərindən istifadə edin və iş sahənizin nəyi paylaşdığını və ya sinxronlaşdırdığını yoxlayın. Dəyəri interfeysdə gizlətmək ona kimin daxil ola biləcəyinə nəzarəti əvəz etmir. Həmkarlar və ya açıq sənədləşmə üçün nəzərdə tutulmuş kolleksiya ilə doldurulmuş məlumatları ixrac etməyin.
2. Metodu, URL-i və başlıqları konfiqurasiya edin
HTTP sorğusu yaradın, POST seçin və URL kimi {{base_url}}/register daxil edin. Headers bölməsində aşağıdakıları əlavə edin:
17token: {{tracking_token}}
Content-Type: application/json
Bu nümunədə məlumat xüsusi 17token başlığında yerləşdirilməlidir. Başqa API bu nümunədən istifadə edib deyə onu Bearer token konfiqurasiyası ilə əvəz etməyin. Həmçinin irsi kolleksiya parametrlərinin nəzərdə tutulmayan Authorization başlığı əlavə edib-etmədiyini yoxlayın.
3. JSON gövdəsini əlavə edin
Body bölməsini açın, raw seçin və JSON-u seçin. Aşağıdakıları daxil edin:
[
{
"number": "{{tracking_number}}"
}
]
Xarici kvadrat mötərizələr vacibdir: bu sorğu yalnız bir göndərişdən ibarət olsa da massivdən istifadə edir. İkiqat dırnaq işarələrindən istifadə edin, sondakı vergülləri silin və JSON-a şərh əlavə etməyin. Sənədlər daşıyıcınız və ya göndərişiniz üçün əlavə məlumat tələb edirsə, göndərməzdən əvvəl sənədləşdirilmiş sahələri əlavə edin.
4. Göndərin və nəticəni yoxlayın
Send düyməsini basın. Əvvəlcə ümumiyyətlə HTTP cavabı alıb-almadığınızı yoxlayın. DNS xətası, TLS xətası, proksi problemi və ya vaxt aşımı sorğunun etibarsız olduğunu izah edən cavabdan fərqlidir. Sonra əməliyyat nəticəsi və göndəriş səviyyəsində qəbul və ya rədd məlumatları üçün cavab gövdəsini yoxlayın.
Sorğunu “Register test shipment” adı ilə yadda saxlayın. HTTP statusunu, API nəticəsini və tokeni kopyalamadan hər hansı xəta mesajını qeyd edin. Qeydiyyat uğursuz olarsa, davam etməzdən əvvəl bu problemi həll edin. Dəyişdirilməmiş sorğunu dəfələrlə göndərmək diaqnostikanı çətinləşdirir və hesab resurslarını sərf edə bilər.
Sorğunu curl ilə təkrarlayın
Aşağıdakı əmrlər Bash və ya Zsh kimi POSIX tipli shell-dən istifadə edir. PowerShell və Windows Command Prompt fərqli dırnaq və dəyişən qaydalarına malikdir. PowerShell-də shell-ə xas komanda ləqəbi əvəzinə curl icra faylını çağırmaq üçün lazım gəldikdə curl.exe istifadə edin.
Əsas URL-i təyin edin və normal məxfi məlumatların idarə edilməsi iş axınınız vasitəsilə məlumatınızı mühit dəyişəninə yükləyin:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Davam etməzdən əvvəl TRACKING_API_TOKEN-u təhlükəsiz şəkildə təyin edin.
Mühit dəyişəni məlumatı yenidən istifadə edilə bilən nümunədən kənarda saxlayır, lakin tam məxfi məlumat idarəetmə sistemi deyil. Lokal test zamanı real tokeni shell tarixçəsində saxlanacaq komandaya daxil etməkdən çəkinin. Avtomatlaşdırma üçün platformanızın məxfi məlumat anbarından istifadə edin və jurnal çıxışını məhdudlaşdırın.
shipment.json adlı fayl yaradın və yer tutucunu test izləmə nömrənizlə əvəz edin:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]
Qeydiyyat sorğusunu göndərin:
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'
Bu, cavab gövdəsini register-response.json faylında saxlayır və HTTP statusunu ayrıca çap edir. Bağlantı və ümumi vaxt aşımı lokal test seçimləridir, 17TRACK xidmət zəmanətləri deyil. API nəticəsini yoxlamaq üçün saxlanmış faylı açın; yalnız status sətri kifayət deyil.
Server HTTP xətası cavabı qaytarsa belə curl ötürməni uğurla tamamlaya bilər. Əksinə, nəqliyyat xətası istifadəyə yararlı API cavabının gəlməsinə mane ola bilər. Skript yazarkən curl-un çıxış statusunu, HTTP statusunu və tətbiq səviyyəsindəki nəticəni ayrı siqnallar kimi idarə edin.
Göndərişin izləmə məlumatlarını istəyin
Qeydiyyatı təsdiqlədikdən sonra Postman sorğusunu kopyalayın və URL-i {{base_url}}/gettrackinfo olaraq dəyişdirin. POST metodunu, autentifikasiya başlığını, məzmun tipini və göndəriş gövdəsini saxlayın. Məlumat əldə etmək istədiyiniz zaman təsadüfən göndərişi yenidən qeydiyyata almamaq üçün onu ayrıca yadda saxlayın.
Bərabər curl sorğusu belədir:
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'
Yeni qeydiyyatdan keçmiş göndərişin dərhal tam hadisə tarixçəsi qaytaracağını düşünməyin. Məlumatların əlçatanlığı göndərişdən və xidmətin emalından asılıdır. Məlumat hələ əlçatan deyilsə, eyni nömrəni təkrar-təkrar qeydiyyata almaq və ya sıx sorğu dövrü işlətmək əvəzinə sənədləşdirilmiş əldə etmə və yeniləmə təlimatlarına əməl edin.
Cavabı üç səviyyədə oxuyun
- Nəqliyyat: müştəri qoşuldu və HTTP cavabı aldı?
- Əməliyyat: API sorğunu qəbul etdi və fərdi göndəriş uğurlu oldu?
- Göndəriş məlumatı: qaytarılmış məlumat nəzərdə tutulan bağlamanı müəyyən edir və onun statusu və ya hadisə tarixçəsi əslində nəyi göstərir?
Status, daşıyıcı və hadisə sahələrini tapmaq üçün rəsmi cavab sxemindən istifadə edin. Normallaşdırılmış göndəriş statusu ilə daşıyıcının ilkin hadisə təsviri arasındakı fərqi qoruyun. Uğurlu axtarış çatdırılmanın sübutu deyil və hadisələrin olmaması bağlamanın itdiyini göstərmir.
Vaxt möhürlərini saxlayarkən təqdim edilmiş vaxt qurşağı və ya ofset məlumatını qoruyun. Müxtəlif formatlardakı xam tarix sətirlərini çeşidləyib onların düzgün xronoloji ardıcıllığı ifadə etdiyini düşünməyin. Həmçinin tətbiqinizin qeydi əldə etdiyi vaxtı göndəriş hadisəsinin baş verdiyi vaxtdan ayırın.
Hər şeyi eyni anda dəyişmədən problemləri aradan qaldırın
- Cavab yoxdur: host adını, şəbəkə girişini, proksi parametrlərini, TLS konfiqurasiyasını və lokal vaxt aşımını yoxlayın. Sertifikat yoxlamasını adi həll kimi söndürməyin.
- Autentifikasiya xətası: tokenin aktiv olduğunu,
17tokenbaşlığının mövcudluğunu və seçilmiş Postman mühitinin dəyişəni düzgün həll etdiyini təsdiqləyin. Təsadüfi boşluqları yoxlayın. - Etibarsız sorğu: API versiyasını, əməliyyat yolunu, POST metodunu, məzmun tipini və JSON massiv strukturunu sənədlərlə müqayisə edərək yoxlayın.
- Göndəriş rədd edildi: göndərişə xas xətanı oxuyun. Hər rəddi autentifikasiya problemi kimi qəbul etmək əvəzinə nömrəni və tələb olunan daşıyıcı məlumatlarını yoxlayın.
- İzləmə hadisələri yoxdur: qeydiyyatı və nəzərdə tutulan göndəriş identikliyini təsdiqləyin. Yenidən cəhd etməzdən əvvəl daşıyıcı məlumatının lazım olub-olmadığını və yeniləmələrin mövcudluğunu yoxlayın.
- Postman işləyir, curl isə uğursuz olur: həll edilmiş URL-i, faktiki başlıqları və gövdə baytlarını müqayisə edin. Shell dırnaqları və təyin olunmamış mühit dəyişənləri sorğuların fərqlənməsinin ümumi səbəbləridir.
Hər testdə bir dəyişəni dəyişin və nəticənin qısa qeydini saxlayın. Postman konsolunu yoxlayır və ya curl-un ətraflı çıxışından istifadə edirsinizsə, çıxışı həssas məlumat kimi qəbul edin: sorğu başlıqları məlumatları ifşa edə bilər. Diaqnostikanı paylaşmazdan əvvəl məxfi məlumatları və müştəri informasiyasını redaktə edin.
İzahın nə vaxt tamamlandığını bilin
Hər iki müştəri nəzərdə tutulan sorğunu göndərdikdə, qeydiyyat başa düşüldükdə, əldə etmə şərh edilə bilən nəticə qaytardıqda və API xətası ilə yeni məlumatı olmayan göndərişi fərqləndirə bildikdə mənalı ilk inteqrasiya testini tamamlamış olursunuz. Təkcə uyğun HTTP status kodları iki müştərinin eyni davrandığını göstərmir.
İş axınını tətbiqə keçirməzdən əvvəl məlumatları serverdə saxlayın, girişləri yoxlayın və strukturlaşdırılmış xəta idarəetməsindən istifadə edin. Hesabınız üçün sənədləşdirilmiş sürət limitləri, paket limitləri, yenidən cəhd təlimatları və yeniləmələrin çatdırılması seçimləri ilə tanış olun. Vaxt aşımından sonra qeydiyyatı düşünmədən yenidən sınamağın təhlükəsiz olduğunu düşünməyin: müştəriniz cavab almasa da server sorğunu emal etmiş ola bilər.
Etibarsız məlumat, düzgün qurulmamış JSON, etibarsız göndəriş nömrəsi, artıq qeydiyyatdan keçmiş göndəriş, əlçatmaz izləmə məlumatları və şəbəkə vaxt aşımı üçün testlər əlavə edin. Hər hal idarə olunmamış istisna və ya müştəriyə yanıltıcı status əvəzinə məqsədli tətbiq nəticəsinə gətirib çıxarmalıdır.
Tez-tez verilən suallar
Həqiqi izləmə nömrəsi olmadan test edə bilərəm?
Etibarsız dəyərlə bəzi sorğu yoxlaması davranışlarını test edə bilərsiniz, lakin bu, göndəriş izləməsini təsdiqləmir. Həqiqi hadisələri test etmək üçün səlahiyyətli göndərişdən və ya xidmət təqdim edirsə, sənədləşdirilmiş test qurğusundan istifadə edin. İxtiyari nümunə nömrələrinin sandbox-a aid olduğunu düşünməyin.
HTTP 200 cavabında niyə hələ də xəta olur?
HTTP statusu və tətbiq nəticələri müxtəlif səviyyələri təsvir edir. Server sorğunu uğurla qəbul edib emal edə, eyni zamanda fərdi göndərişin rədd edildiyini bildirə bilər. Yalnız HTTP statusunu deyil, cavab gövdəsini və sənədləşdirilmiş göndəriş səviyyəsindəki nəticəni oxuyun.
İzləmə məlumatlarını əldə etmək üçün niyə POST istifadə olunur?
Endpoint müqaviləsində göstərilən metoddan istifadə edin. Bu əldə etmə nümunəsi POST vasitəsilə JSON sorğu gövdəsində göndəriş identifikatorlarını qəbul edir. Əməliyyat məlumat oxuduğu üçün onu GET ilə dəyişdirmək sənədləşdirilmiş sorğunu qoruyub saxlamır.
API tokenini brauzer JavaScript-ində yerləşdirməliyəm?
Şəxsi API məlumatını açıq şəkildə təqdim olunan frontend koduna yerləşdirməyin. Məlumatı qoruyan, girişləri yoxlayan və hər bir istifadəçinin hansı göndəriş məlumatlarına daxil ola biləcəyinə nəzarət edən səlahiyyətli backend vasitəsilə sorğuları yönləndirin.
İstehsal mühiti üçün həm Postman, həm də curl lazımdır?
Xeyr. Bunlar faydalı test və diaqnostika alətləridir. İstehsal tətbiqiniz uyğun HTTP müştərisindən istifadə edə bilər. Canlı token və lazımsız müştəri məlumatları olmadan təmizlənmiş Postman sorğusunu və ya curl əmrini təkrarlana bilən istinad kimi saxlayın.
Mənbələr
- 17TRACK API documentation — autentifikasiya, endpoint müqavilələri, sorğu sahələri, cavabların şərhi və inteqrasiya tələbləri üçün istinad.
- Postman documentation: Send API requests — sorğuların konfiqurasiyası və cavabların yoxlanılması.
- Postman documentation: Variables — dəyişən əsaslı sorğu konfiqurasiyası.
- curl manual — başlıqlar, sorğu gövdələri, vaxt aşımı, saxlanmış cavablar və HTTP status çıxışı üçün komanda seçimləri.


