KolayBi API Documentation

website·Indexed 34 days ago

https://developer.kolaybi.com/

REST API for digitizing business financial processes. Includes endpoints for managing sales invoices (including GİB submission and e-Archive cancellation), proformas, product and service records, stock movements, bank/vault transactions, and customer (associate) collections. Provides guides on authentication, API key generation, and implementation examples in C# and cURL.

Tokens: 31.8K
Snippets: 178
Records: 214
Agent score: 53%

What's inside KolayBi

Overview of KolayBi API Modules
KolayBi provides a set of REST-based APIs designed to digitize and automate financial processes. The ecosystem is divided into functional modules that share a common authentication method and response format:
- Associates API: Used for managing customers and suppliers.
- Invoices API: Used for creating invoices and sending e-invoices.
- Products API: Used for product and stock management.
https://developer.kolaybi.com/docs/getting-started/
Understand the e-invoice list response
The response returns a data array containing invoice objects. Each object provides details about the invoice's identity, status, and financial totals.
```
{
  "data": [
    {
      "commercial_doc_id": 18,
      "document_uuid": "f46d5a8d-7726-4b37-bba4-973c7ab50a5b",
      "document_no": "HDB2021000008464",
      "document_status": "sent_to_receiver",
      "document_scenario": "EARSIVFATURA",
      "document_type": "SATIS",
      "direction": "outbound",
      "grand_total": 20,
      "currency": "try",
      "issue_date": "2024-06-10 00:00:00",
      "cancelled_at": "2024-06-15 14:30:00"
    }
  ]
}
```
Field Definitions:
- commercial_doc_id (integer): Invoice ID value
- document_uuid (string): Invoice UUID (ETTN)
- document_no (string): Serial number
- document_status (string): E-Invoice status
- document_scenario (DocumentScenario): Invoice scenario
- document_type (DocumentType): Invoice type
- direction (string): Sending direction
- grand_total (number): Total amount
- currency (string): Invoice currency
- issue_date (string): Invoice date
- cancelled_at (string): Cancellation date
https://developer.kolaybi.com/docs/e-documents/list/
Understand the associate payment response
A successful payment transaction returns a JSON object containing the transaction details and a success flag.
Key Response Fields:
- id (integer): The ID of the recorded payment transaction.
- creator (object): Information about the user who created the transaction.
- transaction_type (object): Details of the transaction type (e.g., payment).
- payment_method (object): The method used for payment (e.g., cash).
- issue_date (string): Transaction date (YYYY-MM-DD HH:mm:ss).
- amount (number): The payment amount.
- currency (string): The currency used.
- success (boolean): Indicates if the operation was successful.
- message (string): Service message (e.g., TRANSACTION.STORE.SUCCESS).
```
{
  "data": {
    "id": 38,
    "creator": {
      "id": 4,
      "full_name": "Test Full Name"
    },
    "transaction_type": {
      "key": "PAYMENT",
      "description": "Payment"
    },
    "payment_method": {
      "key": "CASH",
      "description": "Nakit"
    },
    "issue_date": "2025-06-13 02:03:40",
    "amount": 1000,
    "currency": "try"
  },
  "message": "TRANSACTION.STORE.SUCCESS",
  "success": true
}
```
https://developer.kolaybi.com/docs/associates/payment/

Understand the Bond list response structure

The response returns an array of bond records in the data field. Each record contains detailed information about the bond's financial value, dates, and legal parties.

{
  "data": [
    {
      "id": 84,                          // Bond (installment) ID
      "detail_id": 11,                   // Bond ID linking installments
      "serial_no": "SNT-2026-001",      // Serial number
      "receive_date": "2026-04-30 00:00:00", // Maturity date
      "issue_date": "2026-01-30 00:00:00",   // Issuance date
      "bond_status": "portfolio",       // Bond status
      "cash_flow_direction": 1,          // Cash flow direction
      "amount": 25000.0,                  // Installment amount
      "currency": "try",                // Currency
      "description": "1. taksit",       // Description
      "drawer": "Örnek Borçlu A.Ş.",     // Debtor
      "payee": "Örnek Alacaklı Ltd. Şti.", // Creditor
      "guarantor": "Örnek Kefil",        // Guarantor
      "guarantor_identity_no": "12345678901", // Guarantor ID number
      "issue_place": "Ankara",           // Place of issuance
      "authorized_court_province": "Ankara", // Authorized court province
      "associate_id": 7,                  // Associated current account ID
      "vault_id": 3,                     // Bank/Vault ID
      "endorsed_associate_id": null,      // Endorsed current account ID
      "tags": [
        { "id": 12, "name": "Tahsilat", "description": null }
      ]
    }
  ]
}

