Fatura Oluşturma

Yeni satış faturası oluşturun ve GİB'e gönderime hazırlayın.

Endpoint

POST /kolaybi/v1/invoices

Parametreler

Zorunlu Alanlar

Parametre	Tip	Zorunlu	Açıklama
`contact_id`	integer	Evet	Müşteri/cari ID
`address_id`	integer	Evet	Fatura adresi ID
`order_date`	datetime	Evet	Fatura tarihi (YYYY-MM-DD)
`currency`	Currency	Evet	Fatura para birimi
`items`	array	Evet	En az bir kalem içermeli. Detaylar için Fatura Kalemleri bölümüne bakın.

Fatura Kalemleri

Alan	Tip	Zorunlu	Açıklama
`product_id`	integer	Evet	Ürün ID
`quantity`	string	Evet	Miktar (örn: "1.00")
`unit_price`	string	Evet	Birim fiyat (örn: "100.00")
`vat_rate`	VATRate	Evet	KDV oranı
`description`	string	Hayır	Kalem açıklaması
`discount_amount`	number	Hayır	Satır indirimi (TRY)
`gtip_no`	number	Hayır	İhracat için 12 haneli GTIP numarası

Opsiyonel Temel Alanlar

Parametre	Tip	Zorunlu	Açıklama
`serial_no`	string	Hayır	Özel seri numarası
`due_date`	datetime	Hayır	Vade tarihi
`description`	string	Hayır	Fatura açıklaması
`receiver_email`	string	Hayır	E-fatura/e-arşiv alıcısı
`type`	InvoiceType	Hayır	Varsayılan `sale_invoice`
`tracking_currency`	Currency	Hayır	Tahsilat kasası para birimi
`tags`	array	Hayır	Etiket ID listesi (`tags[0]`, `tags[1]`)
`subtotal_discount_amount`	number	Hayır	Genel iskonto tutarı (TRY)
`subtotal_correction_amount`	number	Hayır	Yuvarlama tutarı (TRY)

Kur & Para Birimi Alanları

Parametre	Tip	Zorunlu	Açıklama
`exchange_rate`	string	Hayır	Şirket para biriminin fatura para birimine oranı (örn: TRY/EUR). Aynı para biriminde gereksiz.
`cross_currency_rate`	string	Hayır	Şirket + fatura para birimlerinden biri TRY değilse zorunlu; `fatura para birimi / TRY` oranı.

E-Belge Senaryo Alanları

Parametre	Tip	Zorunlu	Açıklama
`document_scenario`	string	Hayır	Varsayılan `TICARIFATURA`. Temel fatura için `TEMELFATURA`, ilaç faturası için `ILAC_TIBBICIHAZ` gönderin.
`document_type`	string	Hayır	Varsayılan `SATIS`. `ISTISNA`, `TEVKIFAT`, `OZELMATRAH`, `IHRACKAYITLI` vb. değerler destekli.
`vat_exemption_reason_code`	string	Hayır	`document_type = ISTISNA` olduğunda zorunlu hale gelir.
`shipment_include`	boolean	Hayır	`true` -> açıklamalara “İrsaliye yerine geçer” eklenir.

Özel Matrah Alanları (`document_type = OZELMATRAH`)

Parametre	Tip	Zorunlu	Açıklama
`special_tax_base[reason_code]`	string	Hayır	Özel matrah kodu
`special_tax_base[total]`	string	Hayır	Matrah tutarı
`special_tax_base[percentage]`	string	Hayır	Matrah yüzdesi
`special_tax_base[vat]`	string	Hayır	Hesaplanan vergi

İnternet Satışı Alanları

Parametre	Tip	Zorunlu	Açıklama
`internet_sale[url]`	string	Hayır	Satışın yapıldığı web adresi
`internet_sale[payment_type]`	string	Hayır	`credit-card`, `bank-transfer`, `pay-at-door`, `payment-platform`
`internet_sale[payment_platform]`	string	Hayır	Kullanılan ödeme platformu
`internet_sale[payment_date]`	date	Hayır	Ödeme tarihi

İnternet Satışı Kargo Alanları

Parametre	Tip	Zorunlu	Açıklama
`internet_sale_shipment[carrier_company]`	string	Hayır	Taşıyıcı firma
`internet_sale_shipment[carrier_person]`	string	Hayır	Taşıyıcı kişi
`internet_sale_shipment[carrier_company_tax_number]`	string	Hayır	Taşıyıcı VKN
`internet_sale_shipment[carrier_date]`	date	Hayır	Sevk tarihi

İhracat Taşıma Bilgileri

Parametre	Tip	Zorunlu	Açıklama
`handling_and_shipping_information[delivery_condition]`	string	Hayır	İhracat teslim şartı (`FAS`, `FOB`, `DDU`, `DDP`, `EXW`, `DEQ`, `CFR`)
`handling_and_shipping_information[shipping_method]`	integer	Hayır	Gönderim şekli (`1` Deniz, `2` Demir, `3` Kara, `4` Hava, `5` Posta, `6` Çok Araçlı, `7` Sabit Tesis)
`handling_and_shipping_information[shipping_method_detail]`	string	Hayır	Gönderim şekli açıklaması (yalnızca 1-4 için)
`handling_and_shipping_information[freight]`	string	Hayır	Navlun bedeli
`handling_and_shipping_information[insurance_amount]`	string	Hayır	Sigorta bedeli

İlaç/Tıbbi Cihaz Kalem Alanları (`document_scenario = ILAC_TIBBICIHAZ`)

document_scenario = ILAC_TIBBICIHAZ olduğunda, her kalem için aşağıdaki alanlar kullanılabilir:

Not: identifications alanı en az 1 ürün bilgisi içermelidir. Fatura kaleminde belirttiğiniz quantity değeri kadar identification bilgisi ekleyebilirsiniz.

Parametre	Tip	Zorunlu	Açıklama
`items[n][medicine_medicaldevice_type]`	string	Evet	`medicine` veya `medical_device` değerlerinden biri girilmeli.

İlaç Identification Alanları (`medicine_medicaldevice_type = medicine`)

medicine_medicaldevice_type = medicine olduğunda, aşağıdaki identification alanları zorunludur:

Parametre	Tip	Zorunlu	Açıklama
`items[n][identifications][*][bn]`	string	Evet	Parti Numarası (Batch Number)
`items[n][identifications][*][gtin]`	string	Evet	Küresel Ticari Ürün Numarası (GTIN)
`items[n][identifications][*][sn]`	string	Evet	Sıra Numarası (Serial Number)
`items[n][identifications][*][xd]`	date	Evet	Son Kullanma Tarihi (Expiration Date - YYYY-MM-DD)

Tıbbi Cihaz Identification Alanları (`medicine_medicaldevice_type = medical_device`)

medicine_medicaldevice_type = medical_device olduğunda, aşağıdaki identification alanları zorunludur:

Parametre	Tip	Zorunlu	Açıklama
`items[n][identifications][*][uno]`	string	Evet	Ürün Numarası (UNO)
`items[n][identifications][*][lno]`	string	Evet	Lot/Batch Numarası (LNO)
`items[n][identifications][*][sno]`	string	Evet	Seri/Sıra Numarası (SNO).
`items[n][identifications][*][urt]`	date	Evet	Üretim Tarihi (URT - YYYY-MM-DD)

Örnekler

cURL
JavaScript
PHP
Python
C#

# Temel fatura oluşturma
curl -X POST "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "contact_id=1&address_id=1&order_date=2024-01-15&currency=try&items[0][product_id]=1&items[0][quantity]=2&items[0][unit_price]=100.00&items[0][vat_rate]=20"

# Detaylı fatura oluşturma
curl -X POST "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "contact_id=1&address_id=1&order_date=2024-01-15&currency=eur&tracking_currency=try&tags[0]=12&tags[1]=15&serial_no=KBI2024-0001&due_date=2024-02-15&description=Test faturası&receiver_email=customer@example.com&type=sale_invoice&subtotal_discount_amount=50&exchange_rate=33.52&cross_currency_rate=33.52&document_scenario=TICARIFATURA&document_type=SATIS&internet_sale[url]=https://shop.example.com&internet_sale[payment_type]=credit-card&internet_sale[payment_date]=2024-01-15&internet_sale_shipment[carrier_company]=PTT&internet_sale_shipment[carrier_date]=2024-01-16&items[0][product_id]=1&items[0][quantity]=2&items[0][unit_price]=100.00&items[0][vat_rate]=20&items[0][description]=Test ürün&items[0][gtip_no]=123456789012&items[1][product_id]=2&items[1][quantity]=1&items[1][unit_price]=50.00&items[1][vat_rate]=18"

# İlaç faturası oluşturma
curl --location 'https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Channel: YOUR_CHANNEL' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-urlencode 'contact_id=38' \
  --data-urlencode 'address_id=59' \
  --data-urlencode 'order_date=2025-12-01' \
  --data-urlencode 'currency=TRY' \
  --data-urlencode 'items[0][product_id]=3' \
  --data-urlencode 'items[0][quantity]=2' \
  --data-urlencode 'items[0][unit_price]=100.00' \
  --data-urlencode 'items[0][vat_rate]=20' \
  --data-urlencode 'items[0][medicine_medicaldevice_type]=medicine' \
  --data-urlencode 'items[0][identifications][0][bn]=abc' \
  --data-urlencode 'items[0][identifications][0][gtin]=abc' \
  --data-urlencode 'items[0][identifications][0][sn]=abc' \
  --data-urlencode 'items[0][identifications][0][xd]=2025-11-01' \
  --data-urlencode 'invoice_scenario=ILAC_TIBBICIHAZ'

# Tıbbi cihaz faturası oluşturma
curl --location 'https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --header 'Channel: YOUR_CHANNEL' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --data-urlencode 'contact_id=38' \
  --data-urlencode 'address_id=59' \
  --data-urlencode 'order_date=2025-12-01' \
  --data-urlencode 'currency=TRY' \
  --data-urlencode 'items[0][product_id]=4' \
  --data-urlencode 'items[0][quantity]=1' \
  --data-urlencode 'items[0][unit_price]=200.00' \
  --data-urlencode 'items[0][vat_rate]=20' \
  --data-urlencode 'items[0][medicine_medicaldevice_type]=medical_device' \
  --data-urlencode 'items[0][identifications][0][uno]=UNO123456' \
  --data-urlencode 'items[0][identifications][0][lno]=LNO789012' \
  --data-urlencode 'items[0][identifications][0][sno]=SNO345678' \
  --data-urlencode 'items[0][identifications][0][urt]=2024-01-01' \
  --data-urlencode 'invoice_scenario=ILAC_TIBBICIHAZ'

async function createInvoice(data) {
  const formData = new URLSearchParams();

  // Ana parametreler
  formData.append("contact_id", data.contact_id);
  formData.append("address_id", data.address_id);
  formData.append("order_date", data.order_date);
  formData.append("currency", data.currency);

  // Opsiyonel parametreler
  if (data.serial_no) formData.append("serial_no", data.serial_no);
  if (data.due_date) formData.append("due_date", data.due_date);
  if (data.description) formData.append("description", data.description);
  if (data.receiver_email)
    formData.append("receiver_email", data.receiver_email);
  if (data.type) formData.append("type", data.type);
  if (data.tracking_currency)
    formData.append("tracking_currency", data.tracking_currency);
  if (data.subtotal_discount_amount)
    formData.append(
      "subtotal_discount_amount",
      data.subtotal_discount_amount
    );
  if (data.subtotal_correction_amount)
    formData.append(
      "subtotal_correction_amount",
      data.subtotal_correction_amount
    );
  if (data.exchange_rate)
    formData.append("exchange_rate", data.exchange_rate);
  if (data.cross_currency_rate)
    formData.append("cross_currency_rate", data.cross_currency_rate);
  if (data.document_scenario)
    formData.append("document_scenario", data.document_scenario);
  if (data.document_type)
    formData.append("document_type", data.document_type);
  if (data.vat_exemption_reason_code)
    formData.append(
      "vat_exemption_reason_code",
      data.vat_exemption_reason_code
    );
  if (typeof data.shipment_include !== "undefined")
    formData.append("shipment_include", data.shipment_include);

  if (Array.isArray(data.tags)) {
    data.tags.forEach((tagId, index) =>
      formData.append(`tags[${index}]`, tagId)
    );
  }

  if (data.special_tax_base) {
    Object.entries(data.special_tax_base).forEach(([key, value]) => {
      formData.append(`special_tax_base[${key}]`, value);
    });
  }

  if (data.internet_sale) {
    Object.entries(data.internet_sale).forEach(([key, value]) => {
      formData.append(`internet_sale[${key}]`, value);
    });
  }

  if (data.internet_sale_shipment) {
    Object.entries(data.internet_sale_shipment).forEach(([key, value]) => {
      formData.append(`internet_sale_shipment[${key}]`, value);
    });
  }

  if (data.handling_and_shipping_information) {
    Object.entries(data.handling_and_shipping_information).forEach(
      ([key, value]) => {
        formData.append(`handling_and_shipping_information[${key}]`, value);
      }
    );
  }

  // Fatura kalemleri
  data.items.forEach((item, index) => {
    formData.append(`items[${index}][product_id]`, item.product_id);
    formData.append(`items[${index}][quantity]`, item.quantity);
    formData.append(`items[${index}][unit_price]`, item.unit_price);
    formData.append(`items[${index}][vat_rate]`, item.vat_rate);
    if (item.description)
      formData.append(`items[${index}][description]`, item.description);
    if (item.discount_amount)
      formData.append(`items[${index}][discount_amount]`, item.discount_amount);
    if (item.medicine_medicaldevice_type)
      formData.append(`items[${index}][medicine_medicaldevice_type]`, item.medicine_medicaldevice_type);
    if (Array.isArray(item.identifications)) {
      item.identifications.forEach((identification, idIndex) => {
        if (identification.bn)
          formData.append(`items[${index}][identifications][${idIndex}][bn]`, identification.bn);
        if (identification.gtin)
          formData.append(`items[${index}][identifications][${idIndex}][gtin]`, identification.gtin);
        if (identification.sn)
          formData.append(`items[${index}][identifications][${idIndex}][sn]`, identification.sn);
        if (identification.xd)
          formData.append(`items[${index}][identifications][${idIndex}][xd]`, identification.xd);
        if (identification.uno)
          formData.append(`items[${index}][identifications][${idIndex}][uno]`, identification.uno);
        if (identification.lno)
          formData.append(`items[${index}][identifications][${idIndex}][lno]`, identification.lno);
        if (identification.sno)
          formData.append(`items[${index}][identifications][${idIndex}][sno]`, identification.sno);
        if (identification.urt)
          formData.append(`items[${index}][identifications][${idIndex}][urt]`, identification.urt);
      });
    }
  });

  const response = await fetch(
    "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        Channel: channel,
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: formData,
    }
  );

  return await response.json();
}

// Kullanım
const invoice = await createInvoice({
  contact_id: 1,
  address_id: 1,
  order_date: "2024-01-15",
  currency: "try",
  items: [
    {
      product_id: 1,
      quantity: "2",
      unit_price: "100.00",
      vat_rate: "20",
    },
  ],
});

// İlaç faturası kullanımı
const medicineInvoice = await createInvoice({
  contact_id: 1,
  address_id: 1,
  order_date: "2024-01-15",
  currency: "try",
  document_scenario: "ILAC_TIBBICIHAZ",
  items: [
    {
      product_id: 1,
      quantity: "1",
      unit_price: "150.00",
      vat_rate: "20",
      medicine_medicaldevice_type: "medicine",
      identifications: [
        {
          bn: "LOT123456",
          gtin: "12345678901234",
          sn: "SN123456",
          xd: "2025-12-31",
        },
      ],
    },
  ],
});

// Tıbbi cihaz faturası kullanımı
const medicalDeviceInvoice = await createInvoice({
  contact_id: 1,
  address_id: 1,
  order_date: "2024-01-15",
  currency: "try",
  document_scenario: "ILAC_TIBBICIHAZ",
  items: [
    {
      product_id: 2,
      quantity: "1",
      unit_price: "200.00",
      vat_rate: "20",
      medicine_medicaldevice_type: "medical_device",
      identifications: [
        {
          uno: "UNO123456",
          lno: "LNO789012",
          sno: "SNO345678",
          urt: "2024-01-01",
        },
      ],
    },
  ],
});

function createInvoice($data) {
    $url = 'https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices';

    $postData = [
        'contact_id' => $data['contact_id'],
        'address_id' => $data['address_id'],
        'order_date' => $data['order_date'],
        'currency' => $data['currency']
    ];

    // Opsiyonel parametreler
    if (isset($data['serial_no'])) $postData['serial_no'] = $data['serial_no'];
    if (isset($data['due_date'])) $postData['due_date'] = $data['due_date'];
    if (isset($data['description'])) $postData['description'] = $data['description'];
    if (isset($data['receiver_email'])) $postData['receiver_email'] = $data['receiver_email'];
    if (isset($data['type'])) $postData['type'] = $data['type'];

    // Fatura kalemleri
    foreach ($data['items'] as $index => $item) {
        $postData["items[{$index}][product_id]"] = $item['product_id'];
        $postData["items[{$index}][quantity]"] = $item['quantity'];
        $postData["items[{$index}][unit_price]"] = $item['unit_price'];
        $postData["items[{$index}][vat_rate]"] = $item['vat_rate'];
        if (isset($item['description'])) $postData["items[{$index}][description]"] = $item['description'];
        if (isset($item['discount_amount'])) $postData["items[{$index}][discount_amount]"] = $item['discount_amount'];
    }

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($postData),
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
            'Channel: ' . $channel,
            'Content-Type: application/x-www-form-urlencoded'
        ],
        CURLOPT_RETURNTRANSFER => true
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    return json_decode($response, true);
}

import requests

def create_invoice(data):
    url = "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Channel": channel,
        "Content-Type": "application/x-www-form-urlencoded"
    }

    post_data = {
        "contact_id": data["contact_id"],
        "address_id": data["address_id"],
        "order_date": data["order_date"],
        "currency": data["currency"]
    }

    # Opsiyonel parametreler
    if "serial_no" in data:
        post_data["serial_no"] = data["serial_no"]
    if "due_date" in data:
        post_data["due_date"] = data["due_date"]
    if "description" in data:
        post_data["description"] = data["description"]
    if "receiver_email" in data:
        post_data["receiver_email"] = data["receiver_email"]
    if "type" in data:
        post_data["type"] = data["type"]

    # Fatura kalemleri
    for index, item in enumerate(data["items"]):
        post_data[f"items[{index}][product_id]"] = item["product_id"]
        post_data[f"items[{index}][quantity]"] = item["quantity"]
        post_data[f"items[{index}][unit_price]"] = item["unit_price"]
        post_data[f"items[{index}][vat_rate]"] = item["vat_rate"]
        if "description" in item:
            post_data[f"items[{index}][description]"] = item["description"]
        if "discount_amount" in item:
            post_data[f"items[{index}][discount_amount]"] = item["discount_amount"]

    response = requests.post(url, headers=headers, data=post_data)
    return response.json()

using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;
using Newtonsoft.Json;

async Task<dynamic> CreateInvoiceAsync(Dictionary<string, string> data)
{
    using var client = new HttpClient();

    var request = new HttpRequestMessage(HttpMethod.Post, "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices")
    {
        Content = new FormUrlEncodedContent(data)
    };

    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    request.Headers.Add("Channel", channel);

    var response = await client.SendAsync(request);
    var content = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(content);
}

// Kullanım
var invoice = await CreateInvoiceAsync(new Dictionary<string, string>
{
    { "contact_id", "1" },
    { "address_id", "1" },
    { "order_date", "2024-01-15" },
    { "currency", "try" },
    { "items[0][product_id]", "1" },
    { "items[0][quantity]", "2" },
    { "items[0][unit_price]", "100.00" },
    { "items[0][vat_rate]", "20" }
});

Yanıt

Başarılı Yanıt

{
  "data": {
    "document_id": 1854,
    "grand_total": 2327.6,
    "grand_currency": "eur",
    "exchange_grand_total": 78077.47,
    "exchange_grand_currency": "try"
  }
}

Yanıt Alanları

Alan	Tip	Açıklama
`document_id`	integer	Oluşturulan fatura ID
`grand_total`	number	Fatura para biriminde genel toplam
`grand_currency`	string	Faturanın para birimi
`exchange_grand_total`	number	Şirket para birimindeki karşılığı
`exchange_grand_currency`	string	Şirket para birimi (tracking currency)

Endpoint​

Parametreler​

Zorunlu Alanlar​

Fatura Kalemleri​

Opsiyonel Temel Alanlar​

Kur & Para Birimi Alanları​

E-Belge Senaryo Alanları​

Özel Matrah Alanları (document_type = OZELMATRAH)​

İnternet Satışı Alanları​

İnternet Satışı Kargo Alanları​

İhracat Taşıma Bilgileri​

İlaç/Tıbbi Cihaz Kalem Alanları (document_scenario = ILAC_TIBBICIHAZ)​

İlaç Identification Alanları (medicine_medicaldevice_type = medicine)​

Tıbbi Cihaz Identification Alanları (medicine_medicaldevice_type = medical_device)​

Örnekler​

Yanıt​

Yanıt Alanları​