Ana içeriğe geç

Fatura oluşturma

Yeni bir fatura kaydı oluşturmak için bu endpoint kullanılır. Gövde; fatura başlığı alanları, en az bir ürün satırı (lines) ve alıcı (customer) nesnesinden oluşur. Alanlara özel notlar aşağıda ilgili bölümlerin başında verilmiştir.

İstek​

POST /api/invoices
Accept: application/json
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Üst düzey alanlar​

AlanTipZorunluAçıklama
typestringEvetFatura tipi; bkz. Sabitler — InvoiceType.
invoice_integration_idnumberKoşulluPanelde tanımlı fatura hesabı (entegrasyon veya e-fatura portalı) kaydının ID’si. workflow_status taslak (predraft) değilse zorunludur.
sale_channel_idnumberHayırSatış kanalı ID’si.
order_idstringHayırHarici sipariş tanımlayıcısı.
order_d_idstringHayırMağaza / kanal sipariş numarası.
order_created_atstringKoşulluorder_id varsa Y-m-d formatında tarih.
currencystringHayırPara birimi (örn. TRY).
currency_ratenumberHayırKur (varsayılan davranış uygulama tarafında).
issue_datestringEvetDüzenleme tarihi Y-m-d, bugünden ileri olamaz.
issue_timestringEvetSaat H:i.
waybill_numberstringHayırİrsaliye no (sayısal string).
waybill_datestringHayırİrsaliye tarihi Y-m-d.
cash_salebooleanEvetPeşin satış mı?
due_datestringKoşullucash_sale: false ise zorunlu (Y-m-d).
payment_datestringKoşullucash_sale: true ise zorunlu (Y-m-d).
callback_urlstringHayırGeçerli URL. Fatura durumu değiştikçe bu adrese bildirim gönderilir — bkz. Callback bildirimi.
descriptionstringHayırAçıklama.
linesarrayEvetEn az bir satır; aşağıdaki tabloya bakın.
is_internet_salebooleanHayırİnternet satışı.
internet_saleobjectKoşulluis_internet_sale: true ise zorunlu.
is_need_shipmentbooleanHayırSevkiyat bilgisi gerekli mi (varsayılan uygulama mantığına bağlı).
shipmentobjectKoşulluSevkiyat gerekiyorsa; firma veya kurye VKN + unvan bilgisi kuralları uygulanır.
customerobjectEvetAşağıdaki customer tablosu; id zorunlu (panel kaydı veya kendi sisteminizdeki tanımlayıcı — bkz. Müşteri eşleştirme).

lines[] satır alanları​

Ürünü önce oluşturmanız gerekmez

Her faturada POST /api/products çağırmanıza gerek yoktur. Satır nesnesinde paneldeki ürüne ait id verebilirsiniz (isteğe bağlı); id verseniz de satırdaki zorunlu alanlar (ad, miktar, birim, birim fiyat, KDV oranı) eksiksiz gönderilmelidir.

AlanTipZorunluAçıklama
idnumberHayırPanelde kayıtlı ürün kartı ID’si. Verildiğinde satırı ürünle ilişkilendirir; yine de aşağıdaki zorunlu fatura alanları (ad, miktar, birim, fiyat, KDV vb.) doldurulmalıdır.
namestringEvetÜrün/hizmet adı.
quantitynumberEvetMiktar, min 1.
unitstringEvetÖlçü birimi (UN/UBL kodu, örn. C62 adet).
unit_pricenumberEvetBirim fiyat ≥ 0.
tax_ratestringEvetKDV oranı: 0, 1, 2, 8, 10, 18, 20.
skustringHayırStok kodu.
descriptionstringHayırSatır açıklaması.
discount_typestringHayıramount veya percentage.
discountnumberHayırİndirim tutarı oranı.
exemption_codestringHayırİstisna kodu.
exemption_reasonstringHayırİstisna gerekçesi.
extra_taxesarrayHayırEk vergiler; her eleman tax_code, tax_rate.

customer alanları​

Müşteriyi önce oluşturmanız gerekmez

customer.id zorunludur ancak müşterinin panelde kayıtlı olması gerekmez: id alanına kendi sisteminizdeki müşteri tanımlayıcısını yazıp tam nesneyi gönderin; eşleşen kayıt yoksa müşteri otomatik oluşturulur. Eşleştirme mantığı için aşağıdaki Müşteri eşleştirme bölümüne bakın.

AlanTipZorunluAçıklama
idnumberEvetMüşteri tanımlayıcısı. Paneldeki müşteri ID’si olabileceği gibi, kendi sisteminizdeki müşteri ID’si de olabilir; eşleşme bulunamazsa müşteri otomatik oluşturulur (aşağıya bakın).
typestringEvetperson veya company.
tax_numberstringEvetVKN/TCKN (10 veya 11 hane).
tax_officestringKoşulluTüzel kişide zorunlu.
titlestringKoşulluTüzel kişide ünvan zorunlu; gerçek kişide ad/soyad.
namestringKoşulluGerçek kişi için ad.
surnamestringKoşulluGerçek kişi için soyad.
countrystringEvetÜlke.
addressstringEvetAdres.
citystringEvetİl.
districtstringEvetİlçe.
postcodestringHayırPosta kodu.
phonestringHayırTelefon.
emailstringHayırE-posta.
ibanstringHayırIBAN.

Müşteri eşleştirme​

Her faturadan önce POST /api/customers çağırmanız gerekmez. Gönderdiğiniz customer nesnesi paneldeki müşteri kartıyla şu sırayla eşleştirilir:

  1. İstekte sale_channel_id varsa → customer.id, o satış kanalına daha önce bağlanan harici müşteri ID'si olarak aranır.
  2. sale_channel_id yoksa → customer.id paneldeki müşteri kaydı ID'si olarak aranır.
  3. Eşleşme yoksa → customer.email ile aranır.
  4. Hâlâ yoksa → customer.tax_number ile aranır (11111111111 hariç).
  5. Hiçbiri eşleşmezse → gönderdiğiniz bilgilerle müşteri otomatik oluşturulur; eşleşme varsa kart gönderdiğiniz bilgilerle güncellenir.

Yani kendi sisteminizdeki müşteri ID'sini customer.id alanına yazıp tam nesneyi göndermeniz yeterlidir.

Fatura tipi (e-Fatura / e-Arşiv) nasıl belirlenir?​

Faturanın e-Fatura mı e-Arşiv mi kesileceğini gövdede belirtmezsiniz; platform bunu otomatik saptar. Fatura işlenirken alıcının VKN/TCKN'si GİB kayıtlı kullanıcı (mükellef) listesinde sorgulanır:

  • Alıcının aktif bir e-Fatura posta kutusu (etiketi) varsa fatura e-Fatura olarak gönderilir.
  • Kayıt yoksa fatura e-Arşiv olarak kesilir.
  • tax_number: "11111111111" (isimsiz/nihai tüketici) her zaman e-Arşiv olur.

internet_sale alanları​

is_internet_sale: true gönderildiğinde bu nesne zorunludur.

AlanTipZorunluAçıklama
web_addressstringHayırSatışın gerçekleştiği web adresi.
payment_methodstringHayırÖdeme yöntemi — bkz. Sabitler: internet_sale.payment_method.
payment_platformstringHayırÖdeme altyapısı / aracı adı (örn. iyzico, stripe). Maks. 255 karakter.
payment_datestringHayırÖdemenin gerçekleştiği tarih (Y-m-d).

shipment alanları​

is_need_shipment: true gönderildiğinde bu nesne zorunludur. Sevkiyatı gerçekleştiren kargo firması bilgileri (company_title + company_tax_number) ya da kurye bilgileri (courier_name + courier_tax_number) çiftinden en az biri eksiksiz doldurulmalıdır; her iki çiftin birden boş gönderilmesi doğrulama hatasına yol açar.

AlanTipZorunluAçıklama
company_titlestringKoşulluKargo firması ünvanı. courier_name verilmemişse zorunlu. Maks. 255 karakter.
company_tax_numberstringKoşulluKargo firması vergi/TC kimlik numarası. company_title ile birlikte doldurulur. Maks. 20 karakter.
courier_namestringKoşulluKurye adı. company_title verilmemişse zorunlu. Maks. 255 karakter.
courier_tax_numberstringKoşulluKurye vergi/TC kimlik numarası. courier_name ile birlikte doldurulur. Maks. 20 karakter.
delivery_datestringEvet*Teslimat tarihi (Y-m-d). is_need_shipment: true ise zorunludur.

Örnek istekler​

<?php
$body = [
    'sale_channel_id'        => 1,
    'invoice_integration_id' => 9,
    'type'                   => 'SATIS',
    'issue_date'             => '2026-04-08',
    'issue_time'             => '14:30',
    'cash_sale'              => true,
    'payment_date'           => '2026-04-08',
    'currency'               => 'TRY',
    'currency_rate'          => 1,
    'is_internet_sale'       => true,
    'internet_sale'          => [
        'web_address'      => 'https://example.com',
        'payment_method'   => 'credit_or_debit',
        'payment_platform' => 'iyzico',
        'payment_date'     => '2026-04-08',
    ],
    'customer' => [
        'id'         => 1002,
        'type'       => 'person',
        'tax_number' => '11111111111',
        'tax_office' => '',
        'name'       => 'Şevket',
        'surname'    => 'Yılmaz',
        'phone'      => '+90 532 123 45 67',
        'email'      => 'sevket@example.com',
        'address'    => 'İstiklal Caddesi No: 10',
        'district'   => 'Beyoğlu',
        'city'       => 'İstanbul',
        'country'    => 'TÜRKİYE',
        'postcode'   => '34000',
        'iban'       => '',
    ],
    'lines' => [
        [
            'id'            => 1001,
            'name'          => 'POS Entegratör Lite',
            'description'   => '',
            'sku'           => '002',
            'quantity'      => 1,
            'unit'          => 'C62',
            'unit_price'    => 5000,
            'discount_type' => 'amount',
            'discount'      => 0,
            'tax_rate'      => 20,
            'extra_taxes'   => [
                ['tax_rate' => 2, 'tax_code' => '0059'],
            ],
        ],
    ],
];

$ch = curl_init('https://app.faturaentegrator.com/api/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST          => true,
    CURLOPT_POSTFIELDS    => json_encode($body),
    CURLOPT_HTTPHEADER    => [
        'Accept: application/json',
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

Örnek yanıt​

Başarılı oluşturmada fatura kaynağı data sarmalayıcısı içinde tek kayıt olarak döner. Alanlar uygulama sürümüne göre genişletilebilir.

{
  "data": {
    "id": 123,
    "team_id": 45,
    "type": "SATIS",
    "invoice_integration_id": 9,
    "sale_channel_id": 1,
    "workflow_status": "processing",
    "formal_status": "pending",
    "ettn": null,
    "serial_number": null,
    "pdf_url": null,
    "currency": "TRY",
    "currency_rate": 1,
    "issue_date": "2026-04-08",
    "issue_time": "14:30",
    "cash_sale": true,
    "payment_date": "2026-04-08",
    "due_date": null,
    "callback_url": "https://example.com/fatura-callback",
    "lines_total": "5000.00",
    "discount_total": "0.00",
    "tax_total": "1000.00",
    "extra_tax_total": "100.00",
    "grand_total": "6100.00",
    "is_internet_sale": true,
    "is_need_shipment": false,
    "receiver": { "name": "Şevket", "surname": "Yılmaz", "tax_number": "11111111111", "...": "..." },
    "lines": [
      { "id": 771, "name": "POS Entegratör Lite", "quantity": 1, "unit_price": "5000.00", "grand_total": "6100.00", "...": "..." }
    ],
    "errors": [],
    "internet_sale": { "web_address": "https://example.com", "...": "..." },
    "shipment": null,
    "created_at": "2026-04-08T14:30:12.000000Z",
    "updated_at": "2026-04-08T14:30:12.000000Z"
  }
}

Önemli alanlar:

AlanAçıklama
idFatura ID'si. Durum sorgulama (GET /api/invoices/{id}) ve callback bildirimi eşleştirmesi için bu değeri saklayın.
workflow_statusOluşturma anında processing döner; iş akışı asenkron ilerler. Değerler için bkz. Sabitler.
formal_statusOluşturma anında pending döner; resmileştirme sonucunu gösterir.
ettn, serial_number, pdf_urlOluşturma yanıtında null döner; resmileştirme tamamlanınca dolar. Bu değerleri callback bildirimi sonrası GET /api/invoices/{id} ile alın.
lines_total, tax_total, grand_total vb.Toplamlar gönderdiğiniz satırlardan sunucu tarafında hesaplanır.
errorsAsenkron işlem hataları burada listelenir — bkz. Hata yanıtları.
ETTN ve fatura numarası yanıtta dönmez

Fatura asenkron resmileştirildiği için ETTN ve fatura numarası ilk yanıtta yer almaz. callback_url tanımlayıp bildirim geldiğinde faturayı tekrar sorgulayın veya GET /api/invoices/{id} ile durumu kontrol edin.