Ana içeriğe geç

Fatura Entegratör API'ye Hoş Geldiniz

Fatura Entegratör API, e-fatura ve e-arşiv süreçlerinizi otomatikleştirmek için REST tabanlı bir arayüz sunar: müşteri ve ürün kayıtları, satış kanalı, fatura hesabı / entegrasyonlar ve fatura oluşturma bu uç noktalar üzerinden yönetilir.

Kapsam

API şu an giden fatura akışını kapsar: satış faturası oluşturma, durum takibi, PDF ve iptal/silme. Gelen e-faturalar (inbox listeleme, kabul/ret/iade yanıtı) için API uç noktası bulunmamaktadır.

Uygulamanın çalışma mantığı​

Tipik akış şöyledir:

  1. Fatura hesabı (öncelikli) — app.faturaentegrator.com panelinde en az bir fatura hesabı tanımlanmalıdır. Bu kayıt bir entegratör entegrasyonu veya e-fatura portalı bağlantısı olarak eklenebilir; API’de invoice_integration_id olarak kullanılır. ID’yi panelden veya GET /api/integrations/invoice yanıtından alırsınız.
  2. Hesap oturumu — Aynı panelde kullanıcı hesabınızla giriş yaparsınız (bu, API ile karıştırılmamalıdır).
  3. Satış kanalı ve API anahtarı — Harici sistemi eşlemek için satış kanalı tanımlanır. Kanal ID’si fatura gövdesinde sale_channel_id olarak zorunludur. API anahtarı entegrasyon / API ayarları üzerinden üretilir; isteklerde şifre veya oturum çerezi yerine bu anahtar kullanılır.
  4. Müşteri (customer.id) — Fatura gövdesinde customer.id zorunludur; müşteri bilgileri de istekte bulunmalıdır. Müşteriyi önceden POST /api/customers ile oluşturmanız gerekmez: id alanına kendi sisteminizdeki müşteri tanımlayıcısını yazabilirsiniz; eşleşen kayıt bulunamazsa müşteri otomatik oluşturulur (bkz. Müşteri eşleştirme).
  5. Ürün satırları (lines) — Her faturada POST /api/products ile yeni ürün oluşturmanız gerekmez. Satır nesnesindeki id, sale_channel_id gönderdiğinizde zorunludur ve paneldeki ürün ID’si ya da kendi sisteminizdeki ürün tanımlayıcısı olabilir; buna ek olarak faturanın işlenmesi için gerekli alanlar (ürün/hizmet adı, miktar, birim, birim fiyat, KDV oranı vb.) gövdede eksiksiz gönderilmelidir. KDV oranı 0 olan satırlarda ayrıca istisna kodu ve gerekçesi zorunludur (bkz. istisna kodları).
  6. Fatura oluşturma — POST /api/invoices ile gönderilir. İşlem durumu workflow_status ve formal_status ile takip edilir. İsteğe bağlı callback_url ile sonuç bildirimi alınabilir (bkz. Callback bildirimi).
  7. e-Fatura / e-Arşiv seçimi otomatiktir — Alıcının e-fatura mükellefi olup olmadığı GİB kayıtlı kullanıcı listesinden platform tarafından sorgulanır; gövdede fatura tipi (e-Fatura/e-Arşiv) belirtmezsiniz. Ayrıntı için fatura oluşturma sayfasına bakın.

Siparişlerinizi hangi yöntemle aktarırsınız?​

Faturayı doğrudan POST /api/invoices ile oluşturabileceğiniz gibi, önce siparişi panele aktarıp faturayı oradan üretebilirsiniz. Sipariş aktarımının iki yolu vardır:

YöntemNasıl çalışırNe zaman tercih edilir
API ile gönderim (push) — POST /api/ordersSipariş oluştuğunda siz platforma istek atarsınız.Sipariş anında aktarılsın, akışı siz kontrol edin istiyorsanız.
JSON Feed (pull) — feed entegrasyonuSiparişlerinizi bir JSON adresinde yayınlarsınız; platform saatte bir bu adresi okur.Dışarıya istek atamayan sistemlerde ya da tek bir uç nokta yazıp gerisini platforma bırakmak istiyorsanız.

Her iki yolda da sipariş panele düştükten sonra fatura, otomatik faturalama ayarınızla veya siparişten fatura oluşturma ile üretilir.

Adım adım başlarken​

1. Panel ve API anahtarı​

  • app.faturaentegrator.com adresinden giriş yapın.
  • Önce panel üzerinden fatura hesabınızı (entegrasyon veya e-fatura portalı) ekleyin.
  • API anahtarını API / entegrasyon ayarları sayfasından oluşturun veya kopyalayın. İsteklerde bu değeri Authorization başlığına eklemeniz gerekir (bkz. Kimlik Doğrulama).
  • Base URL: https://app.faturaentegrator.com/api

Test ortamı: Dummy Fatura​

Ayrı bir test/staging sunucusu yoktur; test de canlı adres (https://app.faturaentegrator.com/api) üzerinden, gerçek GİB akışına bağlanmayan Dummy Fatura entegrasyonuyla yapılır:

  • Kota düşmez — Dummy Fatura ile oluşturulan işlemler, canlı fatura kotanızdan veya ücretlendirme paketinizden düşmez (test amaçlıdır).
  • Akışı panelden izleyin — Paneldeki fatura listesi ve detay ekranlarından test faturalarının durumunu (workflow_status, formal_status vb.) takip edebilirsiniz.
  • Callback ile test — Fatura oluştururken callback_url tanımlayarak, işlem sonuçlarının kendi sisteminize nasıl iletileceğini gerçek resmileştirme açmadan doğrulayabilirsiniz (bkz. Callback bildirimi).

Dummy Fatura kurulumu​

  1. Panelde fatura hesabı ekleme ekranından Dummy Fatura entegrasyonunu ekleyin.
  2. Eklenen hesabın ID'sini panelden veya GET /api/integrations/invoice yanıtından alın; bu değeri isteklerde invoice_integration_id olarak kullanın.
  3. API anahtarınızı üretin ve POST /api/invoices isteğini Dummy hesabın ID'siyle gönderin.
  4. Canlıya geçerken yalnızca invoice_integration_id değerini gerçek entegratör/portal hesabınızın ID'siyle değiştirmeniz yeterlidir.

Örnek istekler için Postman dokümantasyonuna bakın.

Postman ile deneyin​

Fatura Entegratör — Postman Dokümantasyonu

Destek​

Destek için bizimle iletişime geçin

Teknik destek ve entegrasyon sorularınız için destek@faturaentegrator.com veya destek@gurmehub.com adreslerine yazabilirsiniz.

Sonraki adım​

Kimlik Doğrulama sayfasında API anahtarını Authorization başlığına ekleme biçimini ve örnek istekleri inceleyin.