ERP API ve Entegrasyon Mimarisi: Geliştirici Rehberi

ERP API nedir ve neden gerekir?

ERP API, dış uygulamaların ERP verisine ve iş mantığına programatik olarak erişmesini sağlayan sözleşmedir. E-ticaret sitesi, mobil saha uygulaması, muhasebe yazılımı, pazaryeri veya BI aracı; siparişi, stoğu, cari hesabı ve faturayı manuel giriş olmadan ERP ile senkron tutar. Doğru tasarlanmış bir API, kopyala-yapıştır hatalarını ve gecikmeli veriyi ortadan kaldırarak tek doğru kaynağı (single source of truth) korur.

Modern ERP ürünlerinin çoğu (Odoo, ERPNext, Logo, Netsis, SAP, Microsoft Dynamics) bir web servisi katmanı sunar. Fark, bu katmanın ne kadar açık, belgeli ve olay tabanlı olduğudur. Bir ERP seçerken API dokümantasyonunun kalitesi, en az fiyat kadar belirleyicidir.

Entegrasyon yöntemleri karşılaştırması

Pratikte hibrit kullanım yaygındır: temel işlemler REST ile senkron çalışır, kritik olaylar webhook ile bildirilir ve gece toplu dosya aktarımı mutabakat için yedek görevi görür.

RESTful API tasarım ilkeleri

• Kaynak adlandırma: Fiil değil isim ve çoğul kullanın: /api/v1/customers, /api/v1/orders/123.
• Versiyonlama: Kırıcı değişiklikler için URL veya başlıkta sürüm tutun (/v1, /v2); eski sürümü bir süre yaşatın.
• HTTP durum kodları: 200/201 başarı, 400 geçersiz istek, 401/403 yetki, 404 bulunamadı, 409 çakışma, 429 hız limiti, 5xx sunucu.
• Sayfalama: Büyük listelerde limit/offset veya cursor tabanlı sayfalama zorunludur.
• Alan filtreleme: ?fields= ve ?updated_since= ile trafik ve gecikme düşürülür.

POST /api/v1/customers
Content-Type: application/json
Authorization: Bearer <access_token>
Idempotency-Key: 6f1c-...-a2

{ "name": "Örnek A.Ş.", "tax_no": "1234567890", "email": "[email protected]" }

201 Created
{ "id": "cust_123456", "created_at": "2026-08-02T09:00:00Z" }

Kimlik doğrulama ve yetkilendirme

Yetkilendirmede en az yetki ilkesi uygulanır: her istemciye yalnızca ihtiyacı olan kaynak ve işlem (okuma/yazma) scope olarak verilir. Muhasebe entegrasyonu stok siparişi oluşturamaz.

Webhook ve olay tabanlı entegrasyon

Sık kullanılan ERP olayları:

• order.created — yeni sipariş oluştu
• invoice.paid — fatura tahsil edildi
• stock.low — stok kritik eşiğin altına düştü
• production.completed — üretim emri tamamlandı

Webhook güvenliği için ERP, gövdeyi (payload) gizli anahtarla imzalar; alıcı HMAC-SHA256imzasını doğrulamadan veriyi işlemez. Ağ kesintilerine karşı ERP başarısız çağrıları yeniden dener; bu yüzden alıcı uç idempotent olmalı ve üstel geri çekilme (exponential backoff) beklenmelidir:

bekleme = min(taban × 2^(deneme−1), üst_sınır) + jitter

Örnek (taban 1 sn, üst sınır 60 sn): 1. deneme 1 sn, 2. deneme 2 sn, 3. deneme 4 sn... rastgele jitter ile eş zamanlı yığılma (thundering herd) önlenir.

Hız limiti, hata yönetimi ve idempotency

• Rate limit: Örn. 100 istek/dakika. Aşımda 429 Too Many Requests ve Retry-After başlığı döner.
• Idempotency-Key: Yazma isteklerinde mükerrer kaydı önler (çift fatura/çift stok hareketi engellenir).
• Yapılandırılmış hata: Hata gövdesinde makine-okur kod ve insan-okur mesaj birlikte döner.
• Loglama ve izleme: Her isteğe correlation-id verilir; hata ayıklama uçtan uca izlenebilir.

Entegrasyon mimarisi desenleri

Bağlantı sayısı arttıkça noktadan noktaya mimari "spagetti"ye döner; sistem sayısı N için olası bağlantı N×(N−1)/2 formülüyle patlar. Bu noktada merkezî bir entegrasyon katmanı (iPaaS veya event bus) bakım maliyetini düşürür.

2026 API eğilimleri

• API-first ERP: Arayüz ile API aynı servisi tüketir; her özellik baştan API üzerinden sunulur.
• Event-driven mimari: Webhook yerini kalıcı olay akışlarına (streaming) bırakıyor.
• AI ajanları için araç (tool) uçları: ERP işlemleri, dil modeli ajanlarının çağırabileceği yapılandırılmış araçlar olarak açılıyor.
• OpenAPI/AsyncAPI standardı: Makine-okur şema, otomatik istemci üretimini yaygınlaştırıyor.

Öneriler ve şartname maddeleri

• ERP seçiminde açık ve versiyonlanmış REST API ile güncel OpenAPI dokümanı şart koşun.
• Kritik olaylar için webhook + HMAC imza ve yeniden deneme politikası talep edin.
• Idempotency-Key desteği ve hız limiti başlıkları sözleşmede yer alsın.
• Kimlik doğrulamada OAuth 2.0 / kısa ömürlü token ve scope bazlı yetki isteyin.
• Vendor lock-in riskine karşı toplu dışa aktarım (export) ve mutabakat uçları zorunlu tutun.

Entegrasyon mimarinizi planlarken güvenlik ve yetkilendirme tarafını ERP güvenliği ve KVKK yazımızla, veri akışını ise ERP-CRM entegrasyonu içeriğiyle birlikte değerlendirin.