API Entegrasyonu ve Sistem Entegrasyonu Nasıl Tasarlanır? Siparişten Muhasebeye Güvenilir Veri Akışı

API entegrasyonu iki uygulamanın veri alışverişi yapmasını sağlar; sistem entegrasyonu ise bu alışverişin iş sonucunu güvenilir biçimde üretmesini sağlar. Bir sipariş API çağrısının 200 OK dönmesi, stok ayrıldığı, sevkiyatın planlandığı ve faturanın oluştuğu anlamına gelmez. Bu sonuçların hangi sistemde, hangi sırayla ve hangi hata davranışıyla oluşacağı ayrıca tasarlanır.

Bu yazıda somut bir B2B senaryosu kullanacağız: müşteri portalda sipariş verir; ERP fiyatı ve ticari koşulları doğrular; depo yönetim sistemi (WMS) stok ayırır; muhasebe sistemi faturayı kaydeder; CRM müşteriye gösterilecek durumu okur. Örnek teknoloji bağımsızdır. REST API, mesaj kuyruğu veya iPaaS seçimi değişebilir; veri sahipliği ve hata semantiği değişmez.

1. API entegrasyonu ile sistem entegrasyonu arasındaki sınır

API entegrasyonu; kimlik doğrulama, istek ve yanıt şeması, durum kodları, zaman aşımı ve sürümleme gibi teknik sözleşmeyi kapsar. Sistem entegrasyonu buna yetkili veri kaynağını, iş akışının durumlarını, tutarlılık hedefini, tekrar işleme politikasını, manuel müdahaleyi ve denetim izini ekler.

Bu ayrım satın alma kararını da etkiler. Bir SaaS ürününde hazır konektör bulunması yalnızca bağlantının mümkün olduğunu gösterir. Konektörün kullandığı alanlar, silme davranışı, hız limiti, geçmiş veri aktarımı ve hata kuyruğu gerçek ihtiyaca göre incelenmelidir.

2. Önce her gerçeğin sahibini belirleyin

Müşteri adı CRM'de, ERP'de ve portalda görünebilir; fakat hepsinin aynı alanı değiştirmesi çatışma üretir. Her veri için tek bir yazma otoritesi ve diğer sistemlerin kullanım biçimi tanımlanmalıdır. Kopya veri kaçınılmaz olabilir; sahipsiz veri kaçınılmaz değildir.

Alan düzeyi sahiplik de gerekebilir. CRM teslimat adresi önerirken ERP vergi kimliğini yönetebilir. Bu durumda ‘müşteri kaydının sahibi kim?’ sorusu yeterli değildir; hangi alanın, hangi olayla ve hangi yönde güncellendiği yazılır.

3. İş akışını HTTP çağrısı değil durum makinesi olarak modelleyin

Sipariş için draft → submitted → accepted → fulfilment_pending → invoiced gibi açık durumlar tanımlayın. integration_failed tek başına yetersizdir: yeniden denenebilir bağlantı hatası, iş kuralı reddi ve sonucu belirsiz yazma aynı müdahaleyi gerektirmez.

• submitted: Portal siparişi kalıcı olarak kaydetti; ERP henüz kabul etmedi.
• accepted: ERP kendi sipariş numarasını verdi; bu numara yerel kayıtla eşlendi.
• fulfilment_pending: WMS stok ayırmayı henüz tamamlamadı.
• verification_required: Uzak sistem çağrısı zaman aşımına uğradı; işlemin uygulanıp uygulanmadığı bilinmiyor.
• rejected: Yeniden denemeyle düzelmeyecek fiyat, yetki veya veri kuralı ihlali var.

Kullanıcı ‘API 504 verdi’ görmek zorunda değildir. ‘Siparişiniz alındı, ERP kaydı doğrulanıyor’ mesajı iş durumunu anlatır. Operasyon paneli ise teknik kodu, son denemeyi, correlation ID'yi ve sorumlu ekibi göstermelidir.

4. API sözleşmesini örnek istekten daha geniş tanımlayın

Bir API sözleşmesi yalnızca URL ve alan listesinden oluşmaz. Zorunlu alanlar, para ve zaman biçimleri, null davranışı, sayfalama, hata gövdesi, hız sınırı, idempotency, webhook imzası, sürüm desteği ve kaldırma takvimi birlikte belgelenir. OpenAPI Specification, insanların ve araçların aynı HTTP arayüzünü anlaması için dil bağımsız bir tanım sunar.

POST /v1/orders HTTP/1.1
Authorization: Bearer <access-token>
Idempotency-Key: ord-01J7YQ4X8T2M
traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
Content-Type: application/json

