API entegrasyonu: Bağlantı kurulunca iş bitmiş sayılır mı?

Web sitesindeki form bir CRM kaydı oluşturuyor. Testte ilk talep sorunsuz geliyor ve entegrasyon tamamlandı sanılıyor. Birkaç gün sonra aynı kişi için iki kayıt oluşuyor, eksik telefon bilgisi bir görevi durduruyor ve bağlantı hatası kimseye görünmüyor. Sorun API’ye bağlanılamaması değildir. Bağlantının gerçek iş koşullarında nasıl davranacağı yeterince tarif edilmemiştir. API entegrasyonu, iki sistem arasında veri göndermek kadar tekrar, hata, yetki ve bakım kararlarını da içerir.

Bu yazıda formdan CRM’e aktarılan kurgusal bir hizmet talebini izleyeceğiz. API, yazılımların tanımlı kurallar üzerinden birbirleriyle iletişim kurmasını sağlayan arayüzdür. Ürüne göre erişim yöntemi ve davranış değişebilir; güncel dokümantasyon ve sözleşme esas alınmalıdır. Buradaki örnekler belirli bir sağlayıcının bütün özelliklerini anlatmaz. Amaç, “veri geldi” kontrolünü daha kapsamlı bir kabul ve işletim planına dönüştürmek, entegrasyonun hangi sorumluluklarla sürdürüleceğini açıkça görmektir.

Önce aktarılacak işi tanımlayın

“Hizmet talebi CRM’e gitsin” cümlesiyle başlayabiliriz. Ardından hangi alanların gerekli olduğunu, ne zaman kayıt açılacağını ve hangi ekibin kullanacağını yazarız. Form eksik bilgiyle gönderilebiliyor mu? Kullanıcı aynı ihtiyaç için tekrar yazarsa yeni talep mi yoksa mevcut kayda ek bilgi mi oluşacak? İş kararı verilmeden yalnızca alan eşleştirmesi yapmak, sistemlerin farklı anlamlarla çalışmasına yol açabilir. Entegrasyonun doğru sonucu teknik ve operasyonel tanımla birlikte belirlenir.

Verinin sahibi de belli olsun. Telefon bilgisi değiştiğinde hangi sistem güncel kabul edilir? CRM çalışanı kaydı düzelttiğinde web tarafında aynı değişiklik gerekir mi? İki yönlü aktarım düşünülüyorsa çakışma kuralları konuşulmalıdır. Her sistemin her alanı değiştirmesi gerekmeyebilir. Bir alanın hangi kaynaktan yönetildiğini belirlemek, sonradan birbirini geri alan güncellemeleri azaltabilir. Bu kararlar entegrasyon belgesinde örneklerle anlatılabilir. Alan adlarının aynı görünmesi, anlamlarının bütünüyle aynı olduğu varsayımını doğurmamalıdır.

Dokümanı gerçek erişimle birlikte inceleyin

Güncel API açıklaması, erişim yetkisi ve uygun test ortamı gereklidir. Bir bağlantı anahtarının bulunması, gereken işlemlerin tümüne izin verildiğini göstermez. Okuma ve yazma ayrı yetkiler taşıyabilir. Test hesabının üretimden hangi yönlerde farklı olduğu öğrenilmelidir. Önceden hazırlanmış bir eklentinin adı da kapsamı açıklamaz; istenen alanları ve davranışları gerçekten desteklediği kontrol edilir. İnceleme, ürün sunumundan çok uygulanacak iş senaryosuna dayanmalıdır.

İstek ve yanıt biçimlerini örnek kayıtlarla inceleyin. Tarih, durum, ülke kodu veya boş alan farklı yorumlanabilir. Bir sistemin zorunlu alanı diğerinde bulunmayabilir. Uygun dönüşüm yapılacaksa kural açık olsun. Yanlış veya eksik verinin nerede durdurulacağı belirlenir. Dış sistemden gelen bilgi de kontrol edilmeden doğru kabul edilmemelidir. Veri kaynağına güvenmek, biçim ve iş kuralı doğrulamasının gereksiz olduğu anlamına gelmez. Hatalı örnekleri test planına dahil etmek bu nedenle yararlıdır.

Aynı işlemin tekrar gelmesini normal bir olasılık sayın

