Skip to main content
AnasayfaBlogKılavuzlarEntegrasyonunuzu bozmadan gönderi takibi API anahtarlarını yapılandırma ve yenileme

Entegrasyonunuzu bozmadan gönderi takibi API anahtarlarını yapılandırma ve yenileme

17TRACK

Gönderi takip API anahtarlarını güvenli şekilde yapılandırmak ve döndürmek için kimlik bilgilerini sunucu tarafında bir gizli bilgi yöneticisinde saklayın, bunları kullanan her uygulamayı belirleyin ve eski anahtarı kullanımdan kaldırmadan önce yeni anahtarı test edin. Sağlayıcınız birbiriyle örtüşen kimlik bilgilerini destekliyorsa tüketicileri kademeli olarak taşıyın ve eski anahtarı yalnızca doğrulama sonrasında iptal edin. Yeni anahtarın oluşturulması mevcut anahtarı hemen geçersiz kılıyorsa sıfır kesinti varsaymak yerine kalıcı kuyruklar ve kurtarma kontrolleriyle koordineli bir geçiş planlayın.

Gönderi Takip API Anahtarlarını Kesinti Olmadan Yapılandırma ve Döndürme

Bu kılavuz; e-ticaret platformlarında, sipariş yönetim sistemlerinde, depo yazılımlarında ve müşteri bildirim hizmetlerinde takip entegrasyonlarını sürdüren geliştiriciler ve operasyon ekipleri içindir. Amaç yalnızca kimliği doğrulanmış bir istek göndermek değil; değişiklik boyunca gönderi kayıtlarını, takip güncellemelerini ve sonraki işlemleri korumaktır.

Sağlayıcınızın kimlik bilgilerini nasıl yönettiğini doğrulayın

Üretim yapılandırmasını değiştirmeden önce sağlayıcının kimlik bilgisi yaşam döngüsünü belirleyin. “Regenerate” olarak adlandırılan bir kontrol paneli işlemi, “create another key” işleminden farklı davranabilir. Davranışı düğme etiketinden çıkarsamayın.

  • Kimlik doğrulama biçimi: Gerekli üst bilgiyi veya diğer kimlik doğrulama mekanizmasını, uç nokta sürümünü ve hesap ilişkisini doğrulayın.
  • Örtüşme: İki kimlik bilgisi aynı anda geçerli kalabilir mi? Yeni bir kimlik bilgisi oluşturmak önceki kimlik bilgisini hemen iptal ediyor mu?
  • İzinler: Anahtarların ayrı kapsamları, ortam kısıtlamaları veya erişim kontrolleri olup olmadığını belirleyin. Varsa bu kontrolleri kullanın; mevcut olduklarını varsaymayın.
  • İptal: Bir kimlik bilgisinin nasıl devre dışı bırakılacağını ve dikkate alınması gereken bir yayılma davranışı olup olmadığını doğrulayın.
  • Operasyonel etkiler: Kotaların, kayıtlı gönderilerin ve webhook ayarlarının hesaba, uygulamaya veya tek bir anahtara bağlı olup olmadığını belirleyin.

17TRACK entegrasyonu için resmî Tracking API belgeleri ve Tracking API ürün sayfası ile başlayın. Entegrasyonunuzun kimlik doğrulama sözleşmesini doğrulamak için belgeleri kullanın; döndürme işlemini planlamadan önce hesap kontrolleriniz veya destek aracılığıyla kimlik bilgisi yaşam döngüsünü doğrulayın. Aşağıdaki prosedür, 17TRACK'in belirli bir çift anahtar veya yeniden oluşturma iş akışı sunduğu iddiası değil, operasyonel bir çalıştırma kılavuzudur.

Karar kuralı: Örtüşen anahtarlarla geçişi yalnızca eşzamanlı geçerlilik doğrulanmışsa kullanın. Aksi takdirde döndürmeyi koordineli bir kimlik bilgisi değişimi olarak ele alın. Bir dağıtım stratejisi, sağlayıcının desteklemediği bir örtüşme aralığı oluşturamaz.

Anahtarı sisteminize yaymadan bir kez yapılandırın

Kimlik doğrulamayı sunucuda tutun