{
  "external_order_id": "B2B-2026-004817",
  "account_id": "AC-1042",
  "currency": "TRY",
  "lines": [
    {"sku": "P-8841", "quantity": "12.000", "unit": "EA"}
  ],
  "expected_price_version": 34
}

external_order_id iş referansıdır; Idempotency-Key aynı mantıksal yazmanın güvenli tekrarını tanımlar; traceparent dağıtık iz bağlamını taşır. Fiyat sürümü, kullanıcının gördüğü koşullar değiştiyse sunucunun sessizce farklı toplamla sipariş açmasını engeller.

Hata yanıtlarını her endpoint için farklı bir JSON biçimiyle üretmek istemciyi kırılganlaştırır. RFC 9457 Problem Details type, title, status, detail ve instance alanlarıyla makine tarafından okunabilir ortak bir hata modeli tanımlar.

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/price-version-conflict",
  "title": "Price version changed",
  "status": 409,
  "detail": "Expected version 34; current version is 35.",
  "instance": "/integration-attempts/ia_98315",
  "current_price_version": 35
}

5. Senkron ve asenkron adımları iş ihtiyacına göre ayırın

Kullanıcının sipariş numarasını hemen görmesi gerekiyorsa portal kaydı senkron oluşturabilir. ERP, WMS ve muhasebenin tamamını aynı HTTP isteğinde bekletmek ise en yavaş sistemin gecikmesini ve kesintisini kullanıcıya taşır. Yerel kabul ile zincirin tamamlanmasını ayırmak çoğu kurumsal akışta daha dayanıklıdır.

• Senkron: kimlik ve yetki kontrolü, zorunlu alan doğrulama, yerel sipariş kaydı.
• Asenkron: ERP aktarımı, stok ayırma, fatura oluşturma, dış bildirim.
• Kullanıcıya dönen sonuç: iş kimliği, mevcut durum ve durum sorgulama adresi.
• Operasyona sunulan sonuç: her aşamanın deneme sayısı, hata sınıfı ve güvenli müdahale eylemi.

6. Idempotency yalnızca aynı isteği görmezden gelmek değildir

HTTP Semantics RFC 9110, PUT ve DELETE gibi yöntemlerin amaçlanan etkisini idempotent olarak tanımlar; POST otomatik olarak idempotent değildir. Sipariş oluşturma gibi POST işlemlerinde uygulama düzeyinde anahtar gerekir.

Sunucu idempotency anahtarını tenant, işlem türü ve istek gövdesinin kanonik özetiyle birlikte saklar. Aynı anahtar ve aynı içerik geldiğinde önceki durum döndürülür. Aynı anahtarla farklı içerik gelirse 409 Conflict üretilir. Eşzamanlı iki istek için kontrol ve kayıt aynı transaction veya benzersiz kısıt içinde yapılmalıdır; önce sorgulayıp sonra koşulsuz eklemek yarış durumuna açıktır.

UNIQUE (tenant_id, operation_type, idempotency_key)

request_hash = SHA256(canonical_json(request_body))

if key exists and request_hash differs:
    return 409 KEY_REUSED_WITH_DIFFERENT_PAYLOAD
if key exists:
    return stored_business_result
else:
    atomically create order + idempotency record + outbox event

Anahtarın saklama süresi, istemcinin gerçek tekrar penceresinden kısa olmamalıdır. Ödeme, sipariş ve dosya işleme farklı süreler gerektirebilir. Saklama süresi dolduktan sonraki tekrarların nasıl ayırt edileceği iş anahtarlarıyla ayrıca düşünülür.

7. Transactional outbox, veritabanı ile mesajlaşma arasındaki boşluğu kapatır

Siparişi veritabanına kaydedip daha sonra kuyruğa mesaj göndermek iki ayrı işlemdir. Veritabanı commit olur, mesaj gönderilemezse sipariş kalır fakat ERP aktarımı başlamaz. Önce mesaj gönderilip commit başarısız olursa bu kez var olmayan sipariş için olay yayılmış olur.

Transactional outbox yaklaşımında sipariş ve yayımlanacak olay aynı yerel transaction içinde kaydedilir. Ayrı publisher outbox satırını kuyruğa gönderir ve gönderim durumunu işaretler. Publisher çökebileceği için aynı olay birden fazla kez teslim edilebilir; tüketici tarafında inbox/deduplication gerekir.

BEGIN;
INSERT INTO orders (id, status, ...) VALUES ('ord_4817', 'submitted', ...);
INSERT INTO outbox (event_id, aggregate_id, event_type, payload)
VALUES ('evt_9001', 'ord_4817', 'order.submitted.v1', '{...}');
COMMIT;

