İlk Tracking API İsteğiniz: Postman ve Curl ile REST İstemcisi Kullanım Rehberi
İlk tracking API isteğinizi yapmak için REST istemcisinde uç noktayı, kimlik doğrulama başlığını ve JSON gövdesini yapılandırın, isteği gönderin ve hem HTTP durumunu hem de yanıt gövdesini inceleyin. Bu kılavuz, aynı iş akışını Postman ve curl'de göstermek için 17TRACK’in Tracking API'sini kullanır: bir gönderiyi kaydedin, gönderinin takip bilgilerini isteyin ve sonucun uygulamanız tarafından kullanılmaya hazır olup olmadığını kontrol edin.
Amaç bir production dağıtımı değil, küçük ve tekrarlanabilir bir entegrasyon testidir. Bir API kimlik bilgisine ve işleme yetkiniz olan bir takip numarasına ihtiyacınız olacaktır. Aşağıdaki komutlar v2.2 uç noktası düzenini kullanır; çalıştırmadan önce uç nokta sürümünü ve hesaba özel gereksinimleri 17TRACK API documentation içinde doğrulayın.
İlk isteğinizin neyi gerçekleştirmesi gerektiğini anlayın
Bir gönderi takip entegrasyonunun iki ayrı amacı vardır: hizmete hangi gönderinin takip edileceğini bildirmek ve bu gönderiyle ilişkili takip bilgilerini almak. Burada gösterilen iş akışında bunlar ayrı isteklerdir. Kayıt işlemi, paketin zaten hareket ettiği anlamına gelmez ve başarılı bir kayıt, taşıyıcı olaylarının hemen kullanılabilir olacağını garanti etmez.
İlk testiniz için toplu işlem yerine tek bir gönderi kullanın. Bu, kimlik doğrulama hatalarını, geçersiz takip numaralarını ve yanıt yorumlamasını daha kolay ayırmanızı sağlar. İlk önemli kilometre taşınız yalnızca “HTTP 200 aldım” değildir. Asıl hedef “API amaçladığım işlemi kabul etti ve gönderi düzeyindeki sonucu açıklayabiliyorum” olmalıdır.
Postman, istekleri düzenlemek ve yanıtları incelemek için görsel bir arayüz sunar. curl ise aynı HTTP alışverişini terminalden tekrarlanabilir hâle getirir. İkisi de API'nin kimlik doğrulama kurallarını, gönderi verilerini veya işleme davranışını değiştirmez. İsteği daha net araştırmanıza yardımcı olan aracı kullanın, ardından çalışan yapılandırmayı diğer araçta yeniden oluşturun.
Kimlik bilgilerinizi, gönderinizi ve istek ayrıntılarını hazırlayın
İstemcilerden herhangi birini açmadan önce aşağıdakileri hazırlayın:
- Yetkili bir API kimlik bilgisi: Bunu 17TRACK API hesap kurulumunuz üzerinden edinin. Tüketici takip oturumu, API kimlik bilgisinin yerine geçmez.
- Gerçek bir takip numarası: Sahip olduğunuz veya erişim izniniz bulunan bir gönderiyi kullanın. Gerçek takip verilerini test ederken yakın zamanda hareket görmüş bir gönderi, uydurma bir numaradan genellikle daha kullanışlıdır.
- Taşıyıcı, biliniyorsa: Teşhis için taşıyıcının adını hazır bulundurun. Durumunuz için bir taşıyıcı tanımlayıcısı gerekiyorsa tahminde bulunmak yerine API belgelerinde tanımlanan değeri ve alanı kullanın.
- Güncel istek sözleşmesi: API sürümünü, kimlik doğrulama başlığını, istek şemasını ve hesap kısıtlamalarını doğrulayın.
- Güvenli bir çalışma alanı: Kimlik bilgilerini, müşteri ayrıntılarını veya eksiksiz takip yanıtlarını herkese açık depolara, ekran görüntülerine ya da paylaşılan destek mesajlarına koymaktan kaçının.
Minimum istek örnekleri şu ayarları kullanır:
| Ayar | Örnek yapılandırma |
|---|---|
| Base URL | https://api.17track.net/track/v2.2 |
| Kayıt işlemi | POST /register |
| Takip bilgileri işlemi | POST /gettrackinfo |
| Kimlik doğrulama başlığı | 17token: YOUR_API_TOKEN |
| Gövde biçimi | Content-Type: application/json ve gönderi nesnelerinden oluşan bir JSON dizisi |
Takip numaralarını dize olarak tutun. Birini sayısal türe dönüştürmek baştaki sıfırların silinmesine veya değerinin başka şekilde değişmesine neden olabilir. Aşağıdaki YOUR_TRACKING_NUMBER yer tutucusu gerçek test gönderinizle değiştirilmelidir; çalışan bir örnek numara değildir.
Postman'de kayıt isteğini oluşturun
1. Küçük bir test ortamı oluşturun
Postman'de base_url, tracking_token ve tracking_number olmak üzere üç değişken içeren bir ortam oluşturun. base_url değerini yukarıdaki temel URL olarak ayarlayın ve diğer değişkenlere kimlik bilginizi ve gönderi numaranızı girin. İsteği göndermeden önce bu ortamı seçin.
Token için Postman'in mevcut gizli bilgi işleme denetimlerini kullanın ve çalışma alanınızın neleri paylaştığını veya senkronize ettiğini kontrol edin. Bir değeri arayüzde gizlemek, ona kimlerin erişebileceğini kontrol etmenin yerine geçmez. İş arkadaşlarına veya herkese açık belgelere yönelik bir koleksiyonu, doldurulmuş kimlik bilgileriyle dışa aktarmayın.
2. Yöntemi, URL'yi ve başlıkları yapılandırın
Bir HTTP isteği oluşturun, POST'u seçin ve URL olarak {{base_url}}/register girin. Headers sekmesine şunları ekleyin:
17token: {{tracking_token}}
Content-Type: application/json
Bu örnekte kimlik bilgisi özel 17token başlığına aittir. Başka bir API bu düzeni kullandı diye bunu Bearer token yapılandırmasıyla değiştirmeyin. Ayrıca devralınan koleksiyon ayarlarının istenmeyen bir Authorization başlığı ekleyip eklemediğini kontrol edin.
3. JSON gövdesini ekleyin
Body'yi açın, raw seçeneğini belirleyin ve JSON'u seçin. Şunu girin:
[
{
"number": "{{tracking_number}}"
}
]
Dış köşeli parantezler önemlidir: Bu istek yalnızca bir gönderi içerse bile bir dizi kullanır. Çift tırnak kullanın, sondaki virgülleri kaldırın ve JSON içine yorum eklemeyin. Belgeler taşıyıcınız veya gönderiniz için ek bilgi gerektiriyorsa göndermeden önce belgelenen alanları ekleyin.
4. Gönderin ve sonucu inceleyin
Send'e tıklayın. Önce herhangi bir HTTP yanıtı alıp almadığınızı kontrol edin. DNS hatası, TLS hatası, proxy sorunu veya zaman aşımı, isteğin geçersiz olduğunu açıklayan bir yanıttan farklıdır. Ardından işlem sonucunu ve gönderi düzeyindeki kabul ya da ret bilgilerini görmek için yanıt gövdesini inceleyin.
İsteği “Register test shipment” adıyla kaydedin. Token'ı kopyalamadan HTTP durumunu, API sonucunu ve hata mesajlarını not edin. Kayıt başarısız olursa devam etmeden önce bu hatayı çözün. Değiştirilmemiş bir isteği tekrar tekrar göndermek teşhisi zorlaştırabilir ve hesap kaynaklarını tüketebilir.
İsteği curl ile yeniden oluşturun
Aşağıdaki komutlar Bash veya Zsh gibi POSIX tarzı bir kabuk kullanır. PowerShell ve Windows Command Prompt farklı tırnak ve değişken kurallarına sahiptir. PowerShell'de, kabuğa özel komut takma adı yerine curl çalıştırılabilir dosyasını çağırmak gerektiğinde curl.exe kullanın.
Temel URL'yi ayarlayın ve normal gizli bilgi işleme iş akışınız üzerinden kimlik bilginizi bir ortam değişkenine yükleyin:
export TRACKING_BASE_URL='https://api.17track.net/track/v2.2'
# Devam etmeden önce TRACKING_API_TOKEN değerini güvenli şekilde ayarlayın.
Ortam değişkeni kimlik bilgisini yeniden kullanılabilir örnekten uzak tutar, ancak eksiksiz bir gizli bilgi yönetimi sistemi değildir. Yerel testlerde gerçek token'ı kabuğunuzun saklayacağı bir komuta yazmaktan kaçının. Otomasyon için platformunuzun gizli bilgi deposunu kullanın ve günlük çıktısını sınırlandırın.
shipment.json adlı bir dosya oluşturun ve yer tutucuyu test takip numaranızla değiştirin:
[
{
"number": "YOUR_TRACKING_NUMBER"
}
]
Kayıt isteğini gönderin:
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 işlem yanıt gövdesini register-response.json dosyasına kaydeder ve HTTP durumunu ayrı olarak yazdırır. Bağlantı ve toplam zaman aşımı değerleri yerel test tercihleridir; 17TRACK hizmet garantileri değildir. API sonucunu incelemek için kaydedilen dosyayı açın; yalnızca durum satırı yeterli değildir.
Sunucu HTTP hata yanıtı döndürse bile curl bir aktarımı başarıyla tamamlayabilir. Buna karşılık bir aktarım hatası, kullanılabilir bir API yanıtının ulaşmasını engelleyebilir. Komut dosyası oluştururken curl çıkış durumunu, HTTP durumunu ve uygulama düzeyindeki sonucu ayrı sinyaller olarak ele alın.
Gönderinin takip bilgilerini isteyin
Kaydı doğruladıktan sonra Postman isteğini çoğaltın ve URL'yi {{base_url}}/gettrackinfo olarak değiştirin. POST yöntemini, kimlik doğrulama başlığını, içerik türünü ve gönderi gövdesini koruyun. Verileri almak istediğinizde gönderiyi yanlışlıkla yeniden kaydetmemek için bunu ayrı kaydedin.
Buna karşılık gelen curl isteği şöyledir:
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 kaydedilmiş bir gönderinin hemen eksiksiz olay geçmişi döndüreceğini varsaymayın. Verilerin kullanılabilirliği gönderiye ve hizmetin işleme sürecine bağlıdır. Bilgiler henüz kullanılabilir değilse aynı numarayı tekrar tekrar kaydetmek veya sıkı bir yoklama döngüsü çalıştırmak yerine belgelenen alma ve güncelleme yönergelerini izleyin.
Yanıtı üç katmanda okuyun
- Aktarım: İstemci bağlandı ve bir HTTP yanıtı aldı mı?
- İşlem: API isteği kabul etti mi ve tekil gönderi başarılı oldu mu?
- Gönderi bilgileri: Dönen veriler amaçlanan paketi tanımlıyor mu ve durum ya da olay geçmişi gerçekte neyi ortaya koyuyor?
Durum, taşıyıcı ve olay alanlarını bulmak için resmi yanıt şemasını kullanın. Normalleştirilmiş gönderi durumu ile taşıyıcının özgün olay açıklaması arasındaki ayrımı koruyun. Başarılı bir sorgulama teslimatın kanıtı değildir ve eksik olaylar bir paketin kaybolduğunun kanıtı değildir.
Zaman damgalarını saklarken sağlanan saat dilimi veya fark bilgilerini koruyun. Farklı biçimlerdeki ham tarih dizelerini sıralamaktan ve doğru kronolojik sırayı temsil ettiklerini varsaymaktan kaçının. Ayrıca uygulamanızın bir kaydı aldığı zaman ile gönderi olayının gerçekleştiği zamanı birbirinden ayırın.
Her şeyi aynı anda değiştirmeden sorun giderin
- Yanıt yok: Ana bilgisayar adını, ağ erişimini, proxy ayarlarını, TLS yapılandırmasını ve yerel zaman aşımını kontrol edin. Sertifika doğrulamasını rutin bir çözüm olarak devre dışı bırakmayın.
- Kimlik doğrulama hatası: Token'ın etkin olduğunu,
17tokenbaşlığının bulunduğunu ve seçilen Postman ortamının değişkeni doğru şekilde çözdüğünü doğrulayın. Yanlışlıkla eklenmiş boşlukları kontrol edin. - Geçersiz istek: API sürümünü, işlem yolunu, POST yöntemini, içerik türünü ve JSON dizi yapısını belgelere göre doğrulayın.
- Gönderi reddedildi: Gönderiye özel hatayı okuyun. Her reddi kimlik doğrulama sorunu olarak değerlendirmek yerine numarayı ve gerekli taşıyıcı bilgilerini kontrol edin.
- Takip olayı yok: Kaydı ve amaçlanan gönderi kimliğini doğrulayın. Yeniden denemeden önce taşıyıcı bilgisinin gerekip gerekmediğini ve güncellemelerin kullanılabilir olup olmadığını kontrol edin.
- Postman çalışıyor ancak curl başarısız: Çözümlenen URL'yi, gerçek başlıkları ve gövte baytlarını karşılaştırın. Kabuk tırnakları ve ayarlanmamış ortam değişkenleri, isteklerin farklılaşabileceği yaygın noktalardır.
Her testte tek bir değişkeni değiştirin ve sonucu kısa bir kayıtla tutun. Postman konsolunu inceliyor veya curl'ün ayrıntılı çıktısını kullanıyorsanız çıktıyı hassas kabul edin: istek başlıkları kimlik bilgilerini açığa çıkarabilir. Teşhis bilgilerini paylaşmadan önce gizli bilgileri ve müşteri verilerini çıkarın.
Kılavuzun ne zaman tamamlandığını bilin
Her iki istemci de amaçlanan isteği gönderdiğinde, kayıt anlaşıldığında, alma işlemi yorumlanabilir bir sonuç döndürdüğünde ve bir API hatası ile yeni bilgisi olmayan bir gönderi arasındaki ayrımı yapabildiğinizde anlamlı bir ilk entegrasyon testini tamamlamış olursunuz. Yalnızca HTTP durum kodlarının eşleşmesi, iki istemcinin aynı şekilde davrandığını kanıtlamaz.
İş akışını bir uygulamaya taşımadan önce kimlik bilgilerini sunucuda tutun, girdileri doğrulayın ve yapılandırılmış hata işleme kullanın. Hesabınız için belgelenen hız limitlerini, toplu işlem limitlerini, yeniden deneme yönergelerini ve güncelleme teslim seçeneklerini inceleyin. Zaman aşımından sonra kaydı düşünmeden yeniden denemenin güvenli olduğunu varsaymayın: istemciniz yanıtı almamış olsa bile sunucu isteği işlemiş olabilir.
Geçersiz kimlik bilgisi, hatalı JSON, geçersiz gönderi numarası, zaten kaydedilmiş gönderi, kullanılamayan takip verileri ve ağ zaman aşımı için testler ekleyin. Her durum, işlenmemiş bir istisna veya müşteriye gösterilen yanıltıcı bir durum yerine bilinçli bir uygulama sonucuna yol açmalıdır.
SSS
Gerçek bir takip numarası olmadan test yapabilir miyim?
Geçersiz bir değerle bazı istek doğrulama davranışlarını test edebilirsiniz, ancak bu gönderi takibini doğrulamaz. Gerçek olayları test etmek için yetkili bir gönderi veya hizmet böyle bir olanak sağlıyorsa belgelenmiş bir test fikstürü kullanın. Rastgele örnek numaraların sandbox'a ait olduğunu varsaymayın.
HTTP 200 yanıtı neden yine de hata içeriyor?
HTTP durumu ve uygulama sonuçları farklı katmanları açıklar. Sunucu bir isteği başarıyla alıp işleyebilirken tek bir gönderinin reddedildiğini bildirebilir. Yalnızca HTTP durumunu değil, yanıt gövdesini ve belgelenen gönderi düzeyindeki sonucu okuyun.
Takip bilgilerini almak için neden POST kullanılıyor?
Uç nokta sözleşmesinde belirtilen yöntemi kullanın. Bu alma örneği, gönderi tanımlayıcılarını POST aracılığıyla JSON istek gövdesinde kabul eder. İşlem veri okuduğu için bunu GET olarak değiştirmek, belgelenen isteği korumaz.
API token'ını tarayıcı JavaScript'ine koymalı mıyım?
Özel bir API kimlik bilgisini herkese açık şekilde sunulan frontend koduna yerleştirmeyin. İstekleri kimlik bilgisini koruyan, girdileri doğrulayan ve her kullanıcının hangi gönderi bilgilerine erişebileceğini denetleyen yetkili bir backend üzerinden yönlendirin.
Production için hem Postman'e hem de curl'e ihtiyacım var mı?
Hayır. Bunlar yararlı test ve teşhis araçlarıdır. Production uygulamanız uygun bir HTTP istemcisi kullanabilir. Canlı token veya gereksiz müşteri verileri içermeyen, temizlenmiş bir Postman isteğini ya da curl komutunu tekrarlanabilir bir referans olarak saklayın.
Kaynaklar
- 17TRACK API documentation — kimlik doğrulama, uç nokta sözleşmeleri, istek alanları, yanıt yorumlama ve entegrasyon gereksinimleri için referans.
- Postman documentation: Send API requests — istek yapılandırması ve yanıt inceleme.
- Postman documentation: Variables — değişken tabanlı istek yapılandırması.
- curl manual — başlıklar, istek gövdeleri, zaman aşımı, kaydedilen yanıtlar ve HTTP durum çıktısı için komut seçenekleri.