Üretim kimlik bilgisini yönetilen bir gizli bilgi deposunda veya eşdeğer kontrollü bir sistemde saklayın. Uygulamanın kimlik bilgisine iş yükü kimliği, dağıtım platformu veya onaylanmış başka bir mekanizma aracılığıyla erişmesini sağlayın. Okuma erişimini buna ihtiyaç duyan iş yükleri ve operatörlerle sınırlandırın.

Anahtarı tarayıcı JavaScript'ine, mobil uygulama paketlerine, kaynak koduna, konteyner görüntülerine veya paylaşılan yapılandırma örneklerine gömmeyin. Müşteriye açık bir takip sayfası, sağlayıcı kimlik bilgisini açığa çıkarmadan takip sağlayıcısında kimlik doğrulaması yapabilen arka ucunuzu çağırmalıdır.

OWASP Secrets Management Cheat Sheet merkezi gizli bilgi yönetimini, kontrollü erişimi, denetlemeyi ve yaşam döngüsü yönetimini destekler. REST Security Cheat Sheet de günlük kaydı ve diğer işlemlerin anahtarları açığa çıkarabileceği URL'lere API anahtarlarının konulmamasını önerir. Sağlayıcının belgelenmiş kimlik doğrulama yöntemini izleyin ve kimlik doğrulama değerlerini istek günlüklerinden ve tanılama dışa aktarımlarından kaldırın.

Ortamları ayırın ve dağıtılan sürümü belirleyin

Sağlayıcı destekliyorsa geliştirme, hazırlık ve üretim için ayrı kimlik bilgileri kullanın. Ayrı kimlik bilgileri veya hesaplar kullanılamıyorsa bu sınırlamayı belgeleyin ve üretim dışı işlerin kontrolsüz üretim yazma işlemleri gerçekleştirmesini engelleyin.

Gizli bilgiye SHIPMENT_TRACKING_API_KEY gibi mantıksal bir yapılandırma başvurusu verin. Gizli bilgi yöneticisi sürümünü veya gizli olmayan bir dağıtım etiketini ayrı olarak kaydedin. Bu etiket, operatörlerin kimlik bilgisini incelemeden veya günlüklemeye gerek kalmadan “Bu çalışan hangi sürümü kullanıyor?” sorusunu yanıtlamasını sağlar.

Uygulamaların güncellemeleri nasıl alacağını açıkça belirleyin. Başlangıçta bir ortam değişkenini okuyan bir işlemin değişen değeri alması için genellikle yeniden başlatılması veya yeniden dağıtılması gerekir. Bağlanmış bir gizli bilgi dosyasının ya da çalışma zamanı aramasının yenileme davranışı farklıdır. Gizli bilgi deposunu güncellemek, çalışan her işlemin yeni değeri benimsediğini kanıtlamaz.

Döndürmeden önce istekleri kurtarılabilir hâle getirin

Takip işlerini sağlayıcıya göndermeden önce kalıcı hâle getirin. Gönderi kaydı için dahili bir işlem tanımlayıcısı, gönderi referansı, işlem durumu ve yeniden deneme geçmişini saklayın. Bu iş yükünü kimlik doğrulamadan ayrı tutun; böylece kuyruktaki işler çalıştırıldıklarında etkin kimlik bilgisini kullanabilir.

API anahtarlarını kuyruk mesajlarına serileştirmeyin. Bu, gecikmiş işleri artık geçersiz bir kimlik bilgisine bağlar ve gizli bilgileri kuyruk depolama alanına, başarısız mesaj kuyruklarına ve hata ayıklama araçlarına yayar.

Yazma işlemleri için yeniden denemeleri etkinleştirmeden önce sağlayıcının yinelenen istekleri ele alma kurallarını belirleyin. Zaman aşımı, kaydın başarısız olduğunu kanıtlamaz: bağlantı kesilmeden önce sağlayıcı isteği kabul etmiş olabilir. Varsa belgelenmiş bir idempotency mekanizması kullanın veya yeniden göndermeden önce gönderinin durumunu uzlaştırın.

Tüketici envanteri ve izleme temeli oluşturun

En kolay gözden kaçan tüketici genellikle ana uygulama değildir. Zamanlanmış içe aktarmaları, kuyruk çalışanlarını, sunucusuz işlevleri, yönetim komut dosyalarını, destek araçlarını, felaket kurtarma dağıtımlarını ve şu anda sıfıra ölçeklenmiş hizmetleri envantere alın.