Supported languages for KolayBi API integration
The KolayBi API provides implementation examples and support for the following languages and environments: cURL (Command line), JavaScript (Node.js and Browser), PHP, Python, and C# (.NET).
https://developer.kolaybi.com/docs/examples/intro/
Retrieve detailed information for a specific associate
Use the GET /kolaybi/v1/associates/{id} endpoint to fetch comprehensive details about a specific associate (cari). This includes identity information, contact details, associated tags, addresses, and financial balances across different currencies.
```
curl -X GET "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates/1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL"
```
https://developer.kolaybi.com/docs/associates/detail/

Obtain an Access Token for KolayBi API

To authenticate requests to the KolayBi API, you must first obtain an access token by sending a POST request to the /kolaybi/v1/access_token endpoint. You must provide the api_key in the JSON body and include the Channel header.

async function getAccessToken(apiKey, channel) {
  const response = await fetch(
    "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/access_token",
    {
      method: "POST",
      headers: {
        Channel: channel,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        api_key: apiKey,
      }),
    }
  );

  const data = await response.json();
  return data.data;
}

Send an E-invoice
Sending an e-invoice is a three-step process:
1. Create the invoice via POST /invoices.
2. Formalize the document via POST /e-document.
3. Verify the status via GET /invoices/{id}.
https://developer.kolaybi.com/docs/faq/

Manage Customer Accounts (Associates) in KolayBi using C#

Customer operations require a Bearer token in the Authorization header and a Channel header.

Listing Customers: Use a GET request to /kolaybi/v1/associates.
Creating Customers: Use a POST request to /kolaybi/v1/associates with data sent as FormUrlEncodedContent.

// List Associates
public async Task<dynamic> ListAssociatesAsync(string accessToken, string channel)
{
    var request = new HttpRequestMessage(HttpMethod.Get, "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates");
    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
    request.Headers.Add("Channel", channel);
    var response = await _httpClient.SendAsync(request);
    var content = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(content);
}

// Create Associate
public async Task<dynamic> CreateAssociateAsync(string accessToken, string channel, Dictionary<string, string> associateData)
{
    var formContent = new FormUrlEncodedContent(associateData);
    var request = new HttpRequestMessage(HttpMethod.Post, "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates") { Content = formContent };
    request.Headers.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", accessToken);
    request.Headers.Add("Channel", channel);
    var response = await _httpClient.SendAsync(request);
    var content = await response.Content.ReadAsStringAsync();
    return JsonConvert.DeserializeObject<dynamic>(content);
}

Setup C# Project Dependencies for KolayBi API
The KolayBi API C# examples rely on Newtonsoft.Json for JSON serialization and deserialization.
```
<PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
```
https://developer.kolaybi.com/docs/examples/csharp/
Get started with KolayBi API integration
To integrate your business with KolayBi, follow these three primary steps:
1. Obtain API Credentials: Retrieve your API key from your account settings and request your Channel information from the KolayBi support team.
2. Make Your First Request: Use your API key and Channel information to obtain an Access Token, which is required to authenticate and use the API.
3. Go Live: Once the integration is tested and complete, transition to the production environment to automate your business processes.
https://developer.kolaybi.com/
Get started with KolayBi API
To begin using the KolayBi API, follow these steps:
1. Obtain your API key from your KolayBi account.
2. Request your unique 'Channel' identifier from the support team at api.support@kolaybi.com.
3. Generate an access token.
4. Make your first API call.
https://developer.kolaybi.com/docs/faq/