2026 API Entegrasyonu Rehberi: Sanal POS, Kargo, ERP ve Webhook Güvenliği Mimarisi

1. Problem: Kopan Senkronizasyonlar, Mükerrer Faturalar ve Güvensiz Webhook Uç Noktaları

Modern işletmelerde müşteri talebi web sitesinden girer, ödeme sanal POS üzerinden geçer, kargo barkodu taşıyıcı API'den alınır, fatura e-Belge entegratörüne düşer ve stok hareketi şirket içi ERP'ye işlenir. Ancak bu bağlantılar aceleyle ve yalnızca "happy path" (her şey yolundayken) düşünülerek kodlandığında üretim ortamında üç ciddi arıza oluşur:

1. Çift İşlem (Duplicate Records): Ödeme webhook'u veya cron görevi ağ gecikmesi yüzünden iki kez tetiklendiğinde aynı siparişe iki fatura kesilmesi veya stokun iki kez düşülmesi.
2. Sessiz Veri Kaybı: Kargo veya muhasebe API'si anlık 502/503 ya da 429 Too Many Requests hatası döndüğünde hatanın yakalanıp kuyruğa alınmaması nedeniyle siparişin arada kaybolması.
3. Doğrulanmamış Webhook Saldırıları: Ödeme başarılı callback adresine imza doğrulaması konmadığında dışarıdan sahte POST isteğiyle ödenmemiş siparişin "onaylı" statüsüne çekilebilmesi.

2. Mimari Yaklaşım: Üretim Ortamına Dayanıklı API ve Middleware Tasarımı

Güvenilir bir entegrasyon katmanı, karşı sistemin her an yavaşlayabileceğini veya geçici hata verebileceğini varsayarak tasarlanır.

A. Webhook Güvenliği: HMAC İmza Doğrulama ve Tekrar Saldırısı (Replay) Koruması

Ödeme sağlayıcılarından (İyzico, PayTR, Stripe) veya kargo servislerinden gelen webhook istekleri işlenmeden önce ham gövde (rawBody) üzerinden kriptografik olarak doğrulanmalıdır:

import crypto from "node:crypto";

export function verifyWebhookSignature(
  rawBody: string,
  receivedSignature: string,
  webhookSecret: string
): boolean {
  if (!receivedSignature || !webhookSecret) return false;

  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(rawBody, "utf8")
    .digest("hex");

  const expectedBuf = Buffer.from(expected, "utf8");
  const receivedBuf = Buffer.from(receivedSignature, "utf8");

  if (expectedBuf.length !== receivedBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, receivedBuf);
}

B. Exponential Backoff, Jitter ve Rate Limit (429) Yönetimi

Karşı API geçici olarak meşgul olduğunda hemen vazgeçmek yerine, 4xx istemci hataları (yeniden denemekle düzelmez) ile 429/5xx/ağ hatalarını ayırmak gerekir:

interface RetryOptions {
  maxAttempts: number;
  baseDelayMs: number;
  timeoutMs: number;
}

export async function fetchWithResilience(
  url: string,
  init: RequestInit,
  opts: RetryOptions = { maxAttempts: 4, baseDelayMs: 500, timeoutMs: 8000 }
): Promise<Response> {
  let lastError: unknown;

  for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);

    try {
      const res = await fetch(url, { ...init, signal: controller.signal });
      clearTimeout(timer);

      if (res.ok) return res;

      // 400, 401, 403, 404, 422 gibi kalıcı hatalarda yeniden deneme yapma
      if (res.status >= 400 && res.status < 500 && res.status !== 429) {
        return res;
      }

      if (attempt === opts.maxAttempts) return res;

      const retryAfterSec = Number(res.headers.get("Retry-After"));
      const backoff = Number.isFinite(retryAfterSec) && retryAfterSec > 0
        ? retryAfterSec * 1000
        : opts.baseDelayMs * Math.pow(2, attempt - 1) + Math.floor(Math.random() * 250);

      await new Promise((r) => setTimeout(r, backoff));
    } catch (err) {
      clearTimeout(timer);
      lastError = err;
      if (attempt === opts.maxAttempts) throw err;

      const delay = opts.baseDelayMs * Math.pow(2, attempt - 1) + Math.floor(Math.random() * 250);
      await new Promise((r) => setTimeout(r, delay));
    }
  }

  throw lastError;
}