Her tüketici için sahibini, ortamını, gizli bilgi başvurusunu, yenileme mekanizmasını, çalıştırma zamanlamasını ve dağıtım yöntemini kaydedin. Kimlik bilgilerini bellekte tutabilecek uzun süre çalışan işleri belirleyin. Ayrıca yapılandırma değişikliklerinden sonra eski kimlik doğrulama üst bilgisini koruyabilecek yeniden kullanılabilir HTTP istemcilerini inceleyin.

Geçişten önce aşağıdakiler için bir temel değer belirleyin:

  • Hizmet, ortam, uç nokta ve dağıtım sürümüne göre gruplanmış kimlik doğrulama hataları.
  • Sağlayıcı yanıt gecikmesi, zaman aşımları, hız sınırı yanıtları ve sunucu hataları.
  • Kuyruk derinliği, bekleyen en eski işin yaşı ve başarısız mesaj hacmi.
  • Başarılı gönderi kayıtları ve çözümlenmemiş kayıt denemeleri.
  • Webhook'ların entegrasyonun parçası olması durumunda webhook alma ve işleme durumu.

Entegrasyon sağlığını gönderi hareketinden ayırın. Yeni taşıyıcı olayı olmayan bir paket, API hatasının kanıtı değildir. Döndürme sırasında başarılı kimliği doğrulanmış istekler ve sağlıklı işleme kuyrukları, teslimat durumu değişen gönderi sayısından daha doğrudan sinyallerdir.

Desteklendiğinde örtüşen anahtarlarla döndürün

  1. Etkin anahtarı iptal etmeden yeni anahtarı oluşturun. Eski kimlik bilgisinin geçerli kalmaya devam ettiğini doğrulayın. Yeni kimlik bilgisini ayrı bir gizli bilgi sürümü olarak saklayın ve erişimi uygun şekilde sınırlandırın.
  2. Yeni anahtarı yalıtılmış biçimde doğrulayın. Hedef ortamda belgelenmiş, düşük etkili bir işlem kullanın. Hem HTTP sonucunu hem de yanıt gövdesindeki uygulama düzeyindeki sonucu kontrol edin.
  3. Temsili bir iş akışını test edin. Yalnızca temel bağlantı kontrolünü değil, uygulamanızın gerçekten ihtiyaç duyduğu işlemleri doğrulayın. Kayıt gerekiyorsa yetkili bir test gönderisi kullanın ve olası kota veya faturalandırma etkilerini hesaba katın.
  4. Küçük bir tüketici grubuna dağıtın. Bir çalışan grubunu veya uygulama örneğini yeni anahtara taşıyın; ardından kimlik doğrulamayı, işleme sonuçlarını ve kuyruk davranışını kontrol edin.
  5. Kalan tüm tüketicilere dağıtın. Her hizmet yeniden yüklendiğinde veya yeniden başladığında envanteri güncelleyin. Zamanlanmış görevleri, etkin olmayan iş yüklerini ve kurtarma yapılandırmalarını dahil edin.
  6. Uygun bir doğrulama süresi boyunca gözlemleyin. İlgili çalışan ömrünü, yapılandırma önbelleği davranışını, yeniden deneme gecikmesini ve iş zamanlamasını kapsayın. Benimsemeyi kanıtlayan evrensel bir bekleme süresi yoktur.
  7. Eski anahtarı iptal edin ve yeniden doğrulayın. Eski kimlik bilgilerini kullanan tüketicileri izleyin; ardından eski gizli bilgi başvurularını saklama ve olay müdahalesi gereksinimlerinize göre kaldırın.

Sağlayıcı tarafında anahtar kullanım raporlaması yoksa benimsemeyi doğrulamak için dağıtım kayıtlarını ve uygulamanın bildirdiği gizli bilgi sürümü etiketlerini kullanın. Bu, operasyonel kanıt sağlar ancak eksiksiz bir tüketici envanterinin yerini tutmaz.

Anında değiştirmeyi koordineli bir geçiş olarak ele alın

