Bir kargo firmasıyla çalışan bir e-ticaret işletmesi düşünün. Siparişler sitede, gönderiler kargo firmasının panelinde. Her gün biri siparişleri tek tek kopyalıyor, takip numaralarını geri yapıştırıyor. Karar veriliyor: iki sistem birbirine bağlanacak. Kargo firmasının bir API'si var, yazılımcı dokümana bakıyor ve "birkaç uç nokta, iki haftada biter" diyor.
Altı hafta sonra entegrasyon hâlâ canlıda değil. Kod yazıldı ama test hesabı ancak üçüncü haftada geldi, dokümandaki alanların bir kısmı gerçekte başka adla dönüyor, iade gönderileri hiç konuşulmamış ve kimse "bitti" demek için neyin çalışması gerektiğini yazmamış.
Bu tablo istisna değil, kuraldır. Bir API entegrasyonunda kod çoğu zaman işin küçük kısmıdır; geri kalanı iki kurum arasında bilgi, erişim ve karar beklemektir. Aşağıdaki yedi konu, başlamadan netleştiğinde takvimi en çok kısaltanlardır.
1. Doküman gerçekten güncel mi?
Karşı tarafın dokümanı bir başlangıç noktasıdır, sözleşme değil. Sık görülen durumlar: doküman iki sürüm geride kalmıştır, bazı alanlar "isteğe bağlı" yazar ama boş gönderilince istek reddedilir, hata kodlarının yarısı açıklanmamıştır.
Başlamadan önce dokümanın son güncellenme tarihine bakın ve karşı taraftan teknik bir muhatap isteyin. Bir e-posta adresi ya da destek kanalı yetmez; sorulara birkaç gün içinde cevap verebilecek bir kişinin adı gerekir. Bu kişinin olmaması, takvime haftalar ekleyebilecek en büyük tek risktir.
2. Test ortamı var mı, ve ne zaman açılacak?
Pek çok servis bir test ortamı sunar, ama ona erişim bir başvuru, bir sözleşme ya da bir onay sürecinden geçer. Bazılarında hiç test ortamı yoktur; denemeler canlı sistemde, gerçek kayıtlarla yapılır.
Projenin ilk haftasında test hesabının açılmış olması gerektiğini plana yazın. Test ortamı yoksa canlı ortamda nasıl deneme yapılacağını, deneme kayıtlarının nasıl iptal edileceğini ve bunun bir maliyeti olup olmadığını önceden konuşun. Gerçek bir kargo etiketi ya da gerçek bir fatura deneme yaparken kesilmemeli.
3. Canlı erişimi kim, hangi onayla verecek?
Test bittikten sonra canlı anahtarlar gerekir. Bu anahtarları çoğu zaman yazılımcı değil, işletmenin hesap sahibi ya da yöneticisi alır. Bazı servisler canlıya geçmeden önce kendi ekipleriyle bir kontrol yapar, bazıları imzalı bir form ister.
Bu adımın kimde olduğunu ve kaç gün sürdüğünü baştan öğrenin. Anahtarların kimin adına, hangi hesapta duracağını da kararlaştırın: proje bittiğinde erişim işletmede kalmalı, tek bir çalışanın kişisel hesabında değil.
4. Gerçek veriden örnekleriniz var mı?
Dokümandaki örnek istekler hep temizdir. Gerçek veride adres satırı iki yüz karakteri geçer, telefon numarası boşluklu yazılmıştır, ürün adında tırnak işareti vardır, bir siparişte on yedi kalem bulunur. Entegrasyonu uzatan hataların önemli bir kısmı bu farklardan çıkar.
Başlamadan önce kendi sisteminizden son birkaç ayın tipik ve sıra dışı kayıtlarından bir örnek seti çıkarın: en uzun adres, en kalabalık sipariş, yurt dışı müşteri, kampanyalı ürün. İsim, telefon ve adres gibi kişisel bilgileri bu sette maskeleyin; KVKK açısından gerçek müşteri bilgisinin bir test ortamına gitmesi gerekmez. Yazılımcı bu set üzerinde çalışırsa sorunlar canlıda değil, ilk hafta ortaya çıkar.
5. Ters giden akışları kim tarif edecek?
Herkes sipariş verildiğinde ne olacağını bilir. Sipariş iptal edildiğinde, müşteri adresi değiştirdiğinde, gönderi iade geldiğinde ya da karşı sistem bir isteği reddettiğinde ne olacağını ise çoğu zaman kimse yazmamıştır. Bu akışlar sonradan "bu da olmalı" diye eklendiğinde takvim kayar.
Her ana akış için ters giden halleri bir sayfada listeleyin ve her biri için tek cümlelik bir karar yazın. Cevap "şimdilik elle yapılacak" olabilir; önemli olan bunun bilinçli bir karar olması ve ilk sürümün kapsamına neyin girdiğinin belli olmasıdır.
6. Bir hata olduğunda kim, nereden görecek?
Entegrasyon sessiz çalışır; sorun da sessiz çıkar. Karşı sistem bir gece kapanır, bir alan değişir, bir istek zaman aşımına düşer ve kimse fark etmez, ta ki müşteri gönderisinin neden yola çıkmadığını sorana kadar.
Başlamadan kararlaştırılacak üç şey vardır: başarısız istekler nerede kayıt altına alınacak, kim bundan haberdar olacak (e-posta, bir mesajlaşma kanalı ya da bir panel), ve hata giderildikten sonra kayıt nasıl yeniden gönderilecek. Bunlar için sonradan zaman ayırmak, baştan ayırmaktan her zaman daha pahalıdır.
7. "Bitti" ne demek?
Entegrasyon projelerinin en uzun süren kısmı çoğu zaman son yüzde onudur, çünkü bitiş çizgisi hiç çizilmemiştir. Yazılımcı "istekler çalışıyor" der, operasyon ekibi "ama şu durumda olmuyor" der, liste uzar.
Başlamadan önce kabul kriterini yazın: hangi senaryolar hangi verilerle test edilecek, kim test edecek, canlıya geçtikten sonra kaç gün birlikte izlenecek. Bu liste kısa olabilir, ama yazılı olmalı. Yazılı bir bitiş çizgisi, sonradan çıkan her yeni isteğin "kapsam değişikliği" olarak görülmesini ve ayrı planlanmasını sağlar.
Takvimi gerçekçi kurmak
Bu yedi konunun çoğu yazılımcının elinde değildir; işletmenin, karşı tarafın ve bazen bir muhasebecinin ya da operasyon sorumlusunun kararını bekler. Bu yüzden iyi bir entegrasyon planı iki takvim içerir: kodun takvimi ve bekleme noktalarının takvimi. Test hesabı, canlı anahtarlar, örnek veri ve kabul testi tarihleri ayrıca yazıldığında, gecikmenin nerede olduğu ilk günden görünür.
Bağlanacak sistemlerin iki tarafındaki veriyi kimin sahiplendiği ve aynı kaydın iki kez düşmemesi gibi konuları, CRM ile ERP özelinde daha önce ayrıca anlatmıştık; burada odak, projenin takvimini belirleyen sorulardır.
Kısaca
API entegrasyonu çoğu zaman koddan değil, bekleyişten uzar. Başlamadan önce dokümanın güncel olduğunu ve bir teknik muhatabı, test ortamının açılış tarihini, canlı erişimin kimde olduğunu, gerçek veriden bir örnek seti, ters giden akışlar için kararları, hataların nerede görüneceğini ve yazılı bir kabul kriterini netleştirin. Bu yedi konu netleştiğinde takvim, iki haftalık bir tahminle iki aylık bir gerçek arasında kalmaz.
Entegrasyon projelerinde bu listeyi teklif aşamasında birlikte dolduruyor, kodun ve bekleme noktalarının takvimini ayrı ayrı veriyoruz.
Böyle bir proje mi planlıyorsun?
10 adımda planla