İçeriğe geç

e-Belge

Fatura API

Yazılımınızdan e-Fatura ve e-Arşiv kesin, durumunu izleyin, PDF ve XML'ini alın.

Ön Muhasebe ve E-Ticaret paketlerinde. Deneme süresinde test anahtarıyla deneyebilirsiniz.

Base URLhttps://panel.efaturan.com/api/v1
Sürüm
v1.0.0
Son güncelleme
Uç sayısı
10 uç

Genel bakış

Kendi yazılımınızdan (ERP, sipariş sistemi, e-ticaret altyapısı, muhasebe programı) eFaturan'a istek atarak e-Fatura ve e-Arşiv faturası kesin; durumunu, PDF'ini ve XML'ini alın; e-Arşiv faturasını iptal edin; belge olaylarını webhook ile anında öğrenin.

Kimler kullanabilir#

DurumAPI
Ön Muhasebe ve E-Ticaret paketleriCanlı ve test anahtarı
Deneme süresi (14 gün)Yalnızca test anahtarı: belgeler deneme ortamında kesilir, GİB'e gitmez
E-Fatura paketiYok (panelde paket bilgisi görünür)
Süresi dolmuş abonelik, askıdaki hesapAnahtarlar çalışmaz (403)

Hak her istekte denetlenir: paket değişir ya da abonelik biterse anahtar o andan itibaren 403 alır; hak geri gelince aynı anahtar yeniden çalışır.

Başvuru süreci yoktur. Hesap sahibi ya da Yönetici rolündeki kullanıcı panelde Ayarlar › API Anahtarları sayfasından anahtar oluşturur.

İstek ve yanıt kuralları#

  • Kök adres: https://panel.efaturan.com/api/v1. Gövde JSON (Content-Type: application/json, UTF-8), en çok 512 KB.
  • Katı şema: tanımlı olmayan alan gönderilirse istek 422 VALIDATION_ERROR alır (yazım hatası sessizce yok sayılmaz). Sorgu parametreleri için de geçerlidir.
  • Tutarlar belge para biriminde ondalık sayıdır (ör. 1234.56); kuruş yuvarlaması eFaturan'ın hesap kurallarıyla yapılır.
  • Fatura tarihi YYYY-AA-GG (Türkiye saati). Zaman damgaları ISO 8601, UTC (2026-11-20T09:15:00.000Z).
  • Her yanıtta X-Request-Id başlığı vardır; destek talebinde paylaşın.
  • Yanıtlar önbelleğe alınmaz (Cache-Control: no-store).
  • Desteklenmeyen yöntem 405 (gövdesiz) döner.

Idempotency#

Ağ kopması, zaman aşımı ya da yeniden deneme yüzünden aynı faturanın iki kez kesilmemesi için POST /invoices isteğinde Idempotency-Key başlığı zorunludur. cancel ve send-email uçlarında isteğe bağlıdır.

  • Her yeni belge için benzersiz bir değer üretin (UUID önerilir). Değeri kendi kaydınızla (ör. sipariş numarası) birlikte saklayın ve yeniden denemede aynı değeri ve aynı gövdeyi gönderin.
  • Aynı anahtar + aynı istek (yöntem, yol ve gövde; alan sırası önemsiz) 24 saat boyunca ilk yanıtı döndürür; ikinci belge kesilmez. Yinelenen yanıtta Idempotent-Replayed: true başlığı bulunur.
  • Aynı anahtar farklı gövdeyle gelirse 409 IDEMPOTENCY_KEY_REUSED.
  • Aynı anahtarla eşzamanlı iki istek gelirse yalnızca biri işlenir; diğeri 409 IDEMPOTENCY_IN_PROGRESS alır. Birkaç saniye sonra aynı istekle yeniden deneyin, ilk yanıtı alırsınız.
  • 4xx yanıtta belge oluşmamıştır ve anahtar serbest kalır: hatayı düzeltip aynı anahtarla yeniden gönderebilirsiniz (ör. 428 sonrası confirm ekleyerek).
  • 5xx yanıt saklanır (belge entegratöre gitmiş olabilir): aynı anahtarla yineleme aynı hatayı döner, yeni belge kesmez. Önce GET /invoices ile belgeyi denetleyin; yoksa yeni anahtarla deneyin.
  • Kayıtlar hesap ve ortam başınadır; 24 saat sonra silinir. İstek yarıda kalmışsa (sunucu kesim sırasında yeniden başladı) kayıt silinmez: süresi dolunca 500 "sonuç belirsiz" olarak 7 gün daha saklanır; aynı anahtar ikinci belge kesmez. GET /invoices ile belgeyi denetleyin, gerekirse yeni anahtarla deneyin.

Sayfalama#

Liste uçları imleçlidir. Yanıt:

JSON
{ "object": "list", "data": [ … ], "hasMore": true, "nextCursor": "eyJjIjoiMjAyNi0xMS0yMFQwOTox…" }

Sonraki sayfa için nextCursor değerini cursor parametresiyle gönderin (?limit=50&cursor=…). Sıra yeniden eskiye (oluşturulma zamanı); yeni belgeler araya girse de sayfalar kaymaz. limit 1-100, varsayılan 25.

Hız sınırları#

SınırDeğer
Anahtar başınaDakikada 120 istek
Hesap başına (tüm anahtarlar)Dakikada 600 istek
Mükellef sorgusuHesap başına 10 dakikada 120
E-posta gönderimiHesap başına saatte 30 (panelden ve API'den gönderilenler birlikte sayılır)
Geçersiz anahtar denemesiIP başına dakikada 30 (aşılınca o adresten gelen geçersiz denemeler 1 dakika 429 alır; geçerli anahtarlı istekler etkilenmez)

Her başarılı yanıtta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset (Unix saniye) başlıkları vardır. Sınır aşılınca 429 RATE_LIMITED ve Retry-After (saniye) döner.

Sürümler ve değişiklikler

  • Sürüm yolun içindedir: /api/v1. Bu sürümde geriye uyumlu değişiklikler yapılır: yeni uç, yeni isteğe bağlı istek alanı, yanıta yeni alan, yeni hata kodu, yeni webhook olayı. İstemciniz tanımadığı yanıt alanlarını ve olayları yok saymalıdır.
  • Kırıcı değişiklik (alanın kaldırılması ya da anlamının değişmesi, zorunlu yeni alan, davranış değişikliği) yalnızca yeni sürümle (/api/v2) gelir; eski sürüm duyurudan sonra belirli bir süre birlikte çalışır.
  • İstek gövdesi katıdır: yeni bir isteğe bağlı alan eklendiğinde eski istemciler etkilenmez.
TarihSürümDeğişiklik
2026-11-211.0.0İlk sürüm: fatura kesme / taslak, liste, ayrıntı, PDF, XML, e-Arşiv iptali, e-posta, mükellef sorgusu, hesap, seriler; Idempotency-Key; webhook'lar (invoice.issued, invoice.status_changed, invoice.failed, invoice.canceled, credits.low). Yayın öncesi güvenlik düzeltmeleri: kontörlü kesim hesap başına sırada; ekipten çıkan kişinin anahtarları iptal; taslak ortama bağlı; test belgesi yalnızca hesabın kendi adreslerine e-postalanır; geçersiz anahtar engeli geçerli anahtarı kesmez; yarıda kalan Idempotency kaydı "sonuç belirsiz"; webhook portu 443/8443/9443, adil teslim sırası ve art arda hatada erken pasife alma.

Bu sürümde olmayanlar: e-İrsaliye ve e-Serbest Meslek Makbuzu kesme, gelen faturalar, cari ve ürün kartları, panel taslağını API'den kesme. Panelden yapılmaya devam eder.

Hızlı başlangıç

  1. Panelde Ayarlar › Entegratör sayfasında Test ortamı bilgilerinin kayıtlı olduğundan emin olun (test anahtarı bu bağlantıyla belge keser).
  2. Ayarlar › API Anahtarları sayfasında Test ortamı için bir anahtar oluşturun. Anahtar (ef_test_…) yalnızca bir kez gösterilir; kopyalayıp sunucunuzda saklayın.
  3. İlk faturayı kesin:
Kabuk
curl https://panel.efaturan.com/api/v1/invoices \
  -H "Authorization: Bearer $EFATURAN_KEY" \
  -H "Idempotency-Key: 7c1e9a52-0f0e-4f43-9d0e-2b8f3f4c1a10" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": { "firstName": "Ayşe", "lastName": "Yılmaz", "city": "İstanbul", "district": "Kadıköy",
               "address": "Caferağa Mah. Örnek Sok. No: 1", "email": "ayse@example.com" },
    "lines": [ { "name": "Kitap", "quantity": 2, "unitPriceExcl": 100, "vatRate": 10 } ]
  }'
  1. Yanıttaki id ile durumu izleyin (GET /invoices/{id}) ya da webhook ekleyin (invoice.status_changed).
  2. Her şey hazır olunca Canlı anahtar oluşturun; kodunuzda yalnızca anahtar değişir.

Kimlik doğrulama

Kod
Authorization: Bearer ef_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • Anahtar biçimi: ef_live_ ya da ef_test_ + 43 karakter. Başka başlık (ör. X-Api-Key), sorgu parametresi ya da tarayıcı çerezi kabul edilmez.
  • Anahtar yalnızca sunucu tarafında kullanılmalıdır. Tarayıcıya, mobil uygulamaya ya da herkese açık bir depoya koymayın. Uçlar CORS izni vermez.
  • Panelde anahtar oluştururken seçilenler:
AyarAçıklama
AdHangi yazılımın kullandığını ayırt etmek için (2-80 karakter).
OrtamCanlı (ef_live_) ya da Test (ef_test_). Deneme süresinde yalnızca Test.
KapsamlarAnahtarın açabileceği uç grupları (aşağıda). En az biri.
IP izin listesiİsteğe bağlı. Tek adres (203.0.113.5) ya da aralık (203.0.113.0/24, IPv6 da olur), en çok 20. Boşsa her adresten.
Bitiş tarihiİsteğe bağlı. O günün sonunda (Türkiye saati) anahtar kendiliğinden geçersizleşir; en çok 3 yıl sonrası.
  • Anahtarı ekipteki bir kullanıcı oluşturduysa, kişi ekipten çıkarıldığında ya da rolü API yetkisi olmayan bir role (Operatör, Mali müşavir, Salt okuma) düşürüldüğünde oluşturduğu anahtarlar kendiliğinden iptal edilir (401 API_KEY_REVOKED). Panelde her anahtarın yanında oluşturan kişi görünür.
KapsamAçtığı uçlar
invoices:writePOST /invoices, POST /invoices/{id}/cancel, POST /invoices/{id}/send-email
invoices:readGET /invoices, GET /invoices/{id}, GET /invoices/{id}/pdf, GET /invoices/{id}/xml
taxpayers:readGET /taxpayers/{vknTckn}
account:readGET /account, GET /series
  • Hesap başına en çok 20 etkin anahtar. Panel her anahtarın son kullanım zamanını ve IP'sini gösterir.
  • İptal et anahtarı hemen geçersiz kılar (geri alınamaz). Sızdığından şüphelendiğiniz anahtarı iptal edip yenisini oluşturun.
  • eFaturan anahtarın tam değerini saklamaz; kaybederseniz yenisini oluşturursunuz.

Test ortamı

Ortamlar: test ve canlı#

Test (ef_test_)Canlı (ef_live_)
Belgenin gittiği yerDeneme ortamı; GİB'e gitmez, resmî değildirGİB
Kullanılan bağlantıPanelde Entegratör › Test ortamıEntegratör › Canlı ortam
SerilerTest ortamının serileriCanlı ortamın serileri
KontörDüşmezKontörlü pakette belge başına 1
Görünen belgelerYalnızca test belgeleriYalnızca canlı belgeler
  • Anahtarın ortamı, panelde hangi ortamın "etkin" seçildiğinden bağımsızdır: test anahtarı her zaman test, canlı anahtar her zaman canlı bağlantıyı kullanır. O ortamın bağlantısı yoksa 409 ENVIRONMENT_NOT_CONFIGURED.
  • Bir ortamın anahtarı öbür ortamın belgesini göremez (404). Idempotency anahtarları ve webhook uçları da ortama ayrıdır.

Test ortamı#

  • Test anahtarı (ef_test_…) hesabın test ortamı entegratör bağlantısını kullanır. Belgeler GİB'e gitmez, resmî değildir ve kontör düşmez. Deneme süresindeki hesaplar yalnızca test anahtarı kullanabilir.
  • Test ortamının serileri, mükellef listesi ve belgeleri canlıdan ayrıdır. GET /series ile test serilerinizi görün; seri yoksa panelde Seriler & Şablonlar'dan ekleyin.
  • Webhook'ları test ortamı için ayrı bir uçla deneyin (uç eklerken Test'i seçin).
  • Canlıya geçerken yalnızca anahtarı değiştirin; gövde, idempotency ve webhook mantığı aynıdır.

Hata kodları

Bütün hatalar aynı gövdeyle döner:

JSON
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "İstek gövdesi ya da parametreler geçersiz.",
    "details": { "issues": [ { "path": "buyer.taxOrIdNumber", "code": "custom", "message": "VKN geçersiz (kontrol hanesi tutmuyor)." } ] },
    "requestId": "req_4kq3uWw1Hc9yb0xP"
  }
}

Kararınızı code alanına göre verin; message Türkçe açıklamadır ve değişebilir. Kodlar kararlıdır.

KodHTTPNe zaman
UNAUTHENTICATED401Authorization: Bearer … başlığı yok
INVALID_API_KEY401Anahtar geçersiz ya da bilinmiyor
API_KEY_REVOKED401Anahtar iptal edilmiş
API_KEY_EXPIRED401Anahtarın bitiş tarihi geçmiş
IP_NOT_ALLOWED403İstek anahtarın IP izin listesinde olmayan adresten
INSUFFICIENT_SCOPE403Anahtarda bu uç için kapsam yok
PLAN_REQUIRED403Paket Fatura API'si hakkını içermiyor
LIVE_KEY_NOT_ALLOWED403Canlı anahtar bu hesapta kullanılamıyor (deneme süresi)
ACCOUNT_SUSPENDED403Hesap askıda
SUBSCRIPTION_EXPIRED403Paket süresi dolmuş
DOCUMENT_ISSUE_BLOCKED403Hesap şu an belge kesemiyor (ör. aylık kota doldu)
INSUFFICIENT_CREDITS402Kontör yetersiz; details.balance kalan bakiye
NOT_FOUND404Kayıt yok, başka hesabın ya da öbür ortamın kaydı
INVALID_JSON400Gövde geçerli JSON değil ya da boş
UNSUPPORTED_MEDIA_TYPE415Content-Type JSON değil
PAYLOAD_TOO_LARGE413Gövde 512 KB'tan büyük
VALIDATION_ERROR422Alan doğrulaması; details.issues[] alan yolu, kod, ileti
BUSINESS_RULE_VIOLATION422İş kuralı: tarih engeli, fatura tipi, tevkifat, istisna, kur, seri, iade referansı…
ISSUE_DATE_CONFIRMATION_REQUIRED428Fatura tarihi açık onay istiyor (aşağıda)
IDEMPOTENCY_KEY_REQUIRED400POST /invoices için Idempotency-Key yok
IDEMPOTENCY_KEY_INVALID400Idempotency-Key 1-255 karakter, boşluksuz görünür ASCII değil
IDEMPOTENCY_KEY_REUSED409Aynı anahtar farklı bir istekle kullanılmış
IDEMPOTENCY_IN_PROGRESS409Aynı anahtarla yapılan istek henüz sonuçlanmadı (Retry-After)
INVALID_STATE409Belge bu işlem için uygun değil (ör. e-Fatura iptali, zaten iptal, dosya henüz hazır değil)
ENVIRONMENT_NOT_CONFIGURED409Anahtarın ortamı için entegratör bağlantısı yok
INTEGRATOR_REJECTED400Entegratör belgeyi reddetti (details.integratorCode)
INTEGRATOR_UNAVAILABLE502Entegratöre ulaşılamadı; biraz sonra yeniden deneyin
RATE_LIMITED429Hız sınırı; Retry-After saniye sonra yeniden deneyin
INTERNAL_ERROR500Beklenmeyen hata; requestId ile bize yazın

Yeni hata kodu eklenmesi kırıcı değişiklik sayılmaz: tanımadığınız kodu HTTP durumuna göre ele alın.

Webhook'lar

Panelde API Anahtarları › Webhook'lar sekmesinden https adresinizi ve olayları seçin. Seçilen olaylar imzalı POST isteğiyle adresinize gelir. Olaylar panelden, otomasyondan ya da API'den kesilen bütün belgeler için üretilir.

OlayNe zaman
invoice.issuedBelge numara alıp entegratöre iletildi (sonucu belirsiz gönderimde belge bulununca)
invoice.status_changedHer durum değişikliği (data.previousStatus önceki durum)
invoice.failedDurum error oldu (data.reason)
invoice.cancelede-Arşiv faturası iptal edildi
credits.lowCanlı belge kesiminden sonra kontör bakiyesi 50, 10 ya da 0'a indi (data.balance, data.threshold)

Uç bir ortama bağlıdır (Canlı / Test) ve yalnızca o ortamdaki belgelerin olaylarını alır. Hesap başına en çok 10 uç.

Gövde#

JSON
{
  "id": "evt_Qm9yZXZlcl9hbmRfZXZlcg",
  "type": "invoice.status_changed",
  "createdAt": "2026-11-20T09:16:05.120Z",
  "environment": "live",
  "data": {
    "invoice": {
      "id": "cmi7x2k1p0003l50ab3c4d5e6", "documentNumber": "ABC2026000000042", "ettn": "3f1c2d4e-…", "documentType": "e_fatura",
      "profile": "TICARIFATURA", "typeCode": "SATIS", "status": "sent", "issueDate": "2026-11-20", "total": 1200, "currency": "TRY", "source": "api"
    },
    "previousStatus": "sending"
  }
}

Olay verisinde alıcının kişisel bilgisi yoktur; ayrıntı için GET /invoices/{id}.

Başlıklar#

BaşlıkAçıklama
X-Efaturan-Signaturet=<unix saniye>,v1=<HMAC-SHA256 onaltılık>
X-Efaturan-EventOlay türü
X-Efaturan-Event-IdOlay kimliği (gövdedeki id); yeniden denemede aynıdır
X-Efaturan-DeliveryTeslimat kimliği
X-Efaturan-AttemptDeneme sırası (1-7)
User-AgenteFaturan-Webhook/1

