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 isteklerde kullanılabilir. 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 nesnesinde paneldeki ürün için id verebilirsiniz; 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.
  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.

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.