C. Idempotency (Tekillik) ve Veri Maskeleme Disiplini

• Ödeme ve Sipariş Aktarımı: Her yazma isteği veritabanında benzersiz kısıta (UNIQUE(provider, external_event_id)) ve Idempotency-Key başlığına bağlanır. Örnek bir kargo/sipariş payload'ı oluşturulurken telefon ('05XXXXXXXXX') veya müşteri adı ('Örnek Müşteri') gibi alanlar şema doğrulamasından (Zod/JSON Schema) geçirilir.
• PII / Gizli Bilgi Hijyeni: Loglarda Authorization başlıkları, API anahtarları, kart tokenları ve T.C. kimlik numaraları asla düz metin olarak saklanmaz; her işlem tekil bir correlation_id ile takip edilir.
• Dead Letter Queue (DLQ) ve Uyarı Sistemi: Maksimum deneme sonrasında hâlâ iletilemeyen ERP veya fatura kayıtları veritabanında failed kuyruğuna alınır ve yetkili ekibe bildirim düşülerek tek tıkla yeniden tetiklenebilir hale getirilir.

3. Süre ve Bütçe Aralığı (2026)

API entegrasyonu maliyeti bağlanacak sistem sayısına (Sanal POS, kargo, CRM, e-Fatura, muhasebe/ERP) ve veri yönüne (tek yönlü vs. çift yönlü gerçek zamanlı senkron) göre belirlenir:

4. Sık Sorulan Sorular

Bir API entegrasyonunda idempotency (tekillik) neden hayati önem taşır?

Ağ kesintisi veya zaman aşımı nedeniyle aynı sipariş ya da ödeme isteği karşı servise iki kez gönderildiğinde idempotency anahtarı (Idempotency-Key) yoksa müşteriden çift tahsilat yapılabilir veya muhasebede mükerrer fatura/irsaliye kesilir. Tekillik kontrolü aynı işlemin yalnızca bir kez işlenmesini garanti altına alır.

Ödeme veya kargo sağlayıcılarından gelen webhook bildirimleri nasıl güvenli hale getirilir?

Webhook uç noktaları dış dünyaya açık olduğundan, gelen isteğin gerçekten ilgili sağlayıcıdan geldiğini kanıtlamak için HMAC-SHA256 imza doğrulaması (timing-safe karşılaştırma ile), timestamp/replay koruması ve mümkünse IP allowlist uygulanmalıdır.

Üçüncü parti bir API geçici olarak yanıt vermezse (503 veya timeout) sistem veriyi nasıl korur?

Kullanıcıyı bekleten doğrudan senkron çağrılar yerine mesaj kuyruğu ve exponential backoff (üstel bekleme) + jitter ile yeniden deneme stratejisi kurulmalıdır. Belirli deneme sayısından sonra kalıcı hata alan kayıtlar Dead Letter Queue (DLQ) alanına alınarak izlenir.

Özel API entegrasyonu ve sistem bağlama projelerinin maliyeti nedir?

Tekil kurumsal web form/CRM bağlantısı içeren özel web projeleri ve Sanal POS ödeme entegrasyonları ₺24.900+, sanal POS/kargo/e-Fatura entegrasyonlu e-ticaret altyapıları ₺49.900+, masaüstü/ERP entegrasyonları ve özel Web SaaS/API middleware platformları ₺66.900+, B2B bayi portalları ise ₺74.900+ bandından başlamaktadır.

5. Sonraki Adım: Sistemlerinizi Güvenle Konuşturun

İlgili hizmetlerimiz ve mimari rehberlerimiz:

• Özel Yazılım ve API Entegrasyonu Hizmeti
• Masaüstü Yazılım ve ERP Geliştirme
• E-Ticaret Sitesi Yaptırma
• Başarılı Bir SaaS Projesi Nasıl Geliştirilir?
• Magento 2 ERP ve Muhasebe Entegrasyon Rehberi
• Proje Fiyat Hesaplama

Şirket içi yazılımlarınızı ve harici servislerinizi tek bir sağlam API katmanında birleştirmek için bize ulaşın:

• Telefon & WhatsApp: 0543 256 97 07
• E-posta: [email protected]
• İletişim: API Entegrasyon Görüşmesi Planla