E-fatura API entegrasyonu: ERP'nizden otomatik fatura kesin

Panelden manuel fatura kesmek KOBİ'ler için yeterli. Ama yüzlerce-binlerce satış yapıyorsanız (e-ticaret, B2B toptancı, SaaS abonelik) her faturayı elle kesmek imkansız. Çözüm: API entegrasyonu.

Hesapdar REST API, kendi ERP'niz, e-ticaret siteniz veya özel yazılımınızdan doğrudan e-fatura kesmenizi sağlar. Fatura verisini bir HTTP isteği ile gönderirsiniz, Hesapdar GİB'e iletir, sonuçları webhook ile geri bildirir.

Kim için ne zaman?

API entegrasyonu şu durumlarda anlamlı:

• E-ticaret siteleri: Sipariş tamamlandığında otomatik fatura.
• B2B toptancılar: Sipariş-fatura eşlemesi ERP üzerinden.
• SaaS işletmeler: Abonelik yenilemesinde otomatik tekrarlayan fatura.
• Pazaryeri satıcıları: Trendyol, Hepsiburada sipariş senkronizasyonu.
• Bayiler ve dağıtımcılar: Çoklu konum / çoklu marka yönetimi.

Aylık 100 faturadan az ise manuel panelin avantajı daha yüksek, kullanıcı kontrolü, hata farkındalığı. 100+ üstünde API otomasyonu kaçınılmaz.

Authentication

Her API çağrısı için Bearer token kullanılır. Token'ı paneldeki Ayarlar → API Anahtarları bölümünden oluşturun.

curl -X POST https://api.hesapdar.com/v1/invoices \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

Token'lar:

• Tüm hesap veya sadece belirli şubeye yetkilendirilebilir.
• Scoped (faturalar, müşteriler, raporlar) olarak sınırlanabilir.
• IP beyaz listesine bağlanabilir.
• İsteğe bağlı olarak son kullanma tarihi belirlenebilir.

Temel endpoint: fatura oluştur

POST /v1/invoices

{
  "customer": {
    "taxNumber": "1234567890",
    "name": "ABC Ticaret A.Ş.",
    "address": "Levent, İstanbul",
    "email": "muhasebe@abc.com.tr"
  },
  "items": [
    {
      "name": "SaaS Abonelik - Kurumsal Plan",
      "quantity": 1,
      "unitPrice": 2499.00,
      "vatRate": 20,
      "unit": "ADET"
    }
  ],
  "metadata": {
    "orderId": "ORD-2026-00145",
    "paymentMethod": "credit_card"
  }
}

Yanıt:

{
  "id": "inv_7f3a2b9c",
  "ettn": "A3B7C2D1-E5F8-4A9B-8C3D-1E7F2A4B6C9D",
  "status": "pending",
  "documentUrl": "https://hesapdar.com/invoices/inv_7f3a2b9c.pdf",
  "xmlUrl": "https://hesapdar.com/invoices/inv_7f3a2b9c.xml",
  "total": {
    "subtotal": 2499.00,
    "vat": 499.80,
    "grandTotal": 2998.80
  }
}

Durum değerleri:

• pending, sisteme yüklendi, GİB'e gönderilecek.
• sent, GİB'e iletildi, alıcıya ulaştı.
• accepted, alıcı kabul etti (ticari fatura için).
• rejected, alıcı reddetti veya GİB hata verdi.
• canceled, iade faturasıyla kapatıldı.

Webhook ile durum takibi

API çağrısı sonrası fatura durumu değiştiğinde Hesapdar size HTTP POST ile bildirir.

Ayarlar → Webhooks üzerinden endpoint URL'inizi girin. Hesapdar şu olaylarda webhook yollar:

• invoice.sent
• invoice.accepted
• invoice.rejected
• invoice.canceled

Webhook payload örneği:

{
  "event": "invoice.rejected",
  "invoiceId": "inv_7f3a2b9c",
  "ettn": "A3B7C2D1-...",
  "reason": "Alıcı VKN'si GİB veri tabanında bulunamadı",
  "timestamp": "2026-04-20T14:32:18Z"
}

Webhook imzalı gelir (HMAC-SHA256). İmzayı doğrulamadan kabul etmeyin:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  return hmac.digest('hex') === signature;
}

Diğer faydalı endpoint'ler

Rate limit

• Varsayılan: dakikada 60 istek
• Kurumsal pakette: dakikada 600 istek
• Özel limit ihtiyacı için enterprise sales ile konuşulur.

Limit aşılırsa 429 Too Many Requests döner; Retry-After header'ı saniye olarak bekleme süresini gösterir.

Idempotency (tekrarlı çağrılar)

Fatura kesim gibi kritik işlemlerde aynı isteğin iki kez gönderilmesi ciddi sorun yaratır (aynı sipariş için iki fatura!). Idempotency-Key header'ı kullanın:

Idempotency-Key: ORD-2026-00145

Aynı key ile ikinci istek geldiğinde Hesapdar orijinal yanıtı tekrar döner, yeni fatura oluşturmaz.

Test ortamı (sandbox)

Canlı fatura kesmeden önce test ortamında deneyin.

• URL: https://sandbox-api.hesapdar.com/v1
• Test API key panelden alınır.
• GİB'e gerçek fatura gönderilmez; sahte ETTN ve sahte durum döndürülür.
• Rate limit yok, sınırsız istek.

Test ortamında tüm production endpoint'leri aynı şemayla çalışır. Üretime geçiş için sadece URL ve API key değiştirilir.

Hata yönetimi

API 200, 400, 401, 403, 404, 422, 429, 500 HTTP kodlarıyla yanıt verir. 422 (iş kuralı hatası) yanıtlarında detaylı alan bilgisi gelir:

{
  "error": "validation_failed",
  "details": [
    { "field": "customer.taxNumber", "message": "VKN 10 haneli olmalı" },
    { "field": "items[0].vatRate", "message": "Geçersiz KDV oranı" }
  ]
}

5xx hatalarında automatic retry (exponential backoff) implement edin. 4xx hatalarında tekrar deneme yapmayın, istek yanlış.

SDK'lar

Hesapdar resmi SDK'lar yayımlar:

• Node.js / TypeScript, npm install @hesapdar/sdk
• PHP / Laravel, composer require hesapdar/laravel
• Python, pip install hesapdar
• .NET / C#, NuGet Hesapdar.Sdk

SDK'lar authentication, retry, webhook doğrulaması ve tüm endpoint'leri type-safe olarak sarar.

Sonraki adım

API erişimi Kurumsal pakette standart, Standart pakette aylık 1.000 çağrıya kadar ücretsiz. Detaylı dokümantasyon için docs.hesapdar.com, canlı deneme hesabı ve kod örnekleri içerir. Kurumsal entegrasyon için iletişime geçin.