4C e-Fatura Entegrasyon Dokümanları

ApiKey Erişimi ve İş Ortağı Talebi

Web servisleri kullanabilmek için firmanıza özel API anahtarı tanımlanmalıdır. Anahtarınız varsa aşağıdaki alandan hızlıca kontrol edebilirsiniz. Anahtarınız yoksa iş ortağı talep formunu doldurun.

ApiKey Kontrol

İş Ortağı Tanım Formu

VKN / TCKN

Firma Ünvanı

Ad Soyad

E-posta

Telefon

Giriş ve Kimlik Doğrulama

API erişimi kullanıcı adı/şifre ile değil, firma adına üretilen API anahtarı ile yapılır. Anahtar her istekte `Authorization` veya `X-API-Key` header alanlarından biriyle gönderilmelidir.

Authorization: Bearer API_TOKEN
Content-Type: application/json

API token düz metin olarak veritabanında saklanmaz. Kaybolursa eski token pasife alınarak yeni token üretilmelidir.

Token Yetkileri

Yetki	Açıklama
`account.read`	Firma ve token bilgilerini okur.
`credits.read`	Kontör bakiyesi sorgular.
`customers.read`	Müşteri listesi ve müşteri detayı sorgular.
`einvoices.read`	e-Fatura listesi ve detayı sorgular.
`einvoices.write`	e-Fatura taslak oluşturur veya gönderir.
`einvoices.preview`	Hazır UBL XML önizlemesi alır.
`*`	Tüm yetkiler.

Modül Kataloğu

Hızlı Teknoloji RestApi dokümanındaki modüller referans alınarak servis aileleri bizim okunur URL standardımıza çevrilmiştir. Eski uç adlarını sadece karşılaştırma amacıyla gösteriyoruz; entegratörlerin kullanacağı adresler /api/v1 ile başlayan 4C adresleridir. Kaynak karşılaştırma: Hızlı RestApi Swagger.

Durum notu: Bu katalogdaki servis aileleri API route, controller ve feature test kapsamına alınmıştır. Belge üreten servisler portalın mevcut invoices, items, customers, wallets, xslt, doc_prefix ve ilgili yardımcı tablolarıyla çalışır.

Giriş, Hesap ve Token

Entegrasyon firması token doğrulama ve hesap bilgisi işlemleri.

Method	4C URL	Hızlı Karşılığı	Durum	Verilecek / Dönen Veri
GET	`/api/v1/me`	Login / Test	Aktif	Token geçerliliği, firma VKN/TCKN, ünvan, aktiflik ve token yetkileri döner.
POST	`/api/v1/auth/token`	Login	Aktif	Kullanıcı adı/şifre yerine portalda üretilen entegrasyon token yönetimi kullanılacak; dışarı açık login akışı güvenlik onayı sonrası verilecek.

Kontör ve Kullanım

Kalan kontör, hareket ve müşteri bazlı kullanım servisleri.

Method	4C URL	Hızlı Karşılığı	Durum	Verilecek / Dönen Veri
GET	`/api/v1/credits`	KalanKontorSorgula	Aktif	Toplam kontör, harcanan kontör, kalan kontör ve belge türü bazlı kontör maliyetleri döner.
GET	`/api/v1/credits/history`	KontorHareketleri	Aktif	Tarih aralığı, VKN/TCKN ve birim türüne göre kontör hareketleri döner.
GET	`/api/v1/credits/customers/{vkntckn}`	GetCustomerCreditCount	Aktif	Alt müşteri veya bayi için kalan kontör ve belge bazlı limit bilgisi döner.
POST	`/api/v1/credits/topups`	KontorYukle	Aktif	Yetkili bayi kullanımı için VKN/TCKN, kontör türü, adet ve açıklama alır; yükleme sonucunu döndürür.

Müşteri, Cari ve Mükellef

Cari kart, GİB mükellef ve müşteri durum sorguları.

