Fatura oluşturma

Yeni bir fatura kaydı oluşturmak için bu endpoint kullanılır. customer içinde id zorunludur ve alıcı bilgileri gövdede bulunmalıdır; her faturada yeni müşteri oluşturmanız gerekmez. lines içinde panel ürününe ait id kullanabilirsiniz; satırda fatura için zorunlu alanlar yine de eksiksiz gönderilmelidir (her seferinde POST /api/products gerekmez).

İstek

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

Üst düzey alanlar

Alan	Tip	Zorunlu	Açıklama
`type`	string	Evet	Fatura tipi; bkz. Sabitler — InvoiceType.
`invoice_integration_id`	number	Koşullu	Panelde tanımlı fatura hesabı (entegrasyon veya e-fatura portalı) kaydının ID’si. `workflow_status` taslak (`predraft`) değilse zorunludur.
`sale_channel_id`	number	Hayır	Satış kanalı ID’si.
`order_id`	string	Hayır	Harici sipariş tanımlayıcısı.
`order_d_id`	string	Hayır	Mağaza / kanal sipariş numarası.
`order_created_at`	string	Koşullu	`order_id` varsa `Y-m-d` formatında tarih.
`currency`	string	Hayır	Para birimi (örn. `TRY`).
`currency_rate`	number	Hayır	Kur (varsayılan davranış uygulama tarafında).
`issue_date`	string	Evet	Düzenleme tarihi `Y-m-d`, bugünden ileri olamaz.
`issue_time`	string	Evet	Saat `H:i`.
`waybill_number`	string	Hayır	İrsaliye no (sayısal string).
`waybill_date`	string	Hayır	İrsaliye tarihi `Y-m-d`.
`cash_sale`	boolean	Evet	Peşin satış mı?
`due_date`	string	Koşullu	`cash_sale: false` ise zorunlu (`Y-m-d`).
`payment_date`	string	Koşullu	`cash_sale: true` ise zorunlu (`Y-m-d`).
`callback_url`	string	Hayır	Geçerli URL.
`description`	string	Hayır	Açıklama.
`lines`	array	Evet	En az bir satır; aşağıdaki tabloya bakın.
`is_internet_sale`	boolean	Hayır	İnternet satışı.
`internet_sale`	object	Koşullu	`is_internet_sale: true` ise zorunlu.
`is_need_shipment`	boolean	Hayır	Sevkiyat bilgisi gerekli mi (varsayılan uygulama mantığına bağlı).
`shipment`	object	Koşullu	Sevkiyat gerekiyorsa; firma veya kurye VKN + unvan bilgisi kuralları uygulanır.
`customer`	object	Evet	Aşağıdaki customer tablosu; `id` zorunlu (panelde kayıtlı müşteri).

`lines[]` satır alanları

Alan	Tip	Zorunlu	Açıklama
`id`	number	Hayır	Panelde 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.
`name`	string	Evet	Ürün/hizmet adı.
`quantity`	number	Evet	Miktar, min 1.
`unit`	string	Evet	Ölçü birimi (UN/UBL kodu, örn. `C62` adet).
`unit_price`	number	Evet	Birim fiyat ≥ 0.
`tax_rate`	string	Evet	KDV oranı: `0`, `1`, `2`, `8`, `10`, `18`, `20`.
`sku`	string	Hayır	Stok kodu.
`description`	string	Hayır	Satır açıklaması.
`discount_type`	string	Hayır	`amount` veya `percentage`.
`discount`	number	Hayır	İndirim tutarı oranı.
`exemption_code`	string	Hayır	İstisna kodu.
`exemption_reason`	string	Hayır	İstisna gerekçesi.
`extra_taxes`	array	Hayır	Ek vergiler; her eleman `tax_code`, `tax_rate`.

`customer` alanları

Alan	Tip	Zorunlu	Açıklama
`id`	number	Evet	Paneldeki müşteri kaydı ID’si.
`type`	string	Evet	`person` veya `company`.
`tax_number`	string	Evet	VKN/TCKN (10 veya 11 hane).
`tax_office`	string	Koşullu	Tüzel kişide zorunlu.
`title`	string	Koşullu	Tüzel kişide ünvan zorunlu; gerçek kişide ad/soyad.
`name`	string	Koşullu	Gerçek kişi için ad.
`surname`	string	Koşullu	Gerçek kişi için soyad.
`country`	string	Evet	Ülke.
`address`	string	Evet	Adres.
`city`	string	Evet	İl.
`district`	string	Evet	İlçe.
`postcode`	string	Hayır	Posta kodu.
`phone`	string	Hayır	Telefon.
`email`	string	Hayır	E-posta.
`iban`	string	Hayır	IBAN.

`internet_sale` alanları

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

Alan	Tip	Zorunlu	Açıklama
`web_address`	string	Hayır	Satışın gerçekleştiği web adresi.
`payment_method`	string	Hayır	Ödeme yöntemi — bkz. Sabitler: `internet_sale.payment_method`.
`payment_platform`	string	Hayır	Ödeme altyapısı / aracı adı (örn. `iyzico`, `stripe`). Maks. 255 karakter.
`payment_date`	string	Hayı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.

Alan	Tip	Zorunlu	Açıklama
`company_title`	string	Koşullu	Kargo firması ünvanı. `courier_name` verilmemişse zorunlu. Maks. 255 karakter.
`company_tax_number`	string	Koşullu	Kargo firması vergi/TC kimlik numarası. `company_title` ile birlikte doldurulur. Maks. 20 karakter.
`courier_name`	string	Koşullu	Kurye adı. `company_title` verilmemişse zorunlu. Maks. 255 karakter.
`courier_tax_number`	string	Koşullu	Kurye vergi/TC kimlik numarası. `courier_name` ile birlikte doldurulur. Maks. 20 karakter.
`delivery_date`	string	Evet*	Teslimat tarihi (`Y-m-d`). `is_need_shipment: true` ise zorunludur.

Örnek istekler

💻 cURL
🐘 PHP
🟢 Node.js
🐍 Python

curl -X POST "https://app.faturaentegrator.com/api/invoices" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
          }
        ]
      }
    ]
  }'

<?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);

const 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' }],
    },
  ],
};

const res = await fetch('https://app.faturaentegrator.com/api/invoices', {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});
const data = await res.json();

import requests

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'}],
        }
    ],
}

r = requests.post(
    'https://app.faturaentegrator.com/api/invoices',
    json=body,
    headers={'Accept': 'application/json', 'Authorization': 'Bearer YOUR_API_KEY'},
)
data = r.json()

Örnek yanıt

Başarılı oluşturmada fatura kaynağı tek kayıt olarak döner (data); alanlar uygulama sürümüne göre genişletilebilir. Detaylı örnek için Postman dokümantasyonundaki Invoice → store gövdesine bakın.

İstek​

Üst düzey alanlar​

lines[] satır alanları​

customer alanları​

internet_sale alanları​

shipment alanları​

Örnek istekler​

Örnek yanıt​