İmza doğrulama#

İmzalanan metin "<t>.<ham gövde>"; anahtar, uç eklenirken bir kez gösterilen gizli anahtardır (whsec_…, olduğu gibi, UTF-8). Ham gövdeyi JSON'a çevirmeden önce doğrulayın, karşılaştırmayı sabit zamanlı yapın ve t 5 dakikadan eskiyse reddedin.

<?php
$secret = getenv('EFATURAN_WEBHOOK_SECRET');            // whsec_…
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_EFATURAN_SIGNATURE'] ?? '';

$t = 0; $sigs = [];
foreach (explode(',', $header) as $part) {
    [$k, $v] = array_pad(explode('=', trim($part), 2), 2, '');
    if ($k === 't') { $t = (int) $v; }
    if ($k === 'v1') { $sigs[] = $v; }
}
if ($t === 0 || abs(time() - $t) > 300) { http_response_code(400); exit; }

$expected = hash_hmac('sha256', $t . '.' . $body, $secret);
$valid = false;
foreach ($sigs as $sig) { if (hash_equals($expected, $sig)) { $valid = true; } }
if (!$valid) { http_response_code(400); exit; }

$event = json_decode($body, true);
// $event['id'] daha önce işlendiyse atlayın; işi kuyruğa alıp hemen yanıt verin.
http_response_code(204);