Method	4C URL	Hızlı Karşılığı	Durum	Verilecek / Dönen Veri
GET	`/api/v1/customers`	CariList / MusteriGetir	Aktif	VKN/TCKN, ünvan, ad veya soyad ile arama; cari temel bilgileri ve sayfalama bilgisi döner.
GET	`/api/v1/customers/{vkntckn}`	CariGetById / MusteriGetir	Aktif	Tek cari kaydı; vergi dairesi, adres, ülke, il/ilçe, e-posta, telefon ve etiket bilgileri döner.
POST	`/api/v1/customers`	MusteriOlustur / CariSave	Aktif	VKN/TCKN, ünvan/ad-soyad, vergi dairesi, adres, e-posta, telefon, bayi/müşavir ve sözleşme bilgileri alır.
PATCH	`/api/v1/customers/{vkntckn}/status`	MusteriAktifPasif	Aktif	Müşteriyi aktif/pasif yapar; işlem sonucunu ve güncel durumu döndürür.
POST	`/api/v1/customers/query-taxpayer`	MukellefBilgisiSorgulama	Aktif	VKN/TCKN ile e-Fatura/e-Arşiv/e-İrsaliye mükellefiyet ve GİB posta kutusu bilgisi döner.

e-Fatura ve Genel Belge

Modelden veya UBL XML üzerinden belge oluşturma, listeleme, dosya alma ve iptal.

Method	4C URL	Hızlı Karşılığı	Durum	Verilecek / Dönen Veri
POST	`/api/v1/einvoices`	SendInvoiceModel	Aktif	Fatura başlığı, alıcı, satıcı, satırlar, vergi/istisna, iade, HKS künye ve ek belge alanları alır; taslak veya gönderim sonucu döner.
GET	`/api/v1/einvoices`	GetDocumentList	Aktif	UUID, fatura no, VKN/TCKN, tarih aralığı ve durum filtreleriyle e-Fatura listesi döner.
GET	`/api/v1/einvoices/{uuid}`	GetDocumentListGUID	Aktif	Belge başlığı ve satırları dahil tek e-Fatura detayı döner.
POST	`/api/v1/einvoices/preview-xml`	ControlDocumentXML	Aktif	Hazır UBL XML veya base64 XML alır; GİB/e-Belge önizleme HTML çıktısını base64 döndürür.
POST	`/api/v1/documents/send-xml`	SendDocument	Aktif	UBL XML, belge türü, gönderici/alıcı etiketleri, taslak/gönder bayrakları alır; UUID ve gönderim durumu döner.
GET	`/api/v1/documents/{uuid}/file`	GetDocumentFile / GetDocumentFileJson	Aktif	PDF, HTML, XML veya JSON formatında belge dosyası döner.
POST	`/api/v1/documents/{uuid}/cancel`	CancelDocument / CancelEArsivInvoice	Aktif	İptal tarihi, nedeni ve belge türü alır; iptal/itiraz sonucunu döndürür.
PATCH	`/api/v1/documents/{uuid}/flags`	SetDocumentFlag / SetTakenFromEntegrator	Aktif	Okundu, aktarıldı, muhasebeleşti, yazdırıldı gibi entegrasyon bayraklarını günceller.

Uygulama Yanıtı ve İrsaliye

Ticari fatura kabul/ret yanıtları, irsaliye ve irsaliye yanıtları.

Method	4C URL	Hızlı Karşılığı	Durum	Verilecek / Dönen Veri
POST	`/api/v1/application-responses`	SendApplicationResponse	Aktif	UUID, yanıt tipi, açıklama ve işlem tarihi alır; kabul/ret yanıtı sonucunu döndürür.
POST	`/api/v1/application-responses/xml`	SendApplicationResponseXml	Aktif	Hazır ApplicationResponse XML alır; zarf ve GİB durum bilgisini döndürür.
POST	`/api/v1/despatch-advice`	SendDespatchAdviceModel	Aktif	e-İrsaliye başlık, taşıyıcı, teslimat, satır ve HKS bilgileri alır.
POST	`/api/v1/despatch-responses`	SendReceiptAdviceModel	Aktif	İrsaliye yanıt satırları, kabul/ret miktarı ve açıklamaları alır.
POST	`/api/v1/despatch-advice/{uuid}/convert-invoice`	ConvertDespachsToInvoice	Aktif	İrsaliyeden fatura oluşturma için irsaliye UUID, fatura tipi ve tarih bilgisi alır.

