Bir armatörden API şifreleri nasıl talep edilir?

Bu rehber, denizyolu armatörlerinin (Maersk, CMA CGM, COSCO, Hapag-Lloyd vb.) ve benzeri dış sistemlerin API erişim bilgilerini nasıl talep edeceğinizi ve heyAtlas'a nasıl tanımlayacağınızı adım adım anlatır.

1. Ne zaman gerekir?

heyAtlas'taki navlun sorgulama, konteyner/gemi takibi, tarife çekme ve booking gibi araçlar, firmanız adına armatörün API'sine bağlanır. Bu bağlantı için armatörün size özel verdiği API kimlik bilgileri gerekir. Kimlik bilgisi tanımlı değilse ilgili araçlar çalışmaz ve asistan sizden bağlantı bilgisi ister.

2. Kimden ve nasıl istenir?

• İlk adres, firmanızın armatör nezdindeki müşteri temsilcisi veya satış temsilcisidir.
• Büyük armatörlerin çoğunda talep, temsilci üzerinden entegrasyon/IT ekibine yönlendirilir.
• Talebinizde şunları belirtin: kullanım amacı (ör. navlun sorgu, konteyner takip), istenen ortam (test/üretim) ve firmanızın müşteri kodu.

Kopyalanabilir örnek talep e-postası

Konu: API / Entegrasyon erişimi talebi — [Firma Adı], müşteri no: [XXXX]

Merhaba,

[Firma Adı] olarak operasyonlarımızı dijital asistanımız üzerinden yürütüyoruz. Tarafımıza tahsisli API erişim bilgilerini (kullanıcı adı / API anahtarı, endpoint adresleri, varsa müşteri kodu) paylaşmanızı rica ederiz. Kullanım amacımız: [navlun sorgulama / konteyner takibi / booking]. Öncelikle test ortamı bilgilerini, doğrulamanın ardından üretim (production) bilgilerini talep ediyoruz.

Şifre ve anahtarları e-posta yerine güvenli bir kanal üzerinden iletmenizi rica ederiz.

Teşekkürler.

3. Hangi bilgileri istemelisiniz?

4. Armatöre göre ipuçları

• Self-servis geliştirici portalı olanlar (ör. Maersk, CMA CGM, Hapag-Lloyd): armatörün developer portalına firmanız adına kayıt olup uygulama (app) oluşturarak anahtarınızı kendiniz üretebilirsiniz. Onay süreci birkaç iş günü sürebilir.
• Manuel süreç işletenler: temsilci üzerinden form doldurulur; anahtarlar entegrasyon ekibince iletilir.
• Hangi armatörün hangi kimlik doğrulama türünü (API Key, OAuth2 vb.) kullandığını bilmeniz gerekmez; heyAtlas sistem tanımı doğru yöntemi otomatik uygular. Size düşen, armatörün verdiği bilgileri eksiksiz girmektir.

5. Bilgileri heyAtlas'a girme

1. Portalda Ayarlar → Kimlik Bilgileri ekranını açın (firma yöneticisi yetkisi gerekir).
2. İlgili sistemi (armatörü) seçin ve armatörün verdiği alanları doldurun.
3. Aynı sistem için birden fazla kimlik tanımlayabilir, birini varsayılan yapabilirsiniz (ör. farklı müşteri kodları).
4. Kaydettikten sonra ilgili aracı asistan üzerinden deneyerek bağlantıyı doğrulayın.

Ayrıntı için: Kimlik bilgilerini yönetme ve Sistem bağlantıları.

6. Güvenlik

• Şifre ve anahtarları e-posta gövdesinde düz metin olarak istemekten kaçının; güvenli paylaşım bağlantısı tercih edin.
• heyAtlas, kimlik bilgilerini şifreleyerek saklar; ekran üzerinde düz metin olarak göstermez.
• Sızıntı şüphesinde armatörden anahtarı yenilemesini (rotate) isteyin ve yeni değeri heyAtlas'ta güncelleyin.
• Ayrıntı için: Kimlik bilgileri güvenliği.

7. Sık karşılaşılan sorunlar

• 401 / 403 hatası: Şifre yanlış girilmiş, süresi dolmuş ya da hesap henüz aktive edilmemiş olabilir. Bilgileri yeniden girin; sürerse temsilcinize doğrulatın.
• Test / üretim karışıklığı: Test anahtarı üretim adresinde (veya tersi) çalışmaz. Hangi ortamın bilgisi girildiğini kontrol edin.
• "Erişim verildi" dendi ama çalışmıyor: Bazı armatörlerde API aboneliğinin ürün bazında (ör. yalnız tracking) açılması gerekir; hangi ürünlere abone olunduğunu sorun.
• IP engeli: Armatör IP kısıtı uyguluyorsa heyAtlas'ın çağrı yaptığı IP'nin allowlist'e eklenmesi gerekir; destek ekibimizden IP bilgisini isteyebilirsiniz.

8. Yardım

Süreç ilerlemiyorsa Destek → Taleplerim üzerinden destek talebi açın; hangi armatör için hangi adımda kaldığınızı yazmanız yeterli.