Modern yazılım mimarisinin kalbi API’lerdir. 2026 yılında bir kurumsal web uygulamasının ortalama 12-25 farklı sistemle konuştuğunu görüyoruz; CRM, ERP, muhasebe, banka, e-posta, SMS, ödeme geçidi, kargo, pazaryeri, sosyal medya, analitik, AI servisleri. Tüm bu sistemlerin verimli konuşabilmesi için doğru tasarlanmış API entegrasyonları şarttır. Biz Stark Ajans olarak API entegrasyonu projelerinde ölçeklenebilir, güvenli ve gözlemlenebilir mimariler kuruyoruz. Bu rehberde API entegrasyon sürecini, kullanılan protokolleri, güvenlik katmanlarını ve 2026 best practice’leri detaylıca paylaşıyoruz.

API Çeşitleri: REST, GraphQL, gRPC, Webhook

REST API: HTTP üzerinden kaynak (resource) tabanlı iletişim. GET/POST/PUT/DELETE metodları, JSON yanıtları. Basitlik ve ekosistem desteği nedeniyle pazar lideri. 2026’da hâlâ en çok kullanılan tercih.

GraphQL: İstemci istediği alanları sorgular, sunucu sadece onları döner. Over-fetching/under-fetching sorununu çözer. Mobile uygulamalarda, karmaşık data grafiklerinde ve frontend ekibine esneklik vermek istediğinizde ideal. Apollo, Hasura, Lighthouse PHP gibi araçlarla implementasyon kolaylaşmıştır.

gRPC: Google’ın protocol buffers tabanlı, HTTP/2 üzerinden çalışan ikili protokol. Microservice’ler arasında ultra düşük gecikme ve tip güvenliği sunar. Public API olarak yaygın değil, iç servislerde kritik.

Webhook: Sunucunun belirli olay gerçekleştiğinde hedef URL’ye POST göndermesi. Polling’e alternatif, real-time event stream. Stripe, GitHub, Meta tüm modern platformlar webhook expose eder.

Server-Sent Events (SSE) ve WebSocket: Gerçek zamanlı veri akışı. Bildirim sistemleri, canlı skor, chat uygulamaları için.

API Entegrasyon Sürecinin Aşamaları

Biz her entegrasyonu şu 7 adımda yürütüyoruz: (1) Discovery: Hedef API’nin dokümantasyonunu oku, authentication modelini anla (API key, OAuth 2.0, JWT, HMAC), rate limit sınırlarını not al, sandbox ortamı var mı kontrol et. (2) Mimarî tasarım: Entegrasyon tek yönlü mü çift yönlü mü, senkron mu asenkron mu, retry stratejisi, hata yönetimi. (3) Teknik PoC: 1-2 günlük prototip ile uçlu uca çalıştığını doğrula. (4) Geliştirme: Client kütüphane, model mapping, service layer, queue worker’lar. (5) Test: Unit test, integration test, VCR/WireMock ile mock kayıt/replay. (6) Gözlem ve alerting: Log, metric, Sentry, Slack webhook bildirimleri. (7) Dokümantasyon ve handover: API sözleşmesi, endpoint haritası, hata kataloğu.

Authentication: API Kimlik Doğrulama Katmanları

Hata Yönetimi ve Retry Stratejisi

Gerçek dünyada API’ler düşer, yavaşlar, rate limit’e takılır. Sağlam entegrasyon bu durumları graceful şekilde yönetmelidir. Bizim standart yaklaşımımız: (1) HTTP status code’a göre retry kararı (5xx retry, 4xx retry yok), (2) Exponential backoff (1s, 2s, 4s, 8s, max 60s), (3) Circuit breaker pattern (arka arkaya başarısız çağrı varsa geçici olarak devreyi aç), (4) Dead letter queue başarısız iş kuyruğu için, (5) Idempotency key ile duplicate istek koruması, (6) Timeout (30s default, finansal işlemde daha kısa), (7) Hatalı response’ları detaylı logla (request/response/headers). Bu pratiklerle bir entegrasyon 7×24 kesintisiz çalışabiliyor.

// Laravel - Webhook retry ve idempotency
class PaymentWebhookController extends Controller {
    public function handle(Request $request) {
        // 1. HMAC imzası doğrula
        if (!$this->verifySignature($request)) {
            return response()->json(['error' => 'Invalid signature'], 401);
        }
        // 2. Idempotency kontrolü
        $eventId = $request->input('event_id');
        if (ProcessedEvent::where('event_id', $eventId)->exists()) {
            return response()->json(['status' => 'already_processed']);
        }
        // 3. Queue'ya at, hızlı yanıt dön
        ProcessPaymentEvent::dispatch($request->all());
        ProcessedEvent::create(['event_id' => $eventId]);
        return response()->json(['status' => 'queued']);
    }
}

Rate Limiting ve Throttling