Diğer e-Belge Modülleri

e-Arşiv, e-SMM, e-Müstahsil, e-Adisyon, e-Döviz ve e-Gider Pusulası servisleri.

Method	4C URL	Hızlı Karşılığı	Durum	Verilecek / Dönen Veri
POST	`/api/v1/earchive-invoices`	SendInvoiceModel / ObjectDocument	Aktif	e-Arşiv senaryosu, internet satış alanları, alıcı, satır, vergi ve rapor bilgileri alır.
POST	`/api/v1/esmm-receipts`	SendReceiptModel	Aktif	Serbest meslek makbuzu stopaj, KDV, brüt/net tutar ve alıcı bilgileri alır.
POST	`/api/v1/emustahsil-receipts`	SendCreditNoteModel	Aktif	Müstahsil makbuzu ürün, stopaj, borsa/bağkur kesintisi ve üretici bilgileri alır.
POST	`/api/v1/eadisyon-receipts`	SendReceiptModel	Aktif	e-Adisyon masa/adisyon, ödeme, satır ve vergi bilgileri alır.
POST	`/api/v1/ecurrency-exchanges`	SendCheckModel	Aktif	e-Döviz alım/satım, kur, döviz tutarı ve müşteri kimlik bilgileri alır.
POST	`/api/v1/expense-notes`	SendCreditNoteModel	Aktif	Gider pusulası satır, stopaj/KDV ve mükellef bilgilerini alır.

XSLT, Tasarım, Kod ve Yardımcı Servisler

Tasarım, stok, prefix, kur, dashboard ve e-posta yardımcı servisleri.

Method	4C URL	Hızlı Karşılığı	Durum	Verilecek / Dönen Veri
GET	`/api/v1/xslt`	XsltList	Aktif	Belge türüne göre XSLT şablon listesi ve varsayılan tasarım bilgisi döner.
POST	`/api/v1/xslt`	XsltSave	Aktif	XSLT adı, türü, içerik/base64, logo, kaşe/imza ve renk ayarları alır.
GET	`/api/v1/xslt/{id}/content`	XsltContent	Aktif	Tek tasarımın XSLT içeriğini döndürür.
GET	`/api/v1/codes`	GetCodeList	Aktif	Birim, vergi, istisna, tevkifat, ülke, il/ilçe gibi kod listelerini döndürür.
GET	`/api/v1/prefixes`	PrefixCodeList	Aktif	Fatura ön eki, yıl, sıra ve belge türü bilgilerini döndürür.
POST	`/api/v1/stocks/search`	StockList	Aktif	Stok kodu/adı ve barkod ile ürün/hizmet kartlarını döndürür.
GET	`/api/v1/rates/tcmb`	TcbmKurGetir	Aktif	Tarih, para birimi ve kur tipine göre TCMB kur bilgisini döndürür.
POST	`/api/v1/documents/{uuid}/email`	SetEmailSend / ReSendMail	Aktif	Belge e-posta adresi, konu, mesaj ve ek seçenekleri alır; gönderim durumunu döndürür.
GET	`/api/v1/archive-reports`	SendingArchiveReportList / ArchiveReportPrewiew	Aktif	e-Arşiv rapor listesi, rapor önizleme ve rapor durumlarını döndürür.

Veri Sözlüğü ve Alan Eşleştirme

Entegratörler eski model adlarıyla çalışıyorsa aşağıdaki eşleştirmeyi kullanabilir. Yeni geliştirmelerde sol taraftaki isimler yerine “4C Alanı” sütunundaki JSON alanları tercih edilmelidir.

