Geliştirici dokümanı · Protokol v1

Özel Entegrasyon API

Kendi yazılımınızla çalışan bir e-ticaret siteniz ya da müşterilerine altyapı sunan bir firmanız varsa, aşağıdaki dört uç noktayı yayınlayarak siparişlerinizi efaturan'a bağlayabilirsiniz. efaturan bu uç noktaları düzenli aralıklarla çağırır, siparişleri e-Fatura / e-Arşiv olarak faturalandırır ve isterseniz kesilen faturayı sitenize geri bildirir.

Genel kurallar

Tüm uç noktalar tek bir kök adresin altındadır, ör. https://www.siteniz.com/api/efaturan. Yalnızca HTTPS.
Kimlik doğrulama: her istekte Authorization: Bearer <API şifresi> başlığı. Şifreyi siz üretir, efaturan panelinde mağaza eklerken girersiniz. Hatalı şifrede 401 dönün.
İstek ve yanıtlar JSON (UTF-8). Tutarlar ondalık TL (ör. 149.90), tarihler ISO 8601 (saat dilimiyle).
efaturan her istekte X-Efaturan-Protocol: 1 başlığını gönderir. Yanıt süresi 30 saniyeyi geçmemelidir; 429 ve 5xx yanıtlarında istek tekrar denenir.

GET/ping

Bağlantı testi. Paneldeki "Bağlantıyı test et" bu uç noktayı çağırır.

{ "ok": true, "store": "Mağaza adınız", "version": "1" }

GET/order-statuses

Sitenizdeki sipariş durumları. Satıcı, panelde yalnızca belirli durumlardaki siparişlerin çekilmesini seçebilir; seçilen kimlikler /orders isteğinde status parametresiyle gelir.

{ "statuses": [ { "id": "2", "name": "Onay bekliyor" }, { "id": "3", "name": "Ödendi" }, { "id": "4", "name": "Kargoda" } ] }

GET/orders?since=…&until=…&page=1&pageSize=100&status=3,4

since – until aralığında oluşturulan veya güncellenen siparişler, sayfalı. status verilmişse yalnızca o durum kimlikleri. Bir sonraki sayfa varsa totalPages ile bildirin; efaturan en fazla 100 sayfa ister.

{
  "orders": [
    {
      "id": "10045",
      "number": "SP-10045",
      "status": "paid",
      "statusId": "3",
      "createdAt": "2026-10-08T10:15:00+03:00",
      "paidAt": "2026-10-08T10:16:12+03:00",
      "currency": "TRY",
      "pricesIncludeVat": true,
      "paymentMethod": "KREDIKARTI/BANKAKARTI",
      "customer": {
        "type": "company",
        "name": "Örnek Ltd. Şti.",
        "taxNumber": "1234567890",
        "taxOffice": "Kadıköy",
        "email": "muhasebe@ornek.com",
        "phone": "05551234567",
        "address": "Moda Cad. No:1",
        "district": "Kadıköy",
        "city": "İstanbul",
        "postalCode": "34710",
        "country": "Türkiye"
      },
      "shipping": { "fee": 29.90, "carrier": "Yurtiçi Kargo", "trackingNumber": "123456", "shippedAt": "2026-10-09T09:00:00+03:00" },
      "items": [
        { "sku": "TS-1", "name": "Pamuklu Tişört", "quantity": 2, "unitPrice": 150.00, "vatRate": 20, "discount": 30.00 }
      ],
      "invoiced": false
    }
  ],
  "page": 1,
  "totalPages": 3
}

Alan	Açıklama
id	Siparişin sitenizdeki tekil kimliği. Faturalanan birimdir; aynı id'ye ikinci fatura kesilmez.
status	created (ödeme bekleniyor) · paid · shipped · delivered · cancelled · returned. Yalnızca paid, shipped ve delivered siparişler faturalanır; created siparişler ödeme alınınca faturalanır, iptal/iade siparişlere fatura kesilmez.
pricesIncludeVat	unitPrice ve discount KDV dahil mi (varsayılan true).
paymentMethod	GİB kodu: KREDIKARTI/BANKAKARTI · EFT/HAVALE · KAPIDAODEME · ODEMEARACISI · DIGER. e-Arşiv internet satışı bilgisine yazılır.
customer.type	individual (bireysel) veya company (kurumsal). Kurumsalda taxNumber 10 haneli VKN olmalı; alıcı e-Fatura mükellefiyse e-Fatura, değilse e-Arşiv kesilir.
customer.taxNumber	Bireyde 11 haneli TCKN; yoksa boş bırakın (nihai tüketici kabul edilir).
items[].unitPrice	İndirim öncesi birim fiyat.
items[].discount	Satırın toplam indirimi (aynı KDV bazında).
items[].vatRate	KDV oranı (%), ör. 20, 10, 1, 0.
shipping.fee	Alıcıdan alınan kargo ücreti; faturaya "Kargo Bedeli" satırı olarak eklenir.
invoiced	Sipariş başka yerde faturalandıysa true; efaturan atlar.

POST/invoices

Fatura kesildikten ve GİB'e iletildikten sonra (satıcı "fatura siteye iletilsin" seçtiyse) bildirilir. 2xx dönün; aynı sipariş için tekrar gelirse yine 2xx dönün.

{
  "orderId": "10045",
  "invoiceNumber": "ABC2026000000123",
  "uuid": "2f7a0c1e-…",
  "issueDate": "2026-10-08",
  "url": "https://efaturan.com/f/…",
  "total": 329.90,
  "currency": "TRY"
}

Canlıya almadan önce

Panelde Mağaza Ayarları → Özel Entegrasyon → yeni mağaza ekleyin, kök adresi ve şifreyi girin, "Bağlantıyı test et".
Otomatik faturayı kapalı tutarak Otomasyon sayfasından "Şimdi çalıştır" ile siparişleri çekin ve tutarları kontrol edin.
Bir siparişi elle faturalayıp tutarı, KDV'yi ve alıcı bilgilerini doğrulayın; sonra otomatik faturayı açın.