Kullanıcı düğmeye yeniden basabilir, bağlantı yanıtı kaybolabilir veya sistem yeniden deneme yapabilir. Bu durumların her biri mutlaka yeni iş oluşturmalıdır denemez. Aynı gönderimi ayırt etmek için uygulamanın desteklediği yöntem incelenir. İşlem kimliği veya idempotans yaklaşımı bazı arayüzlerde kullanılabilir. Ancak her API’nin aynı davranışı sunduğu varsayılmamalıdır. Sağlayıcının güncel sözleşmesi, anahtarın anlamı ve hangi koşullarda tekrarın nasıl ele alındığı değerlendirilir.

Form örneğinde kullanıcı aynı talebi tekrar gönderdiğinde ne beklendiğini yazın. Kayıt oluşturuldu ama yanıt ulaşmadıysa yeni istek mevcut sonuçla ilişkilendirilebiliyor mu? İçerik değişmişse aynı işlem mi sayılacak? Aynı kişiye ait farklı taleplerin yanlışlıkla birleştirilmesi de sorundur. Tekrar kontrolü yalnızca e-posta adresi benzerliğine indirgenmemelidir. İşin kimliği ile kişinin kimliği farklı kavramlardır. Doğru karar, süreç ve veri modeliyle birlikte verilir. Testte bu ayrımı gösteren örnekler bulunmalıdır.

Hataları tek bir tekrar düğmesine bağlamayın

Eksik veri, yetkisiz erişim ve geçici bağlantı sorunu aynı müdahaleyi gerektirmeyebilir. Hata türü ve API’nin açıklaması dikkate alınır. Bazı durumlarda veri düzeltilmeli, bazılarında erişim kontrol edilmeli, bazılarında uygun beklemeyle yeniden deneme yapılmalıdır. Sonsuz ve hızlı tekrar, sistemi daha güvenilir hâle getirmez; yükü veya karışıklığı artırabilir. Hangi durumda ne olacağı açık bir akışla tanımlanmalıdır. Bilinmeyen hata sessizce yok sayılmamalıdır.

İşlem tamamlanamazsa kaydın durumu görünür olsun. Kullanıcıya ne söylenecek, ekip hangi kuyruğu kontrol edecek, tekrarın sorumlusu kim olacak? “Hata oluştu” kaydı tek başına çözüm yolu sağlamayabilir. Gerekli bağlam güvenli biçimde tutulur. Hassas bilgi veya erişim sırrı günlük dosyasına gereksiz yere yazılmaz. Destek ekibinin sorunu araştırabilmesi için işlemle ilişkilendirilebilen ama kontrolsüz veri çoğaltmayan bir kayıt düzeni gerekir. Gözlemlenebilirlik tasarımın parçası olarak düşünülmelidir.

Bir yanıtın alınması işin tamamlandığını her zaman göstermez

Bazı süreçler isteği kabul edip işi daha sonra tamamlayabilir. Bu durumda kabul ile tamamlanma ayrı durumlardır. Kullanıcıya hangi aşamanın gösterileceği ve sonucun nasıl öğrenileceği belirlenmelidir. Bildirim veya durum sorgusu kullanılacaksa bunların davranışı test edilir. İletişimin teknik olarak başarılı olması, bütün iş adımlarının tamamlandığına dair kanıt sayılmamalıdır. API’nin kendi anlamı ve entegrasyonun iş akışı birlikte okunmalıdır. Böylece yarım kalmış iş tamamlanmış gibi sunulmaz.

Yetkiyi yalnızca bağlantı kurma izni olarak görmeyin

Entegrasyon hangi kayıtları okuyabiliyor, hangilerini değiştirebiliyor? Hesabın kimliğinin doğrulanması, her kayıt üzerinde işlem yapma hakkı olduğu anlamına gelmez. Kullanıcı veya bayi gibi ayrımlar varsa veri erişimi buna göre sınanmalıdır. Gereksiz geniş yetkiyle başlamak sonradan kontrolü zorlaştırabilir. İşi yapmak için gerekli kapsam seçilir ve kullanılan sırlar uygun yöntemle korunur. Bunlar istemciye veya genel paylaşım alanına kontrolsüz biçimde taşınmamalıdır. Uygulama ayrıntıları teknik ekipçe değerlendirilir.