Yeni bir kimlik bilgisi vermek eski anahtarı hemen geçersiz kılıyorsa, kademeli dağıtım yoluyla kesintisiz kimlik doğrulaması garanti edilemez. Geçişi, işlerin kaybolmak yerine güvenli biçimde geciktirileceği şekilde tasarlayın.

  1. Kimlik bilgisini değiştirmeden önce uygulama dağıtımını, gizli bilgi başvurusunu, operatör erişimini ve kurtarma komutlarını hazırlayın.
  2. Pratik olduğu durumlarda kalıcı depolamaya iş kabul etmeye devam ederken kontrollü bir sınırda giden takip isteklerini duraklatın.
  3. Devam eden istekleri tamamlayın veya hesaba katın. Belirsiz yazma sonuçlarını otomatik olarak başarısız saymak yerine uzlaştırma için işaretleyin.
  4. Sağlayıcı kimlik bilgisini değiştirin, gizli bilgi deposunu güncelleyin ve her tüketiciyi yenileyin.
  5. Tüm bekleyen işleri serbest bırakmadan önce kimlik doğrulama ve iş akışı kontrollerini çalıştırın.
  6. Sağlayıcının hız sınırlarına uyarak ve yinelenen kayıtları kontrol ederek işlemeyi kademeli biçimde sürdürün.

Entegrasyon duraklatılamıyor, işleri koruyamıyor veya kimlik bilgilerini öngörülebilir biçimde yenileyemiyorsa rutin bir döndürme işleminden önce bu zayıflıkları giderin. Ancak olası bir güvenlik ihlalinde geçici kesintiye yol açsa bile containment için derhâl iptal gerekebilir.

API kimlik doğrulamasını webhook güvenliğinden ayrı tutun

Giden API anahtarı ile gelen webhook doğrulama gizli bilgisi farklı amaçlara hizmet eder. Birini döndürmenin diğerini değiştirdiğini veya ikisinin aynı değeri kullandığını varsaymayın. Sağlayıcının belgelenmiş webhook kimlik doğrulama ve teslim davranışını bağımsız olarak izleyin.

Giden kimlik bilgisi geçişi sırasında durdurmak için ayrı bir neden olmadıkça webhook alımını çalışır durumda tutun. Gelen mesajları sağlayıcının özelliklerine göre doğrulayın, mimari izin verdiğinde onaylamadan önce kalıcı olarak kabul edin ve işlemeyi yinelenen teslimatlara dayanıklı hâle getirin.

Başarılı bir kimliği doğrulanmış API çağrısı, webhook teslimatının veya işlemesinin sağlıklı olduğunu kanıtlamaz. İki yolu ayrı ayrı kontrol edin ve sağlayıcının tasarımı gerektirmedikçe aynı bakım işleminde her iki kimlik bilgisini değiştirmekten kaçının.

Yeniden deneme fırtınası oluşturmadan hataları giderin

Belirtiİlk kontrollerGüvenli yanıt
Dağıtımdan sonra kimlik doğrulama hatalarıGizli bilgi sürümü, üst bilgi biçimi, ortam, boşluklar, önbelleğe alınmış istemcilerKörlemesine yeniden denemeleri durdurun; yapılandırmayı düzeltin ve tek bir isteği doğrulayın.
Yalnızca bazı çalışanlar başarısız oluyorEski işlemler, atlanan dağıtımlar, gecikmiş işler, eski gizli bilgi önbellekleriEtkilenen tüketicileri yenileyin ve sürüm etiketlerini karşılaştırın.
Kurtarma sırasında hız sınırlarıBekleyen işlerin serbest bırakılma hızı ve toplam eşzamanlılıkKurtarmayı yavaşlatın ve belgelenmiş yeniden deneme yönlendirmesini izleyin.
Kayıt işlemi zaman aşımına uğruyorSağlayıcının işlemi zaten kabul edip etmediğiTekrar oynatmadan önce uzlaştırın veya belgelenmiş idempotency mekanizmasını kullanın.

HTTP 401 genellikle eksik veya geçersiz kimlik doğrulamayla ilgilidir; 403 ise sunucunun isteği reddettiği anlamına gelir. Sağlayıcıya özgü yanıt gövdeleri nedeni daha kesin açıklayabilir. Her 403'ü süresi dolmuş anahtar olarak sınıflandırmayın veya her başarısız işlemin HTTP hata durumu kullandığını varsaymayın.