Üçüncü parti API’lerin hemen hepsi rate limit uygular: Meta Graph API 200 call/hour/user, Stripe 100 req/sec, OpenAI dakikada token sınırı. Sizin projenizde rate limit yönetimi için: (1) Çağrı öncesi kota kontrolü, (2) Redis counter ile kendi tarafınızda takip, (3) Sliding window algoritması, (4) 429 Too Many Requests alındığında Retry-After header’ını dinleme, (5) Kritik olmayan çağrıları düşük öncelikli kuyruğa atma, (6) Toplu işlemlerde batch endpoint kullanma (örn: Meta batch API). Kendi API’nizi expose ediyorsanız da rate limiting zorunlu; Laravel throttle middleware veya Redis tabanlı token bucket algoritması.

Webhook Güvenliği

Webhook’lar kimliği doğrulanmadan açık URL’ler gibidir; saldırıya davetiyedir. Mutlak güvenlik adımları: (1) HMAC imzası doğrulama (Stripe, GitHub standart yaklaşımı), (2) IP whitelist (sağlayıcı IP’lerinden gelen), (3) HTTPS zorunlu, (4) Request timestamp kontrolü (5 dakikadan eski retry saldırıları engelle), (5) Idempotency key ile duplicate koruması, (6) Payload boyutu limiti (DoS koruması), (7) Rate limit, (8) Detaylı audit log. Webhook alıcı endpoint’ini production-grade mimariyle kurmak şarttır.

Gözlemlenebilirlik: Log, Metric, Trace

“Entegrasyon çalışmıyor” demek yerine “7 Şubat 14:32’de Stripe API’ye gönderilen 432. ödeme isteği 503 Service Unavailable ile döndü, 15 saniye sonra retry başarılı oldu” diyebilmek profesyonelliğin göstergesidir. Bu seviyede görünürlük için: (1) Structured logging (JSON format, request_id, user_id tagları), (2) Log aggregation (Loki, Elasticsearch, Datadog), (3) Metric collection (Prometheus: latency, error rate, throughput), (4) Distributed tracing (OpenTelemetry, Jaeger), (5) APM (Sentry, New Relic, Datadog APM), (6) Uptime monitoring (UptimeRobot, Betterstack), (7) Slack/PagerDuty alerting. Bu katmanlar SLA taahhüdü verebilmenizi sağlar.

Popüler Entegrasyon Örnekleri ve Özellikleri

• Meta Marketing API: Reklam yönetimi, CAPI (Conversion API), Instant Forms lead pull.
• Google Ads API: Kampanya yönetimi, conversion upload, raporlama.
• iyzico/PayTR: 3D Secure ödeme, abonelik, iade.
• Trendyol/Hepsiburada: Ürün, stok, sipariş, iade senkronizasyonu.
• GİB e-Fatura/e-Arşiv: UBL-TR XML, zorunlu alanlar, mühür.
• Logo/Netsis/Mikro: SQL view, Web Service veya özel ERP API.
• OpenAI/Claude API: Token yönetimi, streaming response, function calling.
• WhatsApp Business API: Mesaj template onayı, webhook, medya upload.
• Aras/Yurtiçi/MNG Kargo: Barkod üretimi, takip, teslim durumu webhook.

2026 API Entegrasyon Maliyetleri

• Basit REST entegrasyon (tek yönlü, az endpoint): 25.000-80.000 TL
• Çift yönlü sync entegrasyonu (ör: ERP-e-ticaret): 120.000-350.000 TL
• Kompleks entegrasyon (çok entegrasyon, queue, retry): 250.000-700.000 TL
• Entegrasyon platformu / integration hub: 500.000-1.500.000 TL
• Aylık bakım (izleme, hata yönetimi): 8.000-40.000 TL

Sıkça Sorulan Sorular

Zapier/Make yeterli mi? Düşük hacim ve basit iş akışlarında evet; yüksek hacim, özel iş mantığı ve finansal işlemde yetersiz kalır.

API dokümantasyonu yoksa ne yaparım? Reverse engineering (network tab analizi) teknik olarak mümkün ama riskli; sağlayıcı ile iletişime geçip resmi doküman istemek şart.

REST mi GraphQL mı seçmeliyim? Public API ve üçüncü parti kullanımı varsa REST; iç uygulama + mobile + esnek frontend gereksinimi varsa GraphQL.

Entegrasyonu bozuldu, ne yaparım? İlk kontrol: üçüncü parti API changelog; ikinci kontrol: rate limit durumu; üçüncü kontrol: authentication geçerlilik. Sentry ve log’lar ilk bakılacak yer.

Stark Ajans API Entegrasyon Hizmetleri

Biz Stark Ajans olarak 200+ farklı API ile entegrasyon geliştirdik. Meta/Google Ads, iyzico/PayTR, Trendyol/Hepsiburada, Logo/Netsis, WhatsApp Business, Shopify/WooCommerce, OpenAI/Claude, Aras/Yurtiçi Kargo, GİB e-Fatura ve daha birçok sistemle kuracağınız entegrasyonlarda güvenli, ölçeklenebilir ve gözlemlenebilir çözümler sunuyoruz.