Yapay Zekâ ile e-Fatura Entegrasyonu

Kendi e-ticaret sitenizi, SaaS ürününüzü ya da CRM'inizi e-Fatura ve e-Arşiv'e bağlamak için kodu sıfırdan yazmanız gerekmez. Faturika panelindeki hazır istemi Claude Code, Codex ya da Cursor gibi bir kod yapay zekâ aracına yapıştırırsınız; araç, Faturika Public API rehberine göre fatura kesme, durum izleme ve hata yönetimi kodunu projenize ekler. Siz planı onaylar, kodu gözden geçirir ve taslakla denersiniz.

Son gözden geçirme: 07.11.2026 · Kaynaklar sayfanın sonunda

Kısaca
  • Hazır istem: Ayarlar › Entegrasyon › "AI ile entegrasyon" (kopyala-yapıştır, kapalı bölüm).
  • Araç iki belgeyi okur: entegrasyon rehberi (Markdown) ve OpenAPI 3.1 tanımı (YAML); ikisi de aynı sayfadan indirilir.
  • API anahtarı isteme yazılmaz; ortam değişkeninden (FATURIKA_API_KEY) okunur.
  • Deneme taslakla yapılır: taslak kontör harcamaz, gönderilen her e-Belge 1 kontördür.
  • Mevzuat kuralları (7 gün, internet satışı bilgileri, alıcıya göre belge türü) istemde ve rehberde; kodu bunlara göre gözden geçirin.

Hangi işletmeler için?

Hazır modülü olmayan her yazılım için: kendi kodladığınız e-ticaret sitesi, abonelik ya da SaaS faturalaması, sipariş paneli, CRM veya ERP. WHMCS, WooCommerce, WiseCP, OpenCart ve PrestaShop kullanıyorsanız hazır modül daha hızlıdır (entegrasyonlar). Pazaryeri siparişleri için panelin kendi kanal bağlantıları yeterlidir (pazaryeri entegrasyonu).

Adım adım kurulum

  1. API anahtarı oluşturun. Panelde Ayarlar › Entegrasyon › Public API Anahtarları bölümünden anahtar oluşturun ve projenizde FATURIKA_API_KEY ortam değişkenine yazın. Mümkünse yalnız gereken kapsamları ve sunucunuzun IP adresini seçin.
  2. Belgeleri projeye koyun. Aynı sayfadan entegrasyon rehberini (entegrasyon-rehberi.md) ve OpenAPI tanımını (openapi.yaml) indirip projenizde docs/faturika/ klasörüne koyun.
  3. İstemi kopyalayıp doldurun. "AI ile entegrasyon" bölümündeki istemi kopyalayın; köşeli parantezli yerlere yazılımınızı, faturanın kesileceği anı ve sipariş verisinin yerini yazın.
  4. Planı onaylayın. İstemi aracınıza yapıştırın. Araç önce planını ve değiştireceği dosyaları özetler; onayladığınızda kodu yazar.
  5. Taslakla deneyin, sonra yayına alın. İlk denemeyi taslak belgeyle yapın (kontör harcamaz), panelde kontrol edin. Kodu gözden geçirip testleri koşturduktan sonra canlıya alın.

Hazır istem neleri ister?

İstem, aracın Faturika API'sinin gerçek kurallarına uymasını sağlayan bir iş tanımıdır. Başlıca maddeler:

Konuİstemdeki kural
BağlantıTaban adres https://faturika.com/papi/v1, her istekte X-Api-Key başlığı, JSON gövde
HazırlıkKurulumda GET /account ile kontör ve eksikleri gösterme
Belge türüAlıcının VKN/TCKN'si POST /taxpayers/query ile sorgulanır; e-Fatura kullanıcısına e-Fatura, değilse e-Arşiv
CariPOST /contacts ile oluştur/güncelle, dönen kimliği kendi müşteri kaydına bağla
FaturaPOST /documents/send; fatura türü her zaman gönderilir, internet satışında ödeme ve teslim bilgileri eklenir
Mükerrer önlemeSipariş başına tek belge; kayıt açan isteklerde amaç başına sabit Idempotency-Key
DurumGönderim asenkron: web kancası (document.status_changed) ya da en sık 60 saniyede bir sorgu; onayda PDF alınır
GüvenlikWeb kancasında X-Faturika-Signature-V2 imza doğrulaması, 5 dakikadan eski istek reddi
HatalarYanıttaki code alanına göre ayrıştırma; uyarı onayı kendiliğinden verilmez, oran sınırında bekleme
DenemeGerçek API ile yalnız taslak; gönderim ve iptal sizin açık onayınızla

Kodu canlıya almadan önce kontrol listesi

  • Tek sipariş, tek fatura: sipariş kaydında belge kimliği (uuid) saklanıyor ve aynı sipariş için ikinci istek aynı tekillik anahtarıyla gidiyor mu?
  • Fatura tarihi: fatura, malın teslimi ya da hizmetin yapılmasından itibaren 7 gün içinde düzenlenir (VUK m.231/5); geç ödenen siparişte tarihin nasıl ele alındığı fatura düzenleme süresi rehberinde.
  • İnternet satışı: e-Arşiv faturada ödeme yöntemi, ödeme tarihi, satışın yapıldığı site ve kargolu satışta taşıyıcı ile gönderim tarihi yer alır (VUK Genel Tebliği 509, IV.2.4.5).
  • Hata gösterimi: başarısız gönderimde dönen kısa Türkçe neden, yöneticiye gösteriliyor mu?
  • Anahtar güvenliği: anahtar kodda, depoda ya da günlükte geçmiyor; yalnız gereken kapsamlar ve sunucu IP'si seçilmiş.
  • Testler: HTTP çağrıları sahte yanıtlarla sınanıyor, testler gerçek API'ye istek atmıyor.

Yapay zekâ ne yapar, siz ne yaparsınız?

Yapay zekâ aracıSiz
Rehberi ve OpenAPI tanımını okur, planı çıkarırFaturanın kesileceği anı ve veri yerini istemde belirtirsiniz
İstemci sınıfını, fatura akışını ve testleri yazarPlanı onaylar, kodu gözden geçirirsiniz
Taslakla deneme yapar (onay verirseniz)Taslağı panelde kontrol edip silersiniz
Kurulum notu ve gereken kapsamları yazarAnahtarı oluşturur, kodu canlıya alırsınız

Uçların tam listesi ve örnek istekler e-Fatura API sayfasında; mevzuat ve teknik kontrol listesinin ayrıntısı API ile e-Fatura entegrasyonu rehberinde.

Sık sorulan sorular

Yapay zekâ ile e-Fatura entegrasyonu nedir?

Kendi yazılımınızı (e-ticaret sitesi, SaaS, CRM) e-Fatura ve e-Arşiv'e bağlayan kodu, Claude Code, Codex ya da Cursor gibi bir kod yapay zekâ aracına hazır bir istemle yazdırmaktır. Araç, Faturika Public API rehberine ve OpenAPI tanımına göre fatura kesme, durum izleme ve hata yönetimi kodunu projenize ekler.

Hazır istemi nereden alırım?

Faturika panelinde Ayarlar › Entegrasyon sayfasındaki "AI ile entegrasyon" bölümünden. Aynı bölümde aracın okuyacağı entegrasyon rehberi ve OpenAPI (YAML) dosyasının indirme düğmeleri de vardır.

API anahtarımı yapay zekâ aracına vermem gerekir mi?

Hayır, vermeyin. Anahtarı projenizde FATURIKA_API_KEY ortam değişkenine yazarsınız; istem, aracın anahtarı koddan değil ortam değişkeninden okumasını ve günlüğe yazmamasını ister.

Deneme yaparken kontör harcanır mı?

Taslak belge kontör harcamaz. İstem, aracın gerçek API ile yalnız taslak oluşturarak denemesini ve kontör harcayan gönderim ile iptal çağrılarını sizin açık onayınız olmadan yapmamasını ister. Her gönderilen e-Belge 1 kontördür.

Yapay zekânın yazdığı kodu doğrudan canlıya alabilir miyim?

Önce gözden geçirin. Mükerrer fatura önlemi (sipariş başına tek belge ve sabit tekillik anahtarı), internet satışı bilgileri ve hata dallarını kontrol edin; testlerin gerçek API'ye istek atmadığından emin olun.

Hangi yazılım dillerinde çalışır?

API standart HTTPS ve JSON kullandığı için dil bağımsızdır: PHP, Node.js, Python, Go, C# ya da Java fark etmez. OpenAPI tanımından istemci kodu da üretilebilir.

Kaynaklar

  1. GİB — 213 sayılı Vergi Usul Kanunu (m.231/5 fatura düzenleme süresi)
  2. GİB — VUK Genel Tebliği Sıra No 509, güncel metin (IV.2.4.5 elektronik ticaret)
  3. GİB — e-Fatura kayıtlı kullanıcı listesi

Son gözden geçirme: 07.11.2026. Bu içerik genel bilgilendirme amaçlıdır; mevzuat değişebilir. Kendi durumunuz için mali müşavirinize danışın.

Ön muhasebenizi bugün dijitale taşıyın

Kredi kartı gerekmeden kaydolun; 2 ay ücretsiz deneyin, 20 hediye kontörle ilk e-belgelerinizi gönderin.