Uygun geçici hatalar için geri çekilme ve rastgele gecikme içeren sınırlı yeniden denemeler kullanın. Geçersiz bir kimlik bilgisini tekrar tekrar göndermek onu düzeltmez. Bir operatörü uyarın, işi koruyun ve yapılandırma hatasının kontrolsüz bir istek fırtınasına dönüşmesini önleyin.

Değişiklikten önce geri alma ve tamamlanma ölçütlerini tanımlayın

Örtüşen anahtar döndürmede geri alma, eski kimlik bilgisi hâlâ geçerli ve güvenilirken tüketicileri geçici olarak ona döndürmek anlamına gelebilir. İptalden sonra bu seçenek artık yoktur. Eski anahtarın güvenliği ihlal edilmiş olabileceğini düşünüyorsanız kullanılabilirliği geri kazanmak için onu geri yüklemeyin; başka bir kimlik bilgisi oluşturun ve ilerlemeye devam edin.

Döndürmeyi ancak envanterdeki tüm tüketiciler yeni kimlik bilgisini kullandığında, kimlik doğrulama hataları beklenen temel değerine döndüğünde, kuyruktaki işler toparlandığında, belirsiz yazma işlemleri uzlaştırıldığında ve webhook işleme sağlıklı kaldığında tamamlayın. Anahtar değerini kaydetmeden sahibi, tamamlanma zamanını, dağıtılan gizli bilgi sürümünü ve iptal sonucunu kaydedin.

Sürekli API güvenliği için döndürme zamanlamasını kuruluş politikasına, kimlik bilgilerinin açığa çıkma riskine ve sağlayıcı yeteneklerine göre seçin. Şüpheli sızıntı veya uygunsuz erişim sonrasında bu zamanlamanın dışında döndürün. Tekrarlanabilir ve test edilmiş bir prosedür, entegrasyonun güvenli biçimde destekleyemeyeceği keyfî bir sıklıktan daha kullanışlıdır.

SSS

Takip API anahtarını kesinti olmadan döndürebilir miyim?

Sağlayıcı eşzamanlı kimlik bilgilerini destekliyorsa ve her tüketici iptalden önce geçiş yapabiliyorsa potansiyel olarak evet. Yeniden oluşturma eski anahtarı hemen devre dışı bırakıyorsa giden isteklerde kontrollü bir kesinti planlayın. Kalıcı kuyruklar bu aralıkta işleri koruyabilir ancak sağlayıcı bağlantısını sürekli kullanılabilir hâle getirmez.

Kuyruktaki gönderi işleri API anahtarını içermeli mi?

Hayır. Gönderi işlemini ve işlem meta verilerini saklayın, ardından çalışan işleme aldığında etkin kimlik bilgisini çözümleyin. Bu, gizli bilgiye maruz kalmayı azaltır ve gecikmiş işlerin geçersiz kılınmış bir anahtarı tekrar tekrar kullanmasını önler.

Anahtarı döndürmek kayıtlı gönderileri siler mi?

Her iki sonucu da varsaymayın. Kayıtlı gönderilerin ve ilgili ayarların hesaba, uygulamaya veya kimlik bilgisine bağlı olup olmadığını doğrulayın. Kimlik doğrulama başarısı tek başına yeni anahtarın beklenen gönderi kayıtlarına erişebildiğini kanıtlamaz.

Bir anahtar depoda veya günlükte görünürse ne yapmalıyım?

Potansiyel olarak güvenliği ihlal edilmiş kabul edin. Anahtarı derhâl iptal edin veya değiştirin, mümkün olan yerlerde erişim ve kullanım kayıtlarını inceleyin ve olay müdahalesi sürecinizi izleyin. Görünen değeri kaldırmak yeterli değildir; kopyalar geçmişte, günlük dışa aktarımlarında veya başka sistemlerde kalabilir.

Eski bir zamanlanmış işin hâlâ önceki anahtarı kullandığını nasıl anlayabilirim?

Gizli bilgi başvurusunu, dağıtılan yapılandırmayı ve çalışma zamanı yenileme davranışını kontrol edin. Güvenliyse kontrollü bir çalıştırmayla test edin veya bir sonraki zamanlanmış başlangıcından önce dağıtımını doğrulayın. Sessiz bir kontrol paneli, seyrek kullanılan bir tüketicinin taşındığını kanıtlamaz.

Kaynaklar