Fatura Listeleme

Şirketinize ait faturaları listeleme ve filtreleme.

Endpoint

GET /kolaybi/v1/invoices

Parametreler

Parametre	Tip	Açıklama
type	InvoiceType	Fatura türü ile filtreleme (varsayılan: sale_invoice)

Fatura Türleri

Tür	Açıklama
sale_invoice	Satış faturası
sale_return_invoice	Satış iade faturası
purchase_invoice	Alış faturası
purchase_return_invoice	Alış iade faturası
self_employment_receipt	Serbest meslek makbuzu

Örnekler

cURL

# Tüm faturalar
curl -X GET "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL"

# Sadece satış faturaları
curl -X GET "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices?type=sale_invoice" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL"

JavaScript

async function listInvoices(filters = {}) {
  const params = new URLSearchParams(filters);
  const response = await fetch(
    `https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices?${params}`,
    {
      headers: {
        Authorization: `Bearer ${accessToken}`,
        Channel: channel,
      },
    }
  );
  return await response.json();
}

// Kullanım
const saleInvoices = await listInvoices({ type: "sale_invoice" });
const allInvoices = await listInvoices();

PHP

function listInvoices($filters = []) {
    $url = 'https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices';
    if (!empty($filters)) {
        $url .= '?' . http_build_query($filters);
    }

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $accessToken,
            'Channel: ' . $channel
        ],
        CURLOPT_RETURNTRANSFER => true
    ]);

    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Kullanım
$saleInvoices = listInvoices(['type' => 'sale_invoice']);

Python

import requests

def list_invoices(filters=None):
    if filters is None:
        filters = {}

    url = "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices"
    headers = {
        "Authorization": f"Bearer {access_token}",
        "Channel": channel
    }

    response = requests.get(url, headers=headers, params=filters)
    return response.json()

# Kullanım
sale_invoices = list_invoices({"type": "sale_invoice"})
all_invoices = list_invoices()

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> ListInvoicesAsync(Dictionary<string, string> filters = null)
{
    using var client = new HttpClient();

    var url = "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/invoices";
    if (filters != null && filters.Count > 0)
    {
        var query = await new FormUrlEncodedContent(filters).ReadAsStringAsync();
        url += "?" + query;
    }

    var request = new HttpRequestMessage(HttpMethod.Get, url);
    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 saleInvoices = await ListInvoicesAsync(new Dictionary<string, string> { { "type", "sale_invoice" } });

Yanıt Formatı

{
  "data": [
    {
      "commercial_doc_id": 1854,
      "currency": "try",
      "tracking_currency": "try",
      "commercial_doc_type": {
        "group": "sale",
        "value": "sale_invoice",
        "key": "SALE_INVOICE",
        "description": "Satış Faturası"
      },
      "commercial_doc_status": {
        "group": "sale",
        "value": "ready_to_send",
        "key": "READY_TO_SEND",
        "description": "Gönderime Hazır"
      },
      "cash_flow_direction": 1,
      "transformation_status": null,
      "financial_action_type_id": 0,
      "e_document_status": "ready",
      "is_payable": true,
      "is_exchange_diff": false,
      "header": {
        "serial_no": "KBI202400000234",
        "issue_date": "2024-01-15 10:30:00",
        "issue_time": "10:30:00",
        "due_date": "2024-02-15 00:00:00",
        "description": "Test faturası",
        "associate": {
          "full_name": "ACME LTD",
          "identity_no": "1234567890"
        }
      },
      "total": {
        "total_vat": 211.6,
        "total_amount": 2327.6,
        "subtotal": 2116,
        "grand_total": 2327.6,
        "exchange_grand_total": 2327.6,
        "subtotal_discount_type": {
          "value": "numeric",
          "key": "NUMERIC",
          "description": "numeric"
        },
        "subtotal_discount_value": 0
      },
      "payment_plan": {
        "actual_amount": 2327.6,
        "total_amount": 2327.6,
        "cash_flow_direction": 1,
        "total_paid": 0,
        "total_remaining": 2327.6,
        "tracking_currency": "try",
        "actual_currency": "try",
        "payment_status_value": "unpaid"
      },
      "projects": [],
      "tags": []
    }
  ]
}

Yanıt Alanları

Alan	Açıklama
commercial_doc_id	Faturaya ait benzersiz ID
currency	Faturanın para birimi
tracking_currency	Takip (kasa) para birimi
commercial_doc_type	Fatura türü bilgisi (group, value, description)
commercial_doc_status	Ticari doküman statüsü
cash_flow_direction	Nakit akışı yönü (1 alacak, -1 borç)
e_document_status	E-belge durumu (ready, sent_to_receiver vb.)
header	Seri numarası, tarih ve cari bilgilerini içerir
header.serial_no	Fatura seri/numarası
header.issue_date	Düzenleme tarihi (YYYY-MM-DD HH:mm:ss)
header.due_date	Vade tarihi
header.associate	Cari özeti (full_name, identity_no)
total	Toplamlar (ara toplam, KDV, grand total, iskontolar)
payment_plan	Tahsilat planı ve kalan bakiye bilgileri
projects	Faturaya bağlı projeler
tags	Faturaya bağlı etiketler

Etiket Alanları (tags)

Alan	Tip	Açıklama
id	integer	Etiket ID değeri
name	string	Etiket adı
description	string	Etiket açıklaması (varsa)

Fatura Durumları

Durum	Açıklama
draft	Taslak
ready_to_send	Gönderime hazır
sent	GİB'e gönderildi
approved	Onaylandı
rejected	Reddedildi
cancelled	İptal edildi