Erişim bilgilerinin değişmesi ve iptali de planlanmalıdır. Bir çalışan ayrıldığında veya sağlayıcı anahtarı yenilediğinde entegrasyon nasıl devam edecek? İşletmenin kendi hesapları üzerinde kontrolü bulunmalıdır. Test ve canlı erişimleri uygun biçimde ayrılır. Kimlik bilgisi değişikliğinin uygulanıp uygulanmadığı doğrulanır. Bu iş yalnızca ilk kurulum sırasında yapılacak bir ayar değildir. Bakım sürecinde hangi ekibin sorumlu olduğu ve gerekli kayıtlara nasıl ulaşacağı anlaşılmalıdır. Aksi hâlde küçük erişim değişikliği görünmeyen hizmet kesintisine dönüşebilir.

Sınırlar ve sürüm değişiklikleri bakım planına girsin

API’nin kullanım koşulları, istek sınırları ve sürüm davranışı güncel dokümantasyon üzerinden incelenmelidir. Burada bütün sağlayıcılara uygulanacak tek sayı yoktur. Uygulamanın beklenen iş hacmi bu koşullarla karşılaştırılır. Ani yoğunlukta ne olacağı ve birikmiş işlerin nasıl işleneceği değerlendirilir. Entegrasyon sadece az sayıda test kaydıyla çalıştı diye bütün kullanım koşullarını karşıladığı varsayılmamalıdır. Gerekli yük ve hata senaryoları projenin ihtiyacına göre seçilir.

Sağlayıcı değişikliklerini kim takip edecek? Bir alanın kaldırılması, zorunlu bilginin değişmesi veya eski sürümün sonlanması entegrasyonu etkileyebilir. Değişiklik duyuruları için sorumlu ve kontrol düzeni belirlenir. Kullanılan sürüm ve bağlantı envanteri tutulabilir. Test ortamında yeni davranış incelenmeden canlı geçiş yapılmaması gerekebilir. Uygun yöntem projenin riskine göre seçilir. Bakım işi teklif ve teslim konuşmasında görünür olursa işletme, bağlantının gelecekte kendiliğinden değişmeden kalacağını varsaymaz.

Kabul testinde yalnızca ilk kaydı göndermeyin

Test planında doğru kayıt, eksik veri, tekrar gönderim, geç yanıt ve yetki sorunu gibi durumlar bulunabilir. Hangi senaryoların gerekli olduğunu iş etkisi belirler. Formdan çıkan bilgi CRM’de doğru alana geldi mi, ilgili ekip görebiliyor mu, hatalı iş kaydı nasıl bulunuyor? Bunlar bütün akışın sorularıdır. Tek bir başarılı istek, kullanıcı deneyimiyle ekip operasyonunun birlikte çalıştığını göstermez. Kabul, iki uç ve aralarındaki istisnalar üzerinden yapılmalıdır.

Test kaydını ve sonucunu tekrar incelenebilir biçimde saklayın. Kullanılan ortam, örnek veri ve beklenen davranış anlaşılır olsun. Bir hata düzeltildikten sonra ilgili senaryo yeniden kontrol edilir. Mümkün ve uygun olan kontroller otomatikleştirilebilir; bütün inceleme tek tür testle sınırlanmak zorunda değildir. İşletme de sonucun kendi sürecine uygunluğunu değerlendirebilmelidir. Teknik ekip “veri ulaştı” derken kullanıcı açısından iş hâlâ bulunamıyorsa kabul beklentisi ortak biçimde netleştirilmelidir.

Canlıya çıkış için sahip ve geri dönüş yolu belirleyin

İlk aktarım döneminde hangi kayıtlar kontrol edilecek, sorun olursa kim haberdar olacak? Yeni bağlantının mevcut işi nasıl etkilediği gözlenir. Gerekirse aktarımı durdurma veya önceki işleyişe dönme planı bulunur. Ancak geri dönüşün veri etkisi de düşünülmelidir; iki sistemde yarım kalmış kayıtlar olabilir. Geçiş yalnızca teknik düğmeye basma işi değildir. İşletmenin günlük operasyonu ve bekleyen işlemleri birlikte ele alınmalıdır. Plan, gerçek hata durumunda kullanılabilecek kadar somut olmalıdır.