Teslim ve yeniden deneme#

  • Herhangi bir 2xx yanıt teslim edildi sayılır. 10 saniyede yanıt verin; işi kuyruğa alıp hemen dönün. Yanıt gövdesi okunmaz (64 KB'tan büyük yanıt hata sayılır).
  • 3xx (yönlendirme izlenmez), 4xx, 5xx, zaman aşımı ve bağlantı hatası başarısız denemedir. Yeniden deneme: 1 dk, 5 dk, 30 dk, 2 sa, 6 sa, 12 sa sonra (en çok 7 deneme, yaklaşık 21 saat).
  • Son deneme de başarısızsa olay "başarısız" olur, uç pasife alınır ve panelde uyarı görünür. Uç ayrıca art arda 20 başarısız denemede (zaman aşımı dahil) erkenden pasife alınır. Adresi düzeltip Yeniden etkinleştir'e basın; pasifken üretilen olaylar gönderilmez (durumu GET /invoices ile eşitleyin).
  • Teslim sırası hesaplar arasında adildir (her turda hesap başına en çok 5 teslimat). Hesap başına en çok 1000 bekleyen teslimat tutulur; aşılınca en eskileri "başarısız" kapanır. Deneme süresindeki hesap en çok 2 uç ekleyebilir.
  • Panelde ve deneme olayında ağ hataları kaba sınıfla gösterilir ("Bağlantı kurulamadı", "TLS (sertifika) hatası", "Alan adı çözümlenemedi", "Zaman aşımı").
  • Aynı olay birden çok kez gelebilir; sıra garanti değildir. id (ya da X-Efaturan-Event-Id) ile tekrarları ayıklayın, durumu belgenin updatedAt'ine göre değerlendirin.
  • Adres kuralları: yalnızca https; port yalnızca 443, 8443 ya da 9443 (yazılmazsa 443); yerel / özel ağ adresleri, bulut metadata adresleri ve eFaturan'ın kendi alan adları kabul edilmez; ad, kayıtta ve her bağlantıda yeniden çözülüp denetlenir.
  • Deneme olayı gönder (type: "webhook.test") yalnızca seçilen uca, hemen ve tek denemeyle gider; sonucu panelde görünür.
  • İmza anahtarını yenile eskisini hemen geçersiz kılar; alıcı sunucunuzdaki değeri de güncelleyin.
  • Panelde uç başına son 100 teslimat (durum, deneme sayısı, HTTP kodu, süre, gövde) görünür; gövdedeki kişisel bilgiler maskelenir.

Olay gövdesinin alanları#

OpenAPI belgesindeki tanım (WebhookEvent). Webhook isteğinin başlıkları:

Webhook başlıkları
AlanTipDurumAçıklama
X-Efaturan-Signaturebaşlık
metinZorunlu—
X-Efaturan-Eventbaşlık
metinZorunlu—
X-Efaturan-Event-Idbaşlık
metinZorunlu—
X-Efaturan-Deliverybaşlık
metinZorunlu—
Webhook olay gövdesi
AlanTipDurumAçıklama
id
metinZorunluOlay kimliği (evt_…); yinelenen teslimde aynıdır.
type
"invoice.issued"|"invoice.failed"|"invoice.canceled"|"invoice.status_changed"|"credits.low"|"webhook.test"Zorunlu—
createdAt
metinZorunluISO 8601 zaman damgası (UTC).
environment
"live"|"test"ZorunluAnahtarın ortamı: live (canlı) ya da test.
nesneZorunlu—

Sık sorulan sorular

Belge türünü (e-Fatura / e-Arşiv) ben seçebilir miyim?

Hayır. GİB kuralına göre alıcı e-Fatura mükellefiyse e-Fatura kesilmelidir; tür alıcıya göre kendiliğinden seçilir. Önceden görmek için GET /taxpayers/{vknTckn}.

İstek zaman aşımına uğradı, fatura kesildi mi?

Aynı Idempotency-Key ve aynı gövdeyle yeniden gönderin: kesildiyse ilk yanıtı alırsınız, kesilmediyse şimdi kesilir. Yeni anahtar üretmeyin.

202 aldım, ne yapmalıyım?

Belge numara aldı ama entegratör yanıtı gelmedi. Durum birkaç dakika içinde netleşir; GET /invoices/{id} ya da invoice.status_changed / invoice.failed webhook'uyla izleyin. Belgeyi yeniden kesmeyin.

KDV dahil fiyatlarım var, kuruş farkı olur mu?

Kalemde unitPriceExcl ile birlikte targetInclVat (iskonto sonrası KDV dahil satır tutarı) gönderin; tutarlıysa KDV hedeften hesaplanır ve toplam birebir tutar.

Dövizli fatura nasıl kesilir?

currency (ör. USD) ve exchangeRate (1 USD'nin TL karşılığı) gönderin. Kur gönderilmezse fatura kesilmez (422).

e-Fatura'yı iptal edebilir miyim?

Hayır; GİB e-Fatura iptaline izin vermez. Alıcı ticari faturayı reddedebilir ya da invoiceTypeCode: "IADE" ile iade faturası kesilir. e-Arşiv faturası POST /invoices/{id}/cancel ile iptal edilir.

Kontör ne zaman düşer?

Kontörlü pakette, canlı ortamda belge entegratöre başarıyla iletildiğinde belge başına 1 kontör. Test ortamı, taslak, hatalı gönderim düşmez; iptal kontörü geri vermez. Bakiye yetmezse 402 INSUFFICIENT_CREDITS (belge kesilmez, numara harcanmaz). credits.low webhook'uyla önceden haber alın.

Geçmiş tarihli fatura kesebilir miyim?

Evet; 7 günden eski tarih, beyan süresi geçmiş dönem ve geçmiş yıl için açık onay gerekir (confirm.issueDate). İleri tarih kesilemez.

Panelde kesilen faturalar API'de görünür mü?

Evet. Liste ve ayrıntı uçları anahtarın ortamındaki bütün giden faturaları döndürür (source: api, manual, marketplace, ecommerce). Webhook olayları da bütün belgeler için üretilir.

Anahtarı tarayıcıdaki JavaScript'ten kullanabilir miyim?

Hayır. Anahtar tam yetkili bir sırdır; yalnızca sunucunuzda kullanın. Uçlar tarayıcıdan gelen başka kökenli isteklere CORS izni vermez.

IP izin listesi hangi adresi görür?

İsteğin internete çıktığı adresi (sunucunuzun dış IP'si). Vekil sunucu arkasındaysanız vekilin çıkış adresini yazın.

Sınırlar aşılırsa ne olur?

429 RATE_LIMITED ve Retry-After döner; o süre kadar bekleyip yeniden deneyin. Toplu kesimde istekleri sıraya alın.

Faturalar

e-Fatura ve e-Arşiv.

7 uç
GET

Faturaları listele

Kapsam: invoices:read
GEThttps://panel.efaturan.com/api/v1/invoices

Anahtarın ortamındaki giden faturalar; yeniden eskiye (oluşturulma sırası). Süzgeçler fatura tarihine göredir. İmleçli sayfalama: nextCursor → cursor.

Açıklama

ParametreAçıklama
from, toFatura tarihi aralığı (dahil, YYYY-AA-GG).
statusVirgülle: sending, sent, accepted, rejected, cancelled, error.
documentTypee_fatura ya da e_arsiv.
limit1-100, varsayılan 25.
cursorÖnceki yanıtın nextCursor değeri.

Liste öğelerinde kalemler ve alıcının adresi yoktur (yalnızca buyer.name, buyer.taxOrIdNumber); ayrıntı için GET /invoices/{id}.

Kabuk
curl "https://panel.efaturan.com/api/v1/invoices?from=2026-11-01&to=2026-11-30&status=sent,accepted&limit=50" \
  -H "Authorization: Bearer $EFATURAN_KEY"

İstek şeması

GET /invoices istek şeması
AlanTipDurumAçıklama
fromsorgu
tarih (YYYY-AA-GG)İsteğe bağlıFatura tarihi başlangıcı (dahil, YYYY-AA-GG).
tosorgu
tarih (YYYY-AA-GG)İsteğe bağlıFatura tarihi bitişi (dahil, YYYY-AA-GG).
statussorgu
metinİsteğe bağlıDurum süzgeci, virgülle: sending, sent, accepted, rejected, cancelled, error.biçim: ^[a-z]+(,[a-z]+)*$
documentTypesorgu
"e_fatura"|"e_arsiv"İsteğe bağlıBelge türü.
limitsorgu
tam sayıİsteğe bağlıSayfa boyutu (1-100, varsayılan 25).≥ 1≤ 100varsayılan: 25
cursorsorgu
metinİsteğe bağlıÖnceki yanıtın nextCursor değeri.en çok 200 karakter

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Sayfa.application/jsonInvoiceList
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması

36 alan

GET /invoices yanıt şeması
AlanTipDurumAçıklama
object
"list"Zorunlu—
dizi|nesneZorunlu—
hasMore
true / falseZorunlu—
nextCursor
metinZorunluSonraki sayfa için cursor parametresi; son sayfada null.null olabilir

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

curl "https://panel.efaturan.com/api/v1/invoices" \
  -H "Authorization: Bearer $EFATURAN_KEY"

Örnek yanıt

Şemadan üretildi: metin alanlarındaki “…” yer tutucudur.

200 · application/json
{
  "object": "list",
  "data": [
    {
      "id": "…",
      "object": "invoice",
      "environment": "live",
      "status": "sending",
      "documentType": "e_fatura",
      "profile": "TICARIFATURA",
      "invoiceTypeCode": "…",
      "sendType": "ELEKTRONIK",
      "documentNumber": "…",
      "ettn": "…",
      "issueDate": "2026-11-20",
      "currency": "…",
      "totals": {
        "taxExclusive": 0,
        "discount": 0,
        "vat": 0,
        "withholding": 0,
        "payable": 0
      },
      "buyer": {
        "name": "…",
        "taxOrIdNumber": "…"
      },
      "source": "…",
      "errorMessage": "…",
      "gibStatusCode": "…",
      "emailedAt": "…",
      "cancelledAt": "…",
      "createdAt": "…",
      "updatedAt": "…",
      "links": {
        "self": "…",
        "pdf": "…",
        "xml": "…"
      }
    }
  ],
  "hasMore": false,
  "nextCursor": "…"
}
POST

Fatura kes ya da taslak oluştur

Kapsam: invoices:write
POSThttps://panel.efaturan.com/api/v1/invoices

e-Fatura / e-Arşiv belgesini numaralandırıp keser. Belge türü alıcının e-Fatura mükellefiyetine göre kendiliğinden seçilir (İhracat her zaman e-Fatura). mode: "draft" yalnızca panelde taslak oluşturur. Idempotency-Key ZORUNLU: aynı anahtarla yinelenen istek ikinci belge kesmez, ilk yanıtı döner.

Açıklama

Belgeyi numaralandırıp keser. Panelden kesilen faturayla aynı kurallardan geçer: fatura tarihi, fatura tipi ve senaryo, tevkifat ve istisna kodları, döviz kuru, seri ve numara, kontör.

Belge türü kendiliğinden seçilir: alıcının VKN/TCKN'si GİB e-Fatura kayıtlı kullanıcı listesinde ve etkin posta kutusu etiketi varsa e-Fatura, değilse e-Arşiv. Kimlik numarası olmayan alıcı nihai tüketicidir (11111111111) ve her zaman e-Arşiv'dir. İhracat (profile: "IHRACAT") her zaman e-Fatura'dır. Seçilen tür yanıtta documentType alanındadır; önceden öğrenmek için GET /taxpayers/{vknTckn}.

Başlıklar: Authorization, Content-Type: application/json, Idempotency-Key (zorunlu).

Gövde#
AlanTürZorunluAçıklama
mode"issue" | "draft"Hayırissue (varsayılan): belgeyi keser. draft: yalnızca panelde taslak oluşturur, belge kesilmez.
buyernesneEvet*Alıcı (aşağıda). *İhracatta gönderilmez.
linesdiziEvetKalemler, 1-500 (aşağıda).
issueDateYYYY-AA-GGHayırFatura tarihi; boşsa bugün (Türkiye saati). Kurallar aşağıda.
confirmnesneHayır{ "issueDate": true }: onay gerektiren tarih uyarılarını onaylar.
profileTICARIFATURA | TEMELFATURA | IHRACATHayıre-Fatura senaryosu; varsayılan TICARIFATURA. e-Arşiv'de yok sayılır.
invoiceTypeCodeSATIS | IADE | TEVKIFAT | ISTISNAHayırFatura tipi; varsayılan SATIS.
currencyISO 4217HayırVarsayılan TRY.
exchangeRatesayıTRY dışında evet1 birim dövizin TL karşılığı. Kur uydurulmaz; siz gönderirsiniz.
seriesIdmetinHayırGET /series kimliği; boşsa belge türünün varsayılan serisi.
notemetin (≤1000)HayırFaturaya yazılan not.
sendTypeELEKTRONIK | KAGITHayıre-Arşiv gönderim şekli; varsayılan ELEKTRONIK.
internetSalenesneHayıre-Arşiv internet satışı bilgisi (aşağıda). e-Fatura'da yok sayılır.
billingReference{ id, issueDate }IADE'de evetİade edilen faturanın numarası ve tarihi.
orderReference{ id, issueDate }HayırSipariş referansı.
despatchReferencesdizi { id, issueDate }Hayırİrsaliye referansları (en çok 50).
paymentTermsnesneHayırÖdeme koşulları (aşağıda).
exportnesneIHRACAT'ta evetYabancı alıcı ve teslim bilgisi (aşağıda).
buyer#
AlanZorunluAçıklama
taxOrIdNumberHayırVKN (10 hane, tüzel kişi) ya da TCKN (11 hane, gerçek kişi / şahıs firması). Kontrol haneleri denetlenir. Boş: nihai tüketici.
titleVKN'de evetUnvan.
firstName, lastNameTCKN'de / kimliksizde evet**Ya da title (ad soyad olarak bölünür).
taxOfficeHayırVergi dairesinin adı (ör. Kadıköy).
city, district, address, postalCode, countryHayırFatura adresi. Ülke boşsa Türkiye; ISO iki harfli kod da olur. Posta kodu 5 hane.
email, phoneHayırİletişim.
lines[]#
AlanZorunluAçıklama
nameEvetMal / hizmet adı (≤500).
quantityEvetMiktar (> 0, ondalıklı olabilir).
unitPriceExclEvetKDV hariç birim fiyat.
vatRateEvetKDV oranı (0-100). %0'da exemptionCode zorunlu.
unitHayırUBL birim kodu; boşsa C62 (adet). Ör. KGM, MTR, HUR, LTR.
discountHayırSatırın toplam iskontosu (KDV hariç).
targetInclVatHayırKDV dahil hedef satır tutarı (iskonto sonrası). KDV dahil fiyatla satan sistemler için: kalemle tutarlıysa KDV "hedef − matrah" olarak hesaplanır ve kuruş farkı oluşmaz; tutarsızsa yok sayılır.
withholdingCode, withholdingRateHayırKDV tevkifatı (GİB kod listesi; oran %, ör. 9/10 → 90). Fatura tipi TEVKIFAT olmalı.
exemptionCode%0 KDV'de evetİstisna / muafiyet kodu (ör. 301, 351).
extraHayırsellerItemCode, buyerItemCode, brand, model, serials[], lotNumber, expiryDate, gtip (12 hane), note, ihracatta packageId, packageQuantity, packageType.
internetSale (e-Arşiv)#

website (zorunlu, URL), paymentMethod (zorunlu: KREDIKARTI/BANKAKARTI, EFT/HAVALE, KAPIDAODEME, ODEMEARACISI, DIGER), paymentDate (zorunlu, YYYY-AA-GG), paymentAgentName (ODEMEARACISI'nda zorunlu), carrierName, carrierTaxId, shipmentDate.

paymentTerms#

dueDate (YYYY-AA-GG), paymentMeansCode (1 belirtilmemiş, 10 nakit, 20 çek, 42 banka hesabı, 48 kart, 49 doğrudan borç, ZZZ diğer), iban (TR ile 26 karakter), note.

export (yalnızca IHRACAT)#

buyer (name, countryCode, city, address zorunlu; taxId, district, postalCode, email), incoterm (EXW, FCA, FOB, CIF, DAP … INCOTERMS 2020), transportMode (1 denizyolu, 2 demiryolu, 3 karayolu, 4 havayolu, 5 posta, 6 çok araçlı, 7 sabit tesis, 8 iç su). Faturanın alıcısı Gümrük ve Ticaret Bakanlığı'dır; yabancı alıcı export.buyer'dadır. Tip ISTISNA ve kalemlerde exemptionCode beklenir.

Fatura tarihi kuralları#
DurumSonuç
Bugünden ileri tarih, 01.01.2005'ten önce, geçersiz gün422 BUSINESS_RULE_VIOLATION (onayla da kesilmez)
İade faturası iade edilen faturanın tarihinden önce422
Geçmiş yıl tarihi ve o yılın numara serisi eFaturan'da başlatılmamış422
7 günden eski tarih (VUK md. 231)428 ISSUE_DATE_CONFIRMATION_REQUIRED
Geçmiş ay ve o dönemin KDV beyan süresi (izleyen ayın 28'i) geçmiş428
Geçmiş takvim yılı428
Bugün ve 0-7 gün önceSerbest

428 yanıtında uyarılar details içindedir. Uyarıları kullanıcınıza gösterip onay alın, ardından aynı gövdeye "confirm": { "issueDate": true } ekleyerek (aynı Idempotency-Key ile) yeniden gönderin:

JSON
{
  "error": {
    "code": "ISSUE_DATE_CONFIRMATION_REQUIRED",
    "message": "11.11.2026 tarihli fatura için onayınız gerekiyor. …",
    "details": {
      "issueDate": "2026-11-11",
      "warnings": [ { "code": "late", "message": "Fatura, malın teslimi veya hizmetin yapıldığı günden itibaren en geç 7 gün içinde düzenlenmelidir (VUK md. 231). …" } ],
      "notes": []
    },
    "requestId": "req_…"
  }
}

Belgenin saati sorulmaz: gerçek kesim anı yazılır. Numara, fatura tarihinin yılındaki seriden verilir.

Örnek: e-Fatura mükellefi şirkete satış#
JSON
{
  "buyer": {
    "taxOrIdNumber": "1234567890",
    "title": "Örnek Ticaret Ltd. Şti.",
    "taxOffice": "Kadıköy",
    "city": "İstanbul",
    "district": "Kadıköy",
    "address": "Caferağa Mah. Örnek Sok. No: 1",
    "email": "muhasebe@ornek.com.tr"
  },
  "lines": [
    { "name": "Danışmanlık hizmeti", "quantity": 1, "unit": "HUR", "unitPriceExcl": 1000, "vatRate": 20 }
  ],
  "orderReference": { "id": "SIP-1001", "issueDate": "2026-11-19" },
  "note": "Sipariş no: 1001"
}
Örnek: internet satışı (e-Arşiv, KDV dahil fiyat)#
JSON
{
  "buyer": { "firstName": "Ayşe", "lastName": "Yılmaz", "city": "İzmir", "district": "Bornova", "address": "…", "email": "ayse@example.com" },
  "lines": [ { "name": "Seramik kupa", "quantity": 3, "unitPriceExcl": 83.33, "vatRate": 20, "targetInclVat": 300 } ],
  "internetSale": { "website": "https://magazam.com", "paymentMethod": "KREDIKARTI/BANKAKARTI", "paymentDate": "2026-11-20", "carrierName": "Kargo firması" }
}
Yanıt#
  • 201: belge kesildi (outcome: "success", status: "sending"; GİB durumu kendiliğinden takip edilir) ya da taslak oluştu (object: "invoice_draft").
  • 202: entegratörden yanıt alınamadı (outcome: "unknown"). Belge numarasını almış olabilir; durum birkaç dakika içinde kendiliğinden netleşir. Aynı belgeyi yeni anahtarla yeniden kesmeyin; GET /invoices/{id} ya da webhook ile izleyin.

Durumlar: sending (entegratöre iletiliyor) → sent (GİB'e iletildi; ticari faturada alıcı yanıtı bekleniyor) → accepted / rejected; cancelled (e-Arşiv iptali); error (GİB'e ulaşmadı ya da hata; errorMessage).

Taslak (mode: "draft"): belge numara almaz, GİB'e gitmez, kontör düşmez. Panelde Taslaklar listesinde görünür; kontrol edilip panelden kesilir. GET /invoices/{id} taslağı da döndürür (object: "invoice_draft", status: "draft"); listede görünmez. Taslak, oluşturan anahtarın ortamına bağlıdır: öbür ortamın anahtarı göremez (404); test anahtarıyla oluşturulan taslak panelde Test (API) rozetiyle görünür ve panelden yalnızca test ortamında kesilir.

Kontör ve eşzamanlı istekler: kontörlü pakette canlı kesimler hesap başına sırayla işlenir; her istek bakiyeyi bir önceki kesimin düşümünden sonra denetler. Bakiye yetmeyen istek 402 INSUFFICIENT_CREDITS alır, belge kesilmez (paralel istek göndermek bakiyeyi eksiye indirmez).

İstek şeması

application/json · gövde zorunlu

POST /invoices istek şeması
AlanTipDurumAçıklama
Idempotency-Keybaşlık
metinZorunluHer yeni belge için benzersiz değer (ör. UUID); 1-255 görünür ASCII karakter. Aynı değer + aynı gövde → ilk yanıt; farklı gövde → 409.en çok 255 karakter
mode
"issue"|"draft"İsteğe bağlıissue: belgeyi numaralandırıp keser (varsayılan). draft: yalnızca panelde taslak oluşturur, belge kesilmez.varsayılan: "issue"
profile
"TICARIFATURA"|"TEMELFATURA"|"IHRACAT"İsteğe bağlıe-Fatura senaryosu (alıcı e-Fatura mükellefiyse; varsayılan TICARIFATURA). IHRACAT: GTB'ye mal ihracatı faturası (export zorunlu). e-Arşiv'de yok sayılır.
invoiceTypeCode
"SATIS"|"IADE"|"TEVKIFAT"|"ISTISNA"İsteğe bağlıFatura tipi: SATIS, IADE (billingReference zorunlu), TEVKIFAT, ISTISNA.varsayılan: "SATIS"
sendType
"ELEKTRONIK"|"KAGIT"İsteğe bağlıe-Arşiv gönderim şekli; varsayılan ELEKTRONIK.
currency
metinİsteğe bağlıISO 4217 para birimi; varsayılan TRY.biçim: ^[A-Z]{3}$varsayılan: "TRY"
exchangeRate
sayıİsteğe bağlıTRY dışında zorunlu: 1 birim dövizin TL karşılığı.> 0≤ 1000000
seriesId
metinİsteğe bağlıSeri kimliği (GET /series). Boşsa belge türünün varsayılan serisi.en çok 40 karakter
issueDate
tarih (YYYY-AA-GG)İsteğe bağlıFatura tarihi (Türkiye saatiyle YYYY-AA-GG); boşsa bugün. İleri tarih kabul edilmez; 7 günden eski, beyan süresi geçmiş ya da geçmiş yıl tarihi confirm.issueDate ister.
note
metinİsteğe bağlıFatura notu (belgeye yazılır).en çok 1000 karakter
nesneİsteğe bağlıAlıcı. IHRACAT dışında zorunlu.
dizi|nesneZorunluKalemler.1–500 öğe
nesneİsteğe bağlıe-Arşiv internet satışı bilgisi (web adresi, ödeme şekli ve tarihi, taşıyıcı).
nesneİsteğe bağlıYalnızca IHRACAT: yabancı alıcı, teslim şartı (INCOTERMS) ve gönderim şekli.
nesneİsteğe bağlıİade faturasında iade edilen faturanın numarası ve tarihi.
nesneİsteğe bağlıSipariş referansı (numara ve tarih).
dizi|nesneİsteğe bağlıİrsaliye referansları.0–50 öğe
nesneİsteğe bağlıÖdeme koşulları: vade, ödeme şekli kodu, IBAN, not.
nesneİsteğe bağlıAçık onaylar. Onay gerektiren durumda yanıt 428 ISSUE_DATE_CONFIRMATION_REQUIRED olur; ayrıntıdaki uyarılar okunup confirm ile yeniden gönderilir.

Yanıtlar

Yanıt kodları
KodNe zamanGövde
201Belge kesildi (outcome: success) ya da taslak oluştu.application/jsonInvoiceCreateResponse
202Entegratörden yanıt alınamadı; belge numara aldı, durum kendiliğinden takip ediliyor (outcome: unknown).application/jsonInvoiceCreated
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
402Kontör bakiyesi yetersiz (INSUFFICIENT_CREDITS).application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
409Idempotency çakışması ya da ortam için entegratör bağlantısı yok.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
422Doğrulama (VALIDATION_ERROR) ya da iş kuralı (BUSINESS_RULE_VIOLATION).application/jsonError
428Fatura tarihi onay gerektiriyor (ISSUE_DATE_CONFIRMATION_REQUIRED); confirm.issueDate: true ile yeniden gönderin.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması (InvoiceCreated)

75 alan

POST /invoices yanıt şeması (ınvoicecreated)
AlanTipDurumAçıklama
id
metinZorunluFatura kimliği.
object
"invoice"Zorunlu—
environment
"live"|"test"ZorunluAnahtarın ortamı: live (canlı) ya da test.
status
"sending"|"sent"|"accepted"|"rejected"|"cancelled"|"error"Zorunlusending: entegratöre iletiliyor · sent: GİB'e iletildi · accepted · rejected · cancelled · error.
documentType
"e_fatura"|"e_arsiv"ZorunluBelge türü.
profile
"TICARIFATURA"|"TEMELFATURA"|"EARSIVFATURA"|"IHRACAT"Zorunlu—
invoiceTypeCode
metinZorunluSATIS, IADE, TEVKIFAT, ISTISNA.
sendType
"ELEKTRONIK"|"KAGIT"Zorunlu—null olabilir
documentNumber
metinZorunluGİB belge numarası (ör. ABC2026000000001); sonucu belirsiz gönderimde boş olabilir.null olabilir
ettn
metinZorunluEvrensel tekil tanımlama numarası (UUID).null olabilir
issueDate
tarih (YYYY-AA-GG)ZorunluFatura tarihi (Türkiye saatiyle).null olabilir
currency
metinZorunlu—
nesneZorunluTutarlar (belge para biriminde, ondalık).
nesneZorunlu—
source
metinZorunluBelgenin kaynağı: api, manual (panel), marketplace, ecommerce.
errorMessage
metinZorunluHata ya da ret açıklaması.null olabilir
gibStatusCode
metinZorunlu—null olabilir
emailedAt
metinZorunluISO 8601 zaman damgası (UTC).null olabilir
cancelledAt
metinZorunluISO 8601 zaman damgası (UTC).null olabilir
createdAt
metinZorunluISO 8601 zaman damgası (UTC).
updatedAt
metinZorunluISO 8601 zaman damgası (UTC).
nesneZorunlu—
nesneZorunlu—null olabilir
dizi|nesneZorunlu—
outcome
"success"|"unknown"Zorunlusuccess: entegratör kabul etti (201). unknown: yanıt alınamadı, durum takip ediliyor (202).
message
metinZorunlu—

Yanıt şeması (InvoiceDraft)

21 alan

POST /invoices yanıt şeması (ınvoicedraft)
AlanTipDurumAçıklama
id
metinZorunlu—
object
"invoice_draft"Zorunlu—
environment
"live"|"test"ZorunluAnahtarın ortamı: live (canlı) ya da test.
status
"draft"Zorunlu—
documentType
metinZorunlu—
profile
metinZorunlu—
invoiceTypeCode
metinZorunlu—
documentNumber
herhangiZorunlu—
ettn
herhangiZorunlu—
issueDate
metinZorunlu—null olabilir
currency
metinZorunlu—
nesneZorunlu—
nesneZorunlu—
source
"api"Zorunlu—
createdAt
metinZorunluISO 8601 zaman damgası (UTC).
updatedAt
metinZorunluISO 8601 zaman damgası (UTC).
nesneZorunlu—

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

curl -X POST "https://panel.efaturan.com/api/v1/invoices" \
  -H "Authorization: Bearer $EFATURAN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "buyer": {
      "taxOrIdNumber": "1234567890",
      "title": "Örnek Ticaret Ltd. Şti.",
      "taxOffice": "Kadıköy",
      "city": "İstanbul",
      "district": "Kadıköy",
      "address": "Caferağa Mah. Örnek Sok. No: 1",
      "email": "muhasebe@ornek.com.tr"
    },
    "lines": [
      {
        "name": "Danışmanlık hizmeti",
        "quantity": 1,
        "unit": "C62",
        "unitPriceExcl": 1000,
        "vatRate": 20
      }
    ],
    "note": "Sipariş no: 1001"
  }'

Örnek yanıt

201 · application/json
{
  "id": "cmi7x2k1p0003l50ab3c4d5e6",
  "object": "invoice",
  "environment": "live",
  "status": "sending",
  "documentType": "e_fatura",
  "profile": "TICARIFATURA",
  "invoiceTypeCode": "SATIS",
  "sendType": null,
  "documentNumber": "ABC2026000000042",
  "ettn": "3f1c2d4e-5a6b-4c7d-8e9f-0a1b2c3d4e5f",
  "issueDate": "2026-11-20",
  "currency": "TRY",
  "totals": {
    "taxExclusive": 1000,
    "discount": 0,
    "vat": 200,
    "withholding": 0,
    "payable": 1200
  },
  "buyer": {
    "name": "Örnek Ticaret Ltd. Şti.",
    "isCompany": true,
    "taxOrIdNumber": "1234567890",
    "title": "Örnek Ticaret Ltd. Şti.",
    "firstName": null,
    "lastName": null,
    "taxOffice": "Kadıköy",
    "email": "muhasebe@ornek.com.tr",
    "phone": null,
    "country": "Türkiye",
    "city": "İstanbul",
    "district": "Kadıköy",
    "postalCode": null,
    "address": "Caferağa Mah. Örnek Sok. No: 1"
  },
  "references": {
    "billingReference": null,
    "orderReference": {
      "id": "SIP-1001",
      "issueDate": "2026-11-19"
    },
    "despatchReferences": [],
    "paymentTerms": null,
    "exchangeRate": null
  },
  "lines": [
    {
      "name": "Danışmanlık hizmeti",
      "quantity": 1,
      "unit": "HUR",
      "unitPriceExcl": 1000,
      "vatRate": 20,
      "discount": 0,
      "withholdingCode": null,
      "withholdingRate": null,
      "exemptionCode": null,
      "lineTotalExcl": 1000,
      "vat": 200,
      "withholding": 0
    }
  ],
  "source": "api",
  "errorMessage": null,
  "gibStatusCode": null,
  "emailedAt": null,
  "cancelledAt": null,
  "createdAt": "2026-11-20T09:15:00.000Z",
  "updatedAt": "2026-11-20T09:15:00.000Z",
  "links": {
    "self": "/api/v1/invoices/cmi7x2k1p0003l50ab3c4d5e6",
    "pdf": "/api/v1/invoices/cmi7x2k1p0003l50ab3c4d5e6/pdf",
    "xml": "/api/v1/invoices/cmi7x2k1p0003l50ab3c4d5e6/xml"
  },
  "outcome": "success",
  "message": "Fatura entegratöre iletildi; GİB durumu otomatik takip edilecek."
}
GET

Fatura ayrıntısı

Kapsam: invoices:read
GEThttps://panel.efaturan.com/api/v1/invoices/{id}

Kalemler ve alıcı bilgisiyle fatura; ya da API ile oluşturulmuş, henüz kesilmemiş taslak. Başka hesabın ya da öbür ortamın belgesi 404.

Açıklama

Yanıt, POST /invoices yanıtının outcome ve message dışındaki alanlarıdır. Başka hesabın ya da öbür ortamın belgesi 404 NOT_FOUND.

İstek şeması

GET /invoices/{id} istek şeması
AlanTipDurumAçıklama
idyol
metinZorunluFatura kimliği (POST /invoices yanıtındaki id).

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Fatura ya da taslak.application/jsonInvoiceOrDraft
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması (Invoice)

73 alan

GET /invoices/{id} yanıt şeması (ınvoice)
AlanTipDurumAçıklama
id
metinZorunluFatura kimliği.
object
"invoice"Zorunlu—
environment
"live"|"test"ZorunluAnahtarın ortamı: live (canlı) ya da test.
status
"sending"|"sent"|"accepted"|"rejected"|"cancelled"|"error"Zorunlusending: entegratöre iletiliyor · sent: GİB'e iletildi · accepted · rejected · cancelled · error.
documentType
"e_fatura"|"e_arsiv"ZorunluBelge türü.
profile
"TICARIFATURA"|"TEMELFATURA"|"EARSIVFATURA"|"IHRACAT"Zorunlu—
invoiceTypeCode
metinZorunluSATIS, IADE, TEVKIFAT, ISTISNA.
sendType
"ELEKTRONIK"|"KAGIT"Zorunlu—null olabilir
documentNumber
metinZorunluGİB belge numarası (ör. ABC2026000000001); sonucu belirsiz gönderimde boş olabilir.null olabilir
ettn
metinZorunluEvrensel tekil tanımlama numarası (UUID).null olabilir
issueDate
tarih (YYYY-AA-GG)ZorunluFatura tarihi (Türkiye saatiyle).null olabilir
currency
metinZorunlu—
nesneZorunluTutarlar (belge para biriminde, ondalık).
nesneZorunlu—
source
metinZorunluBelgenin kaynağı: api, manual (panel), marketplace, ecommerce.
errorMessage
metinZorunluHata ya da ret açıklaması.null olabilir
gibStatusCode
metinZorunlu—null olabilir
emailedAt
metinZorunluISO 8601 zaman damgası (UTC).null olabilir
cancelledAt
metinZorunluISO 8601 zaman damgası (UTC).null olabilir
createdAt
metinZorunluISO 8601 zaman damgası (UTC).
updatedAt
metinZorunluISO 8601 zaman damgası (UTC).
nesneZorunlu—
nesneZorunlu—null olabilir
dizi|nesneZorunlu—

Yanıt şeması (InvoiceDraft)

21 alan

GET /invoices/{id} yanıt şeması (ınvoicedraft)
AlanTipDurumAçıklama
id
metinZorunlu—
object
"invoice_draft"Zorunlu—
environment
"live"|"test"ZorunluAnahtarın ortamı: live (canlı) ya da test.
status
"draft"Zorunlu—
documentType
metinZorunlu—
profile
metinZorunlu—
invoiceTypeCode
metinZorunlu—
documentNumber
herhangiZorunlu—
ettn
herhangiZorunlu—
issueDate
metinZorunlu—null olabilir
currency
metinZorunlu—
nesneZorunlu—
nesneZorunlu—
source
"api"Zorunlu—
createdAt
metinZorunluISO 8601 zaman damgası (UTC).
updatedAt
metinZorunluISO 8601 zaman damgası (UTC).
nesneZorunlu—

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

ID="…" # Fatura kimliği (POST /invoices yanıtındaki id).

curl "https://panel.efaturan.com/api/v1/invoices/$ID" \
  -H "Authorization: Bearer $EFATURAN_KEY"

Örnek yanıt

Şemadan üretildi: metin alanlarındaki “…” yer tutucudur.

200 · application/json
{
  "id": "…",
  "object": "invoice",
  "environment": "live",
  "status": "sending",
  "documentType": "e_fatura",
  "profile": "TICARIFATURA",
  "invoiceTypeCode": "…",
  "sendType": "ELEKTRONIK",
  "documentNumber": "…",
  "ettn": "…",
  "issueDate": "2026-11-20",
  "currency": "…",
  "totals": {
    "taxExclusive": 0,
    "discount": 0,
    "vat": 0,
    "withholding": 0,
    "payable": 0
  },
  "buyer": {
    "name": "…",
    "isCompany": false,
    "taxOrIdNumber": "…",
    "title": "…",
    "firstName": "…",
    "lastName": "…",
    "taxOffice": "…",
    "email": "…",
    "phone": "…",
    "country": "…",
    "city": "…",
    "district": "…",
    "postalCode": "…",
    "address": "…"
  },
  "source": "…",
  "errorMessage": "…",
  "gibStatusCode": "…",
  "emailedAt": "…",
  "cancelledAt": "…",
  "createdAt": "…",
  "updatedAt": "…",
  "links": {
    "self": "…",
    "pdf": "…",
    "xml": "…"
  },
  "references": {
    "billingReference": {
      "id": "…",
      "issueDate": "…"
    },
    "orderReference": {
      "id": "…",
      "issueDate": "…"
    },
    "despatchReferences": [
      {
        "id": "…",
        "issueDate": "…"
      }
    ],
    "paymentTerms": {
      "dueDate": "…",
      "paymentMeansCode": "…",
      "iban": "…",
      "note": "…"
    },
    "exchangeRate": 0
  },
  "lines": [
    {
      "name": "…",
      "quantity": 0,
      "unit": "…",
      "unitPriceExcl": 0,
      "vatRate": 0,
      "discount": 0,
      "withholdingCode": "…",
      "withholdingRate": 0,
      "exemptionCode": "…",
      "lineTotalExcl": 0,
      "vat": 0,
      "withholding": 0
    }
  ]
}
GET

Fatura PDF'i

Kapsam: invoices:read
GEThttps://panel.efaturan.com/api/v1/invoices/{id}/pdf

Entegratördeki belgenin PDF görüntüsü. Yeni kesilmiş belgede dosya hazır değilse 409.

Açıklama

Dosyayı ek olarak döndürür (application/pdf, application/xml; dosya adı belge numarası). XML, belgenin imzalı UBL-TR hâlidir. Yeni kesilmiş belgede dosya henüz hazır değilse 409 INVALID_STATE: birkaç dakika sonra yeniden deneyin. GİB'e ulaşmamış (error) belgenin dosyası yoktur.

İstek şeması

GET /invoices/{id}/pdf istek şeması
AlanTipDurumAçıklama
idyol
metinZorunluFatura kimliği (POST /invoices yanıtındaki id).

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200PDF dosyası.application/pdf
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Başarılı yanıtın gövdesi dosyanın kendisidir (application/pdf).

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

ID="…" # Fatura kimliği (POST /invoices yanıtındaki id).

curl "https://panel.efaturan.com/api/v1/invoices/$ID/pdf" \
  -H "Authorization: Bearer $EFATURAN_KEY" \
  -o fatura.pdf
GET

Fatura XML'i (UBL-TR)

Kapsam: invoices:read
GEThttps://panel.efaturan.com/api/v1/invoices/{id}/xml

Belgenin imzalı UBL-TR XML'i. Yeni kesilmiş belgede dosya hazır değilse 409.

Açıklama

Dosyayı ek olarak döndürür (application/pdf, application/xml; dosya adı belge numarası). XML, belgenin imzalı UBL-TR hâlidir. Yeni kesilmiş belgede dosya henüz hazır değilse 409 INVALID_STATE: birkaç dakika sonra yeniden deneyin. GİB'e ulaşmamış (error) belgenin dosyası yoktur.

İstek şeması

GET /invoices/{id}/xml istek şeması
AlanTipDurumAçıklama
idyol
metinZorunluFatura kimliği (POST /invoices yanıtındaki id).

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200XML dosyası.application/xml
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Başarılı yanıtın gövdesi dosyanın kendisidir (application/xml).

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

ID="…" # Fatura kimliği (POST /invoices yanıtındaki id).

curl "https://panel.efaturan.com/api/v1/invoices/$ID/xml" \
  -H "Authorization: Bearer $EFATURAN_KEY" \
  -o fatura.xml
POST

e-Arşiv faturasını iptal et

Kapsam: invoices:write
POSThttps://panel.efaturan.com/api/v1/invoices/{id}/cancel

Yalnızca e-Arşiv faturası iptal edilir (e-Fatura iptal edilemez → 409 INVALID_STATE). İptal kontörü geri vermez. Gövde boş olabilir.

Açıklama

Gövde boş olabilir. Yalnızca e-Arşiv faturası iptal edilir. e-Fatura GİB kuralı gereği iptal edilemez (409 INVALID_STATE): alıcı reddeder ya da iade faturası kesilir. Zaten iptal edilmiş ya da hatalı belge 409. İptal kontörü geri vermez. Yanıt: güncel fatura (status: "cancelled").

İstek şeması

application/json · gövde isteğe bağlı · alan yok (boş nesne gönderilebilir)

POST /invoices/{id}/cancel istek şeması
AlanTipDurumAçıklama
idyol
metinZorunluFatura kimliği (POST /invoices yanıtındaki id).
Idempotency-Keybaşlık
metinİsteğe bağlıİsteğe bağlı; verilirse yineleme ilk yanıtı döner.en çok 255 karakter

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200İptal edilen fatura.application/jsonInvoice
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması

73 alan

POST /invoices/{id}/cancel yanıt şeması
AlanTipDurumAçıklama
id
metinZorunluFatura kimliği.
object
"invoice"Zorunlu—
environment
"live"|"test"ZorunluAnahtarın ortamı: live (canlı) ya da test.
status
"sending"|"sent"|"accepted"|"rejected"|"cancelled"|"error"Zorunlusending: entegratöre iletiliyor · sent: GİB'e iletildi · accepted · rejected · cancelled · error.
documentType
"e_fatura"|"e_arsiv"ZorunluBelge türü.
profile
"TICARIFATURA"|"TEMELFATURA"|"EARSIVFATURA"|"IHRACAT"Zorunlu—
invoiceTypeCode
metinZorunluSATIS, IADE, TEVKIFAT, ISTISNA.
sendType
"ELEKTRONIK"|"KAGIT"Zorunlu—null olabilir
documentNumber
metinZorunluGİB belge numarası (ör. ABC2026000000001); sonucu belirsiz gönderimde boş olabilir.null olabilir
ettn
metinZorunluEvrensel tekil tanımlama numarası (UUID).null olabilir
issueDate
tarih (YYYY-AA-GG)ZorunluFatura tarihi (Türkiye saatiyle).null olabilir
currency
metinZorunlu—
nesneZorunluTutarlar (belge para biriminde, ondalık).
nesneZorunlu—
source
metinZorunluBelgenin kaynağı: api, manual (panel), marketplace, ecommerce.
errorMessage
metinZorunluHata ya da ret açıklaması.null olabilir
gibStatusCode
metinZorunlu—null olabilir
emailedAt
metinZorunluISO 8601 zaman damgası (UTC).null olabilir
cancelledAt
metinZorunluISO 8601 zaman damgası (UTC).null olabilir
createdAt
metinZorunluISO 8601 zaman damgası (UTC).
updatedAt
metinZorunluISO 8601 zaman damgası (UTC).
nesneZorunlu—
nesneZorunlu—null olabilir
dizi|nesneZorunlu—

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

ID="…" # Fatura kimliği (POST /invoices yanıtındaki id).

curl -X POST "https://panel.efaturan.com/api/v1/invoices/$ID/cancel" \
  -H "Authorization: Bearer $EFATURAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Örnek yanıt

Şemadan üretildi: metin alanlarındaki “…” yer tutucudur.

200 · application/json
{
  "id": "…",
  "object": "invoice",
  "environment": "live",
  "status": "sending",
  "documentType": "e_fatura",
  "profile": "TICARIFATURA",
  "invoiceTypeCode": "…",
  "sendType": "ELEKTRONIK",
  "documentNumber": "…",
  "ettn": "…",
  "issueDate": "2026-11-20",
  "currency": "…",
  "totals": {
    "taxExclusive": 0,
    "discount": 0,
    "vat": 0,
    "withholding": 0,
    "payable": 0
  },
  "buyer": {
    "name": "…",
    "isCompany": false,
    "taxOrIdNumber": "…",
    "title": "…",
    "firstName": "…",
    "lastName": "…",
    "taxOffice": "…",
    "email": "…",
    "phone": "…",
    "country": "…",
    "city": "…",
    "district": "…",
    "postalCode": "…",
    "address": "…"
  },
  "source": "…",
  "errorMessage": "…",
  "gibStatusCode": "…",
  "emailedAt": "…",
  "cancelledAt": "…",
  "createdAt": "…",
  "updatedAt": "…",
  "links": {
    "self": "…",
    "pdf": "…",
    "xml": "…"
  },
  "references": {
    "billingReference": {
      "id": "…",
      "issueDate": "…"
    },
    "orderReference": {
      "id": "…",
      "issueDate": "…"
    },
    "despatchReferences": [
      {
        "id": "…",
        "issueDate": "…"
      }
    ],
    "paymentTerms": {
      "dueDate": "…",
      "paymentMeansCode": "…",
      "iban": "…",
      "note": "…"
    },
    "exchangeRate": 0
  },
  "lines": [
    {
      "name": "…",
      "quantity": 0,
      "unit": "…",
      "unitPriceExcl": 0,
      "vatRate": 0,
      "discount": 0,
      "withholdingCode": "…",
      "withholdingRate": 0,
      "exemptionCode": "…",
      "lineTotalExcl": 0,
      "vat": 0,
      "withholding": 0
    }
  ]
}
POST

Faturayı e-postayla gönder

Kapsam: invoices:write
POSThttps://panel.efaturan.com/api/v1/invoices/{id}/send-email

PDF ve XML ekli e-posta; her adrese ayrı. Hesap başına saatte 30 gönderim (panelden gönderilenlerle birlikte sayılır). Test ortamı belgesi yalnızca hesabın doğrulanmış e-posta adreslerine gider (başka adres 422); konuda "DENEME" yazar.

Açıklama

En çok 5 adres; her adrese ayrı e-posta, ekinde PDF ve XML. Gönderen adı firmanızın unvanı, yanıtlar firma e-postanıza gider. Yanıt: { "id", "object": "email_delivery", "emails", "sentAt" }.

Test ortamı belgesi yalnızca hesabınızın doğrulanmış e-posta adreslerine (hesap sahibi ve ekip üyeleri) gönderilir; başka adres 422 alır. Konuda ve gövdede "DENEME — resmî belge değildir" yazar.

İstek şeması

application/json · gövde zorunlu

POST /invoices/{id}/send-email istek şeması
AlanTipDurumAçıklama
idyol
metinZorunluFatura kimliği (POST /invoices yanıtındaki id).
Idempotency-Keybaşlık
metinİsteğe bağlıİsteğe bağlı; verilirse yineleme ilk yanıtı döner.en çok 255 karakter
emails
dizi|e-postaZorunluAlıcı adresleri (en çok 5).1–5 öğe

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Gönderildi.application/jsonEmailDelivery
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması

4 alan

POST /invoices/{id}/send-email yanıt şeması
AlanTipDurumAçıklama
id
metinZorunlu—
object
"email_delivery"Zorunlu—
emails
dizi|metinZorunlu—
sentAt
metinZorunluISO 8601 zaman damgası (UTC).

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

ID="…" # Fatura kimliği (POST /invoices yanıtındaki id).

curl -X POST "https://panel.efaturan.com/api/v1/invoices/$ID/send-email" \
  -H "Authorization: Bearer $EFATURAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "muhasebe@ornek.com.tr"
    ]
  }'

Örnek yanıt

Şemadan üretildi: metin alanlarındaki “…” yer tutucudur.

200 · application/json
{
  "id": "…",
  "object": "email_delivery",
  "emails": [
    "…"
  ],
  "sentAt": "…"
}

Mükellef

e-Fatura mükellef sorgusu.

1 uç
GET

e-Fatura mükellef sorgusu

Kapsam: taxpayers:read
GEThttps://panel.efaturan.com/api/v1/taxpayers/{vknTckn}

VKN/TCKN'nin GİB e-Fatura kayıtlı kullanıcı listesinde olup olmadığı, kayıtlı unvan ve posta kutusu etiketleri. Adres ve vergi dairesi döndürülmez. Hesap başına 10 dakikada 120 sorgu.

Açıklama

GİB e-Fatura kayıtlı kullanıcı listesine bakar. documentType, POST /invoices'ın bu alıcı için seçeceği türdür. Vergi dairesi ve adres döndürülmez (kişisel veri). Test anahtarıyla deneme ortamının listesi sorgulanır.

İstek şeması

GET /taxpayers/{vknTckn} istek şeması
AlanTipDurumAçıklama
vknTcknyol
metinZorunlu10 haneli VKN ya da 11 haneli TCKN.

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Sonuç.application/jsonTaxpayer
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması

6 alan

GET /taxpayers/{vknTckn} yanıt şeması
AlanTipDurumAçıklama
object
"taxpayer"Zorunlu—
taxOrIdNumber
metinZorunlu—
isEInvoiceUser
true / falseZorunluGİB e-Fatura kayıtlı kullanıcı listesinde mi?
title
metinZorunluListede kayıtlı unvan / ad soyad.null olabilir
aliases
dizi|metinZorunluPosta kutusu (PK) etiketleri.
documentType
"e_fatura"|"e_arsiv"ZorunluBu alıcıya kesilecek belge türü (etkin etiket yoksa e_arsiv).

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

VKN_TCKN="…" # 10 haneli VKN ya da 11 haneli TCKN.

curl "https://panel.efaturan.com/api/v1/taxpayers/$VKN_TCKN" \
  -H "Authorization: Bearer $EFATURAN_KEY"

Örnek yanıt

200 · application/json
{
  "object": "taxpayer",
  "taxOrIdNumber": "1234567890",
  "isEInvoiceUser": true,
  "title": "ÖRNEK TİCARET LİMİTED ŞİRKETİ",
  "aliases": [
    "urn:mail:defaultpk@ornek.com.tr"
  ],
  "documentType": "e_fatura"
}

Hesap

Hesap, paket, kontör, seriler.

2 uç
GET

Hesap, paket ve kontör

Kapsam: account:read
GEThttps://panel.efaturan.com/api/v1/account

Paket, abonelik, kontör bakiyesi, aylık kota, ortam ve anahtar bilgisi.

Açıklama

Paket ve abonelik (subscription.status: active, trialing, past_due, canceled, expired), kontör bakiyesi (credits.balance) ve bu ortamda kontör düşüp düşmediği, aylık kota, anahtarın ortamı ve kapsamları, entegratör bağlantısının varlığı.

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Hesap.application/jsonAccount
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması

28 alan

GET /account yanıt şeması
AlanTipDurumAçıklama
object
"account"Zorunlu—
nesneZorunlu—null olabilir
nesneZorunlu—null olabilir
nesneZorunlu—
environment
"live"|"test"ZorunluAnahtarın ortamı: live (canlı) ya da test.
integratorConfigured
true / falseZorunluAnahtarın ortamı için entegratör bağlantısı var mı?
nesneZorunlu—
nesneZorunlu—null olabilir
nesneZorunlu—
nesneZorunlu—

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

curl "https://panel.efaturan.com/api/v1/account" \
  -H "Authorization: Bearer $EFATURAN_KEY"

Örnek yanıt

Şemadan üretildi: metin alanlarındaki “…” yer tutucudur.

200 · application/json
{
  "object": "account",
  "company": {
    "title": "…",
    "taxNumber": "…"
  },
  "plan": {
    "code": "…",
    "name": "…"
  },
  "subscription": {
    "status": "…",
    "trialEndsAt": "…",
    "currentPeriodEnd": "…"
  },
  "environment": "live",
  "integratorConfigured": false,
  "credits": {
    "chargedInThisEnvironment": false,
    "balance": 0
  },
  "quota": {
    "monthlyLimit": 0,
    "usedThisMonth": 0
  },
  "apiAccess": {
    "live": false,
    "test": false
  },
  "key": {
    "name": "…",
    "prefix": "…",
    "environment": "live",
    "scopes": [
      "invoices:read"
    ],
    "ipRestricted": false
  }
}
GET

Fatura serileri

Kapsam: account:read
GEThttps://panel.efaturan.com/api/v1/series

Anahtarın ortamındaki etkin e-Fatura ve e-Arşiv serileri (POST /invoices › seriesId).

Açıklama

Anahtarın ortamındaki etkin e-Fatura ve e-Arşiv serileri: { id, documentType, prefix, isDefault }. Seriler panelde Seriler & Şablonlar sayfasında yönetilir.

Yanıtlar

Yanıt kodları
KodNe zamanGövde
200Seriler.application/jsonSeriesList
400Geçersiz istek (INVALID_JSON, IDEMPOTENCY_KEY_REQUIRED, IDEMPOTENCY_KEY_INVALID, INTEGRATOR_REJECTED).application/jsonError
401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.application/jsonError
403IP izin listesi, kapsam, paket hakkı, askı, abonelik ya da canlı anahtar kısıtı.application/jsonError
404Kayıt yok ya da bu hesaba / ortama ait değil.application/jsonError
413Gövde çok büyük.application/jsonError
415Content-Type application/json değil.application/jsonError
429Hız sınırı aşıldı.application/jsonError
500Beklenmeyen hata.application/jsonError
502Entegratöre ulaşılamadı.application/jsonError

Yanıt şeması

9 alan

GET /series yanıt şeması
AlanTipDurumAçıklama
object
"list"Zorunlu—
dizi|nesneZorunlu—
hasMore
falseZorunlu—
nextCursor
herhangiZorunlu—

Örnek istek

Anahtarı kodunuza yazmayın; ortam değişkeninden okuyun.

curl "https://panel.efaturan.com/api/v1/series" \
  -H "Authorization: Bearer $EFATURAN_KEY"

Örnek yanıt

Şemadan üretildi: metin alanlarındaki “…” yer tutucudur.

200 · application/json
{
  "object": "list",
  "data": [
    {
      "id": "…",
      "object": "series",
      "documentType": "…",
      "prefix": "…",
      "isDefault": false
    }
  ],
  "hasMore": false,
  "nextCursor": null
}