Swagger Alanı	4C Alanı	Açıklama
`AppType`	`document_type`	efatura, earsiv, esmm, emustahsil, eirsaliye, eadisyon, edoviz veya egider değerlerinden biri.
`SourceUrn`	`sender_tag_id / sender_tag`	Gönderici GİB etiketi. Boş bırakılırsa firmanın ilk aktif gönderici etiketi kullanılır.
`DestinationIdentifier`	`receiver.vkntckn`	Alıcı VKN/TCKN; 10 veya 11 hane zorunludur.
`DestinationUrn`	`receiver_tag`	Alıcı GİB posta kutusu etiketi; e-Fatura gönderiminde zorunlu, e-Arşivde opsiyoneldir.
`InvoiceModel.invoiceheader`	`scenario, invoice_type, invoice_date, currency`	Belge senaryosu, fatura tipi, tarih/saat, para birimi, sipariş ve iade bilgileri.
`InvoiceModel.customer`	`receiver`	Alıcı unvan/ad-soyad, vergi dairesi, adres, ülke, il/ilçe, e-posta ve telefon alanları.
`InvoiceModel.invoiceLines`	`lines[]`	Mal/hizmet adı, miktar, birim, fiyat, iskonto, KDV, istisna kodu, tevkifat ve HKS künye no alanları.
`IsDraft`	`send=false`	Belge taslak kaydedilir; GİB gönderimi yapılmaz.
`IsPreview`	`preview=true veya /preview-xml`	Sadece GİB/e-Belge kural kontrolü ve önizleme amacıyla çalışır.
`IsXml`	`/documents/send-xml`	Model yerine hazır UBL XML gönderilecekse XML uçları kullanılacaktır.

GİB/e-Belge kural kontrolü API tarafında da uygulanır. Örneğin iade faturasında iade edilen fatura bilgisi, KDV oranı 0 olan istisna satırında istisna kodu, HKS satırında künye no zorunlu kabul edilir.

Kontör Sorgulama

GET /credits

Firmanın toplam, harcanan ve kalan kontör bilgisini döndürür.

curl -H "Authorization: Bearer API_TOKEN" \
  https://eportal-test.4cteknoloji.com/api/v1/credits

{
  "credit": 1000,
  "spent": 120,
  "remaining": 880,
  "document_costs": {
    "efatura": {"label": "E-Fatura", "cost": 2},
    "earsiv": {"label": "E-Arşiv", "cost": 1}
  }
}

Müşteri Sorgulama

GET /customers?search={arama}&per_page=50

VKN/TCKN, unvan, ad veya soyad ile müşteri araması yapılır.

curl -H "Authorization: Bearer API_TOKEN" \
  "https://eportal-test.4cteknoloji.com/api/v1/customers?search=0010969949"

GET /customers/{vkntckn}

curl -H "Authorization: Bearer API_TOKEN" \
  https://eportal-test.4cteknoloji.com/api/v1/customers/0010969949

e-Fatura Oluşturma ve Gönderme

POST /einvoices

`send=false` gönderilirse taslak oluşturulur. `send=true` gönderilirse belge, paneldeki “GİB'e Gönder” akışıyla kaydedilir ve e-Fatura kontörü düşülür.

Şube, fatura ön eki ve gönderici etiketi gönderilmezse firmanın ilk uygun tanımları kullanılır. Sayaç veya etiket eksikse API alan bazlı hata döndürür.

{
  "send": true,
  "scenario": "ticari_fatura",
  "invoice_type": "satis",
  "invoice_date": "2026-07-06",
  "invoice_time": "14:30",
  "currency": "TRY",
  "currency_rate": 1,
  "receiver_tag": "urn:mail:defaultpk@gib.gov.tr",
  "receiver": {
    "vkntckn": "11111111111",
    "title": "Örnek Alıcı LTD ŞTİ",
    "country": "TR",
    "city_id": 34,
    "district_id": 430,
    "address": "Beykoz / İstanbul",
    "email": "muhasebe@example.com"
  },
  "lines": [
    {
      "name": "Danışmanlık Hizmeti",
      "quantity": 1,
      "unit": "C62",
      "unit_price": 1000,
      "vat_rate": 20
    }
  ]
}

