API entegrasyonlu mobil uygulama rehberi

Mobil uygulamanın tek başına çalıştığı dönem büyük ölçüde geride kaldı. Sipariş alan bir uygulama stok bilgisini görmek ister. Satış ekibi müşteri geçmişine erişmek ister. Muhasebe, tahsilatın anında ERP tarafına düşmesini bekler. Kargo durumunun da kullanıcı ekranına birkaç saniye içinde yansıması istenir. İşte tam bu noktada api entegrasyonlu mobil uygulama yaklaşımı devreye girer.

En basit haliyle bu yapı, mobil uygulamanın farklı kurumsal sistemlerle programatik biçimde veri alışverişi yapmasıdır. Uygulama çoğu zaman doğrudan ERP, CRM, ödeme altyapısı ya da kargo servisiyle konuşmaz; arada güvenlik, doğrulama, loglama ve dönüşüm sağlayan bir entegrasyon katmanı yer alır. İyi kurgulanmış bir entegrasyon, ekran açılış süresini 2-3 saniye bandında tutabilir, sipariş çakışmalarını azaltabilir ve manuel veri girişini ciddi ölçüde düşürebilir. Kötü bir tasarım ise bunun tersine yol açar: zaman aşımı, veri tutarsızlığı, başarısız ödeme, yanlış stok ve artan destek yükü.

Buradaki kritik nokta şu: Mobil uygulama geliştirme ile entegrasyon geliştirme aynı iş değildir. Arayüz ne kadar iyi olursa olsun, arka taraftaki veri akışı zayıfsa kullanıcı deneyimi bozulur. Aşağıda, ERP, CRM, ödeme ve kargo sistemleriyle bağlantı kurarken teknik ekiplerin ve karar vericilerin özellikle dikkat etmesi gereken başlıkları ele alıyoruz.

API entegrasyonlu mobil uygulama nedir, nasıl çalışır?

API, iki sistemin belirli kurallar çerçevesinde haberleşmesini sağlar. Mobil uygulama bir sipariş oluşturduğunda, çoğu senaryoda aslında bir HTTP isteği gönderir. Örnek bir akış 5 adımdan oluşabilir: kullanıcı sepeti onaylar, mobil uygulama backend API'ye istek atar, backend ödeme servisinden sonucu alır, ERP'ye siparişi işler, kargo sistemine gönderi kaydı açar. Kullanıcı ekranda tek bir butona basmıştır; arka planda ise birden fazla servis devrededir.

Bu noktada mobil cihazdan kurumsal sistemlere doğrudan bağlanmak çoğu zaman doğru yaklaşım değildir. ERP veya CRM sistemlerinin API'leri dış erişime sınırlı şekilde açılır, hız limiti uygular ya da veri modelini mobil kullanım için uygun biçimde sunmaz. Bu nedenle yaygın mimari, mobil uygulama → özel backend / middleware → üçüncü taraf sistemler hattıdır.

Neden araya bir entegrasyon katmanı konur?

• Güvenlik: API anahtarları ve erişim token'ları mobil uygulamaya gömülmez.
• Veri dönüşümü: ERP'deki karmaşık alanlar mobil kullanım için sadeleştirilir.
• Performans: Sık çağrılan veriler 60 saniye ya da 5 dakika gibi kısa sürelerle cache'lenebilir.
• Hata yönetimi: Kargo servisi yanıt vermese bile sipariş kuyruğa alınabilir.

Basit bir örnek JSON yanıtı şöyle olabilir:

{
  "orderId": "ORD-2026-1042",
  "paymentStatus": "authorized",
  "erpSync": true,
  "shipment": {
    "carrier": "Yurtici",
    "trackingCode": "YK123456789"
  }
}

Mobil tarafta görünen veri sade olabilir; ancak arka planda çok daha karmaşık bir işlem zinciri çalışır.

ERP entegrasyonunda veri modeli ve süreç uyumu kritik

ERP entegrasyonu, en çok hata üreten alanlardan biridir; çünkü mesele yalnızca veri çekmek değildir. Sipariş, stok, fiyat, cari hesap, fatura, depo ve iade süreçleri birlikte ele alınmalıdır. Örneğin bir mobil B2B sipariş uygulamasında kullanıcı 120 kalemlik bir sipariş geçebilir. Uygulama, stokta var görünen ürünü ERP'ye kaydetmeye çalıştığında aynı ürün başka bir kanal tarafından 15 saniye önce tüketilmiş olabilir. Sonuç: stok çakışması.

Bu yüzden ilk yapılması gereken iş, alan eşleştirme dokümanını hazırlamaktır. Hangi mobil alanın ERP'de hangi tabloya ya da servise karşılık geldiği netleşmelidir. "Ürün adı" basit görünür; ancak çoğu ERP'de ürün kodu, varyant kodu, birim tipi, KDV oranı ve depo bazlı stok ayrı alanlardır.

ERP tarafında dikkat edilmesi gerekenler

• Tek yönlü mü çift yönlü mü? Sadece ERP'den veri mi okunacak, yoksa sipariş ve tahsilat da geri mi yazılacak?
• Senkron mu asenkron mu? Siparişin ERP'ye anında düşmesi iş gereği zorunluysa senkron akış gerekir. Ancak ağır işlemler için kuyruk yapısı daha güvenlidir.
• Kimlik alanları: Ürün kodu, müşteri kodu ve sipariş numarası gibi eşsiz alanlar en başta tanımlanmalıdır.
• Zaman damgası: Son güncelleme tarihi tutulmadan delta senkronizasyon sağlıklı çalışmaz.

Gerçek hayatta sık görülen bir senaryo şudur: saha satış ekibi internetin zayıf olduğu bölgede çalışır. Uygulama offline sipariş alır, bağlantı geldiğinde 10 dakika içinde ERP'ye toplu aktarım yapar. Bu tasarım en baştan düşünülmezse aynı sipariş iki kez işlenebilir. Çözüm, her sipariş için idempotency key kullanmak ve ERP yazma işlemini bu anahtarla tekilleştirmektir.

CRM entegrasyonunda müşteri verisi, yetki ve veri kalitesi öne çıkar

CRM entegrasyonu denince çoğu ekip yalnızca müşteri kartı çekmeyi düşünür. Oysa mobil uygulamanın ihtiyacı genellikle daha geniştir: teklif geçmişi, açık fırsatlar, destek kayıtları, temsilci notları, segment bilgisi, izin tercihleri. Özellikle satış odaklı uygulamalarda, kullanıcı ekranında görünen tek bir müşteri kartının arkasında 20'den fazla alan bulunabilir.

Buradaki temel risk veri kalitesidir. CRM sistemlerinde aynı müşterinin birden fazla kayıtla bulunması şaşırtıcı değildir. Mobil uygulama bu kayıtları olduğu gibi taşırsa kullanıcı arama ekranında mükerrer sonuçlarla karşılaşır. Bu da yanlış işlem riskini artırır.

CRM bağlantısında kontrol listesi

• Tekil müşteri tanımı: E-posta mı, telefon mu, müşteri numarası mı ana kimlik olacak?
• Rol bazlı erişim: Her satış temsilcisi tüm müşteri notlarını görmeli mi?
• Kişisel veri işleme: Gereksiz alanlar mobile taşınmamalı, veri minimizasyonu uygulanmalıdır.
• Güncelleme stratejisi: Müşteri notu mobilde girildiyse CRM'ye anında mı, periyodik mi yazılacak?

Örneğin servis ekibine özel bir mobil uygulamada yalnızca son 90 günün kayıtlarını göstermek yeterli olabilir. Tüm müşteri geçmişini her açılışta indirmek hem yavaştır hem de gereksiz veri taşır. Bu noktada sayfalama, filtreleme ve artımlı senkronizasyon ciddi fark yaratır.

Ödeme entegrasyonunda PCI kapsamı, hata senaryoları ve 3D Secure akışı doğru kurulmalı

Ödeme entegrasyonu en hassas başlıklardan biridir; çünkü mesele yalnızca tahsilat değil, aynı zamanda güven ve uyumluluktur. Mobil uygulama kart verisini doğrudan işliyorsa yükümlülükler artar. Çoğu projede daha güvenli yöntem, ödeme servis sağlayıcısının tokenizasyon veya hosted payment page gibi modellerinden yararlanmaktır.

Bir ödeme akışında 4 temel durum sık görülür: başarılı provizyon, başarısız provizyon, kullanıcının işlemi terk etmesi, bankadan gecikmeli sonuç gelmesi. Mobil arayüz, bu durumların hepsini yönetebilmelidir. "Ödeme başarısız" mesajı tek başına yeterli değildir; sipariş oluştu mu, oluşmadı mı, yeniden deneme güvenli mi, bunların kullanıcıya açık biçimde gösterilmesi gerekir.

Ödeme tarafında dikkat edilmesi gerekenler

• İdempotent istekler: Kullanıcı aynı butona iki kez bastığında çift çekim oluşmamalı.
• Webhook doğrulaması: Başarılı ödeme sonucu yalnızca uygulama dönüşüne değil, servis sağlayıcının sunucu bildirimine göre teyit edilmeli.
• Timeout yönetimi: 30 saniyeyi geçen isteklerde belirsiz durumlar için sorgulama uç noktası bulunmalı.
• Test ortamı: Sandbox ile canlı ortam ayarları kesin çizgilerle ayrılmalı.

Özellikle 3D Secure akışında mobil webview, deep link dönüşü ve uygulama yaşam döngüsü iyi test edilmelidir. Android ve iOS tarafında farklı davranışlar görülebilir. En azından başarılı, başarısız, kullanıcı iptali ve ağ kopması senaryoları cihaz üzerinde tekrar edilmelidir.

Kargo entegrasyonunda durum kodları ve operasyon gerçeği birlikte ele alınmalı

Kargo entegrasyonu çoğu projede hafife alınır. Oysa kullanıcı deneyimini doğrudan etkiler. "Kargoda" ifadesi tek bir durum gibi görünse de servis sağlayıcılarda 10'dan fazla alt durum olabilir: oluşturuldu, şubede, dağıtımda, teslim edildi, iade sürecinde gibi. Mobil uygulama bu kodları normalize etmezse kullanıcı, farklı kargo firmalarında tutarsız ekranlarla karşılaşır.

Bir e-ticaret ya da bayi sipariş uygulamasında gönderi etiketi oluşturma, takip kodu alma ve teslimat durumunu güncelleme en yaygın üç işlemdir. Ancak pratikte adres doğrulama, desi bilgisi, çoklu paket, iade kargo ve teslimat istisnaları da gündeme gelir.

Kargo servisleriyle bağlantıda önemli noktalar

• Durum eşleme tablosu: Her kargo firmasının kodları ortak bir sözlüğe çevrilmeli.
• Polling sıklığı: Takip verisi her 10 saniyede bir çekilmez; maliyet ve hız limiti hesaplanır.
• Adres doğrulama: İl, ilçe, posta kodu ve mahalle formatları önceden kontrol edilir.
• Label/PDF yönetimi: Etiket çıktıları mobilde görüntülenecekse dosya boyutu ve erişim süresi planlanır.

Somut bir örnek verelim: Aynı gün 500 gönderi oluşturan bir operasyon düşünün. Her gönderi için anlık sorgu atmak yerine toplu durum güncelleme veya webhook desteği varsa o model tercih edilir. Böylece hem API limiti korunur hem de gereksiz trafik azalır.

Performans, güvenlik ve izlenebilirlik olmadan entegrasyon sürdürülebilir olmaz

Bir entegrasyon projesinin başarı ölçütü yalnızca bağlantının kurulması değildir. Yük altında nasıl davrandığı, hata anında iz bırakıp bırakmadığı ve güvenlik politikalarına uyumu da en az bunun kadar önemlidir. Mobil uygulamanın açılışında 6 farklı servis çağrılıyorsa, her birinin 700-800 milisaniyelik gecikmesi toplam deneyimi hissedilir biçimde kötüleştirebilir. Bu nedenle kritik veriler önceliklendirilir; bazı çağrılar ise arka planda yüklenir.

Teknik açıdan ihmal edilmemesi gereken başlıklar

• Rate limit ve retry: Üçüncü taraf servisler sınırsız çağrı kabul etmez. Geri deneme stratejisi kontrollü olmalı.
• Centralized logging: Sipariş no, müşteri no, istek zamanı ve hata kodu log'lanmalı.
• Monitoring: 5xx hata oranı, ortalama yanıt süresi, başarısız webhook sayısı takip edilmeli.
• Versiyonlama: API v1 ve v2 geçişleri mobil sürüm bağımlılığı yaratmadan yönetilmeli.
• Gizli bilgi yönetimi: API key ve secret değerleri güvenli kasalarda tutulmalı.

Üretim ortamına geçmeden önce en az 1 test matrisi hazırlanması iyi bir pratiktir: cihaz türleri, işletim sistemi sürümleri, ağ koşulları, hata senaryoları ve entegrasyon bağımlılıkları tek tabloda izlenir. Özellikle ödeme ve ERP yazma akışlarında bu tablo projeyi ciddi ölçüde güvence altına alır.

Doğru proje yaklaşımı: önce entegrasyon haritası, sonra ekranlar

Kurumsal mobil projelerde sık yapılan hata, önce ekran tasarlayıp sonra sistemlere bağlanmaya çalışmaktır. Daha sağlıklı yöntem bunun tersidir. Önce hangi sistemlerle hangi veri akışlarının kurulacağı netleştirilir. Ardından senaryolar, hata akışları ve yetki modeli çıkarılır. Son aşamada mobil deneyim bu teknik çerçeveye yerleştirilir.

İyi bir başlangıç için 2-4 haftalık keşif çalışması çoğu projede yüksek değer üretir. Bu sürede API dokümantasyonu incelenir, eksik uç noktalar belirlenir, veri eşleştirme yapılır, test ortamları doğrulanır ve kritik riskler görünür hale gelir. Böylece geliştirme sürecindeki sürprizler azalır.

Kısacası api entegrasyonlu mobil uygulama, yalnızca veri çeken bir mobil ürün değildir; kurumsal süreçlerin cepte güvenli, hızlı ve izlenebilir biçimde çalışmasıdır. ERP, CRM, ödeme ve kargo bağlantıları doğru tasarlandığında mobil uygulama gerçekten operasyonun bir parçası haline gelir. Aksi durumda ise yalnızca güzel görünen ama sahada kırılan bir katman olarak kalır.