Özel Yazılım Projeleri kapsamında entegrasyon ihtiyacını tarif ederken bu davranışları, testleri ve bakım sorumluluklarını birlikte konuşabilirsiniz. Formdan CRM’e tek kayıt gelmesi iyi bir başlangıçtır; tamamlanmış çalışma için hangi koşulun kabul edildiği ve hangisinin açık kaldığı bilinmelidir. Ekip daha sonra hata olduğunda nereden bakacağını, hangi kaydı nasıl takip edeceğini ve hangi değişiklikte yeniden test yapacağını anlayabilmelidir. Entegrasyonun gerçek teslimi, bağlantıyla birlikte bu çalışma bilgisinin de devredilmesidir.

Bir örnek kaydı uçtan uca izleyin

Kabul sırasında aynı örneğe ait form kaydı, aktarım işlemi ve CRM sonucunu birlikte açın. İlk denemede doğru sonuç oluşsun. Ardından yanıtın kullanıcıya ulaşmadığı durum incelensin: işlem tekrarlandığında hangi kayıtla ilişkilendiriliyor? Son olarak zorunlu bir alanı eksik bırakıp işin nerede durduğunu görün. Ekip bu üç durumu izleyebiliyorsa yalnızca bağlantıyı değil farklı sonuçları da konuşabilir. İnceleme sırasında kullanılan kayıtların gerçek müşteri bilgisi taşıması gerekmez. Ama örnek, işletmenin günlük işinde karşılaşacağı alan ve kararları temsil etmelidir.

Sık Sorulan Sorular

API erişimi varsa entegrasyon kolay mı olur?

Erişim önemli bir girdidir ama kapsamı tek başına belirlemez. Veri uyumu, yetkiler, işlem davranışı, hata koşulları ve bakım ihtiyacı incelenmelidir. Hazır bağlantı gereken alanları desteklemeyebilir. Küçük bir teknik değerlendirme veya deneme, belirsizliği azaltabilir. Güncel dokümantasyon ve gerçek kullanım senaryosu birlikte görülmeden süre hakkında kesin beklenti kurmak zor olabilir.

Aynı kayıt neden iki kez oluşabilir?

Yeniden gönderim, yanıt kaybı veya sistemin tekrar denemesi buna katkı verebilir. Uygulamanın aynı işlemi nasıl ayırt edeceği tasarlanmalıdır. Bazı API’lerde idempotans desteği bulunabilir; davranışı güncel açıklamadan kontrol edilir. Kişi benzerliği ile işlem kimliği aynı şey değildir. Aynı müşterinin ayrı taleplerini yanlış birleştirmemek de önemlidir.

Her hata için otomatik tekrar yapılmalı mı?

Hayır. Hatanın türü ve sağlayıcının tanımladığı davranış dikkate alınmalıdır. Eksik veri veya yetki sorunu yalnızca tekrar gönderilerek çözülmeyebilir. Geçici sorunlarda uygun bekleme ve sınırlandırma gerekebilir. Bilinmeyen durumda sorumlu ekibin görebileceği kayıt ve aktarım yolu bulunmalıdır. Sonsuz tekrar yerine kontrollü bir hata akışı tasarlanmalıdır.

Entegrasyon tamamlandıktan sonra bakım gerekir mi?

Sürüm, erişim, veri kapsamı ve iş ihtiyaçları değişebilir. Değişikliklerin takibi ve gerekli testler için sorumluluk belirlenmelidir. Bir kez çalışması gelecekte hiç kontrol gerekmeyeceğini göstermez. Bakım kapsamı baştan konuşulursa işletme hangi işin destek, hangisinin yeni geliştirme olduğunu daha iyi anlayabilir. Bağlantı envanteri bu takibi destekler.

İşletme kabul testine nasıl katılmalı?

Gerçek süreci temsil eden uygun örneklerle beklenen sonucu değerlendirebilir. Kaydın doğru yerde görünmesi, sorumlu ekibin işlem yapabilmesi ve hata durumunun anlaşılması incelenir. Teknik ayrıntının tümünü bilmek gerekmez; iş sonucunun doğru tarif edilmesi önemlidir. Test bulguları geliştirme ekibiyle aynı kayıt üzerinden konuşulursa beklenti farkları daha somut biçimde çözülebilir.