Özel Durumlar

Durum	Gereken Alan
İade / Tevkifat İade	`return_invoices[].number` ve `return_invoices[].date`
KDV 0 / İstisna	`lines[].exception_code`
Hal Kayıt Sistemi	`lines[].kunye_no`

Hata Kodları

HTTP	Açıklama
`401`	API anahtarı eksik, geçersiz veya süresi dolmuş.
`403`	API anahtarının işlem için yetkisi yok.
`402`	Kontör bakiyesi yetersiz.
`422`	GİB/e-Belge kuralı veya form validasyonu başarısız.
`500`	Beklenmeyen sistem hatası.

{
  "message": "GİB/e-Belge kural kontrolü başarısız.",
  "errors": {
    "return_invoices": [
      "İade faturalarında iade edilen fatura numarası ve tarihi girilmelidir."
    ]
  }
}

Örnek İstekler

Hesap Bilgisi

GET /me

curl -H "Authorization: Bearer API_TOKEN" \
  https://eportal-test.4cteknoloji.com/api/v1/me

Eski tip kullanıcı adı/şifre şifreleme akışı yerine bu API'de Bearer token kullanılır. Token kontrolü için ilk çağrı olarak GET /me önerilir.

e-Fatura Listesi

GET /einvoices?per_page=50

curl -H "Authorization: Bearer API_TOKEN" \
  "https://eportal-test.4cteknoloji.com/api/v1/einvoices?vkntckn=11111111111"

Hazır UBL XML Önizleme

POST /einvoices/preview-xml

{
  "document_type": "efatura",
  "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+..."
}

Servis Testleri

Harici entegrasyon servisleri için feature testleri eklendi. Testler SQLite bellek veritabanında çalışır; canlı müşteri veya fatura verisine dokunmaz.

php artisan test --filter=ExternalApiTest

Kapsam	Kontrol
Kimlik	Token yokken /credits 401 döner; doğru token ile /me firma bilgisini döndürür.
Kontör	/credits, /credits/history, /credits/customers/{vkntckn} ve /credits/topups akışları çalışır.
Müşteri	/customers arama, detay, oluşturma, aktif/pasif ve mükellef/GİB alias sorgusu çalışır.
e-Fatura liste	/einvoices sayfalı liste döndürür; /einvoices/{uuid} satırlarıyla beraber tek belgeyi verir.
e-Belge modülleri	e-Arşiv, e-SMM, e-Müstahsil, e-İrsaliye, e-Adisyon, e-Döviz ve e-Gider Pusulası servisleri kayıt üretir.
Belge işlemleri	Dosya alma, XML alma, bayrak güncelleme, iptal, e-posta kuyruğu ve uygulama yanıtı servisleri çalışır.
Yardımcı servisler	Kod listesi, prefix, stok, GİB kullanıcı, TCMB kur, XSLT ve rapor servisleri yanıt verir.
Doküman sayfası	/IntegrationDocuments sayfası modül kataloğu, ApiKey kontrolü ve iş ortağı formunu içerir.
İş ortağı formu	/IntegrationDocuments/WebServisIstek geçerli talepleri doğrular ve başarı mesajıyla döner.

Canlı Sağlık Kontrolü

curl -i https://eportal-test.4cteknoloji.com/api/v1/credits
# 401 beklenir: API anahtarı zorunlu

curl -H "Authorization: Bearer API_TOKEN" https://eportal-test.4cteknoloji.com/api/v1/me
# 200 beklenir: firma ve token bilgisi döner

Harici Entegrasyon Dokümanları