‘Exactly once’ etiketi tek başına uçtan uca garanti değildir. Kuyruk mesajı bir kez verse bile tüketici veritabanı commit ettikten sonra acknowledgment öncesinde çökebilir. Güvenli hedef; tekrar teslimi beklemek, her yan etkiyi iş kimliğiyle tekilleştirmek ve uzlaştırılabilir kayıt tutmaktır.

8. Hataları tekrar denenebilirlik ve belirsizlik açısından sınıflandırın

Retry bütçesi katmanlar arasında çoğalmamalıdır. API gateway üç, uygulama üç, worker üç kez denerse tek iş olayı 27 uzak çağrı üretebilir. Hangi katmanın retry sahibi olduğu, toplam süre ve maksimum deneme sayısı açık olmalıdır. Circuit breaker arızayı çözmez; başarısız bağımlılığa yeni yük bindirmeyi geçici olarak sınırlar.

9. Güvenlik: entegrasyon hesabına yalnızca gereken yetkiyi verin

Uzun ömürlü ortak API anahtarını kod deposunda tutmak kolay, fakat rotasyonu ve olay incelemesini zorlaştırır. Mümkünse her entegrasyona ayrı istemci kimliği, kısa ömürlü erişim belirteci, hedef API'ye bağlı audience ve dar scope verin. OAuth 2.0 Security Best Current Practice (RFC 9700), token yetkilerinin gereken en düşük kapsam ve kaynak sunucuyla sınırlandırılmasını önerir.

• TLS sertifikasını doğrulayın; doğrulamayı kapatan geçici ayarı üretime taşımayın.
• Secret değerlerini log, hata gövdesi, URL query parametresi veya istemci tarafı koda yazmayın.
• Webhook için imza, zaman damgası ve replay penceresi doğrulayın; ham gövde üzerinde doğrulama yapın.
• Müşteri/tenant kapsamını yalnızca istek gövdesinden almayın; kimlik bağlamıyla eşleştirin.
• Servis hesabı kullanımını ve yetki değişikliklerini denetim izine ekleyin.

10. Şema eşleme ve sürümleme veri kaybının sessiz kaynağıdır

ERP customer_code alanını 12 karakter, CRM 40 karakter kabul ediyorsa kesme kararı teknik ayrıntı değildir. Ondalık hassasiyet, para birimi, saat dilimi, birim, enum değerleri, null ile boş metin farkı ve silme semantiği alan kataloğunda yazılmalıdır.

Yeni alan eklemek çoğu zaman geriye uyumludur; alanın anlamını değiştirmek değildir. Olay adında veya şemada sürüm kullanın, üretici ve tüketici geçiş süresini planlayın. Tüketici bilinmeyen alanları tolere edebilir; bilinmeyen enum değeri karşısında sessizce varsayılan seçmek yanlış iş sonucu oluşturabilir.

Toplu geçmiş veri aktarımını canlı değişiklik akışından ayırın. Backfill çalışırken yeni siparişler geliyorsa kesim zamanı, yüksek su işareti veya change-data-capture sınırı belirlenmelidir. Aksi halde aradaki kayıtlar atlanabilir ya da iki kez uygulanabilir.

11. Gözlemlenebilirlik: teknik metriği iş sonucu ile bağlayın

Her işlemde order_id, external_order_id, integration_attempt_id, event_id ve dağıtık trace kimliği farklı amaçlara hizmet eder. Hepsini tek ‘correlation id’ alanına sıkıştırmak yerine ilişkilerini kaydedin. W3C Trace Context servisler arasında iz bağlamı taşımak için traceparent ve tracestate başlıklarını standartlaştırır.

• Teknik metrikler: istek gecikmesi, timeout oranı, 429/5xx oranı, kuyruk yaşı, retry sayısı.
• İş metrikleri: gönderilen sipariş, ERP tarafından kabul edilen sipariş, stok ayrılan sipariş, faturalanan sipariş.
• Tutarlılık metrikleri: kaynak ve hedef arasında eksik, fazla veya alanları farklı kayıt sayısı.
• Operasyon metrikleri: manuel müdahale yaşı, çözülemeyen kayıt, aynı hatanın tekrar oranı.

Yüksek kardinaliteli sipariş numarasını metrik etiketi yapmak maliyeti ve sorgu yükünü büyütür; bunu log veya trace alanında tutun. OpenTelemetry HTTP semantic conventions düşük kardinaliteli route şablonlarını ve ortak HTTP özniteliklerini tanımlar.

12. Uzlaştırma, entegrasyonun son savunma hattıdır

Gerçek sistemlerde bütün hatalar anında görünmez. Bir webhook kaybolabilir, yönetici ERP'de manuel değişiklik yapabilir veya eski tüketici yeni enum değerini atlayabilir. Bu yüzden periyodik reconciliation işi, beklenen kayıtları iki tarafta karşılaştırmalıdır.

-- Portalda kabul edilmiş fakat 15 dakika içinde ERP eşleşmesi oluşmamış kayıtlar
SELECT o.id, o.external_order_id, o.accepted_at
FROM orders o
LEFT JOIN erp_order_links e ON e.order_id = o.id
WHERE o.status IN ('accepted', 'fulfilment_pending')
  AND e.erp_order_id IS NULL
  AND o.accepted_at < now() - interval '15 minutes';

Karşılaştırma yalnızca satır sayısı değildir. İş anahtarı, toplam tutar, para birimi, satır adedi ve durum gibi kontrol toplamları kullanılabilir. Fark bulunduğunda otomatik düzeltmenin güvenli olup olmadığı belirlenir; finansal bir kaydı sessizce yeniden yazmak yerine inceleme görevi açmak gerekebilir.

13. Yayına çıkmadan önce kanıtlanması gereken senaryolar

• Aynı sipariş eşzamanlı iki kez gönderildiğinde ERP'de kaç kayıt oluşuyor?
• ERP siparişi kaydedip yanıt vermediğinde portal hangi durumu gösteriyor?
• Outbox publisher commit sonrası çöktüğünde olay yeniden yayımlanabiliyor mu?
• Aynı olay tüketiciye iki kez geldiğinde stok veya fatura iki kez değişiyor mu?
• Partner 429 döndürdüğünde Retry-After ve toplam retry bütçesi korunuyor mu?
• Eski tüketici yeni alanı ve yeni enum değerini nasıl ele alıyor?
• Secret rotasyonu kesintisiz yapılabiliyor mu?
• Yedekten dönüş sonrası tamamlanmış dış işlemler tekrar yürütülüyor mu?
• Uzlaştırma işi kasıtlı oluşturulan eksik ve fazla kayıtları buluyor mu?

Test ortamında başarılı bir demo yeterli değildir. Ağ kesintisi, gecikme, bozuk yanıt, kısmi veri, sıra dışı teslim ve yeniden başlatma kontrollü biçimde uygulanmalıdır. Kabul kriteri yalnızca veri geçti mi sorusunu değil, yanlış veri geçmedi mi ve belirsiz sonuç görünür mü sorularını da kapsar.

14. iPaaS, özel entegrasyon servisi veya doğrudan bağlantı

Hazır iPaaS; standart konektör, görsel eşleme ve operasyon paneliyle teslim süresini kısaltabilir. Özel entegrasyon servisi karmaşık iş kuralları, yüksek hacim veya ayrıntılı hata kontrolünde daha uygun olabilir. Uygulamaların birbirini doğrudan çağırması az sayıda basit akışta yeterli olabilir; bağlantı sayısı büyüdükçe sahiplik ve gözlemlenebilirlik dağılır.

15. Üretime geçiş planı

İlk olarak tek bir işlem türünü, örneğin sipariş oluşturmayı gölge modunda çalıştırın. Yeni entegrasyon sonucu üretir fakat yetkili sisteme yazmaz; mevcut akışla sonuçlar karşılaştırılır. Ardından belirli müşteri veya ürün grubuyla kontrollü yazma açılır. Hata oranı, kuyruk yaşı ve uzlaştırma farkı eşiklerin altında kaldığında kapsam genişletilir.

• Rollback koşulunu sayı ile tanımlayın: örneğin beş dakikada %2'den fazla iş kuralı dışı hata.
• Eski ve yeni akış aynı anda yazacaksa çift kayıt korumasını geçişten önce kurun.
• Şema değişikliklerini eski ve yeni sürümün birlikte çalışabileceği sırayla yayınlayın.
• Operasyon ekibine hata durumları, yeniden işleme yetkisi ve iletişim zinciri verin.
• Canlıya çıkıştan sonra ilk uzlaştırmayı planlı bir kontrol olarak çalıştırın.

API ve sistem entegrasyonu tasarımının teslim çıktısı

Sağlam bir entegrasyon projesi endpoint listesinden daha fazlasını teslim eder: veri sahipliği matrisi, OpenAPI sözleşmesi, alan eşleme kataloğu, durum makinesi, idempotency kapsamı, retry bütçesi, hata sınıfları, güvenlik modeli, gözlemlenebilirlik alanları, uzlaştırma sorguları ve geri dönüş planı.

TankDev'in sistem entegrasyonu yaklaşımını, sistem sınırları çalışmasını ve kurumsal yazılım mimarisi rehberini inceleyebilirsiniz. ERP, CRM, muhasebe, depo veya özel API akışınızı bize anlatın; hangi verinin nerede sahiplenileceğini ve hata anında ne olması gerektiğini birlikte netleştirelim.