Fatura Oluşturma

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

Endpoint

POST /kolaybi/v1/invoices

Parametreler

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
currency	Currency	Evet	Para birimi
items	array	Evet	Fatura kalemleri
serial_no	string	Hayır	Özel fatura seri numarası
due_date	datetime	Hayır	Vade tarihi
description	string	Hayır	Fatura açıklaması
receiver_email	string	Hayır	E-fatura alıcı e-postası
type	InvoiceType	Hayır	Fatura türü

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	İndirim tutarı

Örnekler

cURL

# 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=TRY&due_date=2024-02-15&description=Test faturası&receiver_email=customer@example.com&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[1][product_id]=2&items[1][quantity]=1&items[1][unit_price]=50.00&items[1][vat_rate]=18"

JavaScript

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

  // 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);
  });

  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",
    },
  ],
});

PHP

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

Python

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()

C#

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": {
    "id": 1,
    "serial_no": "2024-001",
    "contact_id": 1,
    "address_id": 1,
    "order_date": "2024-01-15",
    "due_date": "2024-02-15",
    "currency": "TRY",
    "type": "sale_invoice",
    "status": "ready_to_send",
    "total_amount": 240.0,
    "vat_amount": 40.0,
    "items": [
      {
        "id": 1,
        "product_id": 1,
        "product_name": "Test Ürün",
        "quantity": "2",
        "unit_price": "100.00",
        "vat_rate": "20",
        "subtotal": 200.0,
        "vat_amount": 40.0,
        "total": 240.0
      }
    ]
  }
}

Yanıt Alanları

Alan	Tip	Açıklama
id	integer	Oluşturulan fatura ID
serial_no	string	Fatura seri numarası
contact_id	integer	Müşteri ID
address_id	integer	Adres ID
order_date	string	Fatura tarihi
due_date	string	Vade tarihi
currency	string	Para birimi
type	string	Fatura türü
status	string	Fatura durumu
total_amount	number	Toplam tutar
vat_amount	number	KDV tutarı
items	array	Fatura kalemleri

Kurallar

Önemli

• Müşteri ve adres: Sistemde mevcut olmalı
• En az 1 kalem: Faturada en az 1 ürün olmalı
• Tarih formatı: YYYY-MM-DD olmalı
• Miktar ve fiyat: String formatında decimal
• KDV oranı: Geçerli değerlerden biri olmalı