Cari Virman İşlemi

İki cari arasında virman (bakiye aktarımı) yapılır. Kaynak cari URL'deki id, hedef cari destination_associate_id ile belirtilir.

Endpoint

POST /kolaybi/v1/associates/{id}/transactions/transfer

Parametreler

Parametre	Tip	Açıklama
id	integer	Kaynak (virmanı yapan) cari ID'si

Request Body

Alan	Tip	Zorunlu	Açıklama
destination_associate_id	integer	Evet	Hedef cari ID'si
amount	number	Evet	Virman tutarı
currency	string	Evet	Para birimi
cash_flow_direction	integer	Evet	Transfer yönü (-1 para çıkışı, 1 para girişi)
exchange_rate	number	Koşullu	Döviz kuru. currency firma para biriminden farklıysa zorunlu
destination_currency	string	Hayır	Hedef cari para birimi (varsayılan currency)
destination_exchange_rate	number	Koşullu	Hedef döviz kuru. destination_currency hem currency hem firma para biriminden farklıysa zorunlu
issue_date	string	Hayır	İşlem tarihi (YYYY-MM-DD HH:mm:ss)
description	string	Hayır	Açıklama
project_ids[]	integer	Hayır	Proje ID'si (en fazla 1)
expenses[0][source_type]	string	Hayır	Masrafın çıkacağı hesap türü: Vault veya Associate
expenses[0][source_id]	integer	Hayır	Aktif kasa/banka veya cari ID'si
expenses[0][amount]	number	Hayır	Masraf tutarı
expenses[0][currency]	string	Hayır	Masraf para birimi
expenses[0][exchange_rate]	number	Hayır	Masraf kuru (gönderilmezse TCMB kuru)
transaction_currency_rates[0][quote_currency]	string	Hayır	Takip para birimi (currency'den farklı)
transaction_currency_rates[0][rate]	number	Hayır	1 birim takip para biriminin currency cinsinden değeri

Örnekler

cURL

curl -X POST "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates/123/transactions/transfer" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "destination_associate_id=456&amount=10&currency=usd&exchange_rate=40&destination_currency=eur&destination_exchange_rate=50&cash_flow_direction=-1&description=Virman açıklaması&project_ids[0]=7&expenses[0][source_type]=Vault&expenses[0][source_id]=1&expenses[0][amount]=50&expenses[0][currency]=try&transaction_currency_rates[0][quote_currency]=gbp&transaction_currency_rates[0][rate]=1.25"

JavaScript

async function createAssociateTransfer(associateId, transferData) {
  const formData = new URLSearchParams();
  Object.keys(transferData).forEach((key) => {
    formData.append(key, transferData[key]);
  });

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

// Kullanım
const transfer = await createAssociateTransfer(123, {
  destination_associate_id: 456,
  amount: 10,
  currency: "usd",
  exchange_rate: 40,
  destination_currency: "eur",
  destination_exchange_rate: 50,
  cash_flow_direction: -1,
  description: "Virman açıklaması",
  "project_ids[0]": 7,
  "expenses[0][source_type]": "Vault",
  "expenses[0][source_id]": 1,
  "expenses[0][amount]": 50,
  "expenses[0][currency]": "try",
  "transaction_currency_rates[0][quote_currency]": "gbp",
  "transaction_currency_rates[0][rate]": 1.25,
});

PHP

function createAssociateTransfer($associateId, $transferData) {
    $url = "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates/{$associateId}/transactions/transfer";

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL => $url,
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => http_build_query($transferData),
        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);
}

// Kullanım
$transfer = createAssociateTransfer(123, [
    'destination_associate_id' => 456,
    'amount' => 10,
    'currency' => 'usd',
    'exchange_rate' => 40,
    'destination_currency' => 'eur',
    'destination_exchange_rate' => 50,
    'cash_flow_direction' => -1,
    'description' => 'Virman açıklaması',
    'project_ids' => [7],
    'expenses' => [
        ['source_type' => 'Vault', 'source_id' => 1, 'amount' => 50, 'currency' => 'try'],
    ],
    'transaction_currency_rates' => [
        ['quote_currency' => 'gbp', 'rate' => 1.25],
    ],
]);

Python

import requests

def create_associate_transfer(associate_id, transfer_data):
    url = f'https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates/{associate_id}/transactions/transfer'
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Channel': channel,
        'Content-Type': 'application/x-www-form-urlencoded'
    }

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

# Kullanım
transfer = create_associate_transfer(123, {
    'destination_associate_id': 456,
    'amount': 10,
    'currency': 'usd',
    'exchange_rate': 40,
    'destination_currency': 'eur',
    'destination_exchange_rate': 50,
    'cash_flow_direction': -1,
    'description': 'Virman açıklaması',
    'project_ids[0]': 7,
    'expenses[0][source_type]': 'Vault',
    'expenses[0][source_id]': 1,
    'expenses[0][amount]': 50,
    'expenses[0][currency]': 'try',
    'transaction_currency_rates[0][quote_currency]': 'gbp',
    'transaction_currency_rates[0][rate]': 1.25,
})

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> CreateAssociateTransferAsync(int associateId, Dictionary<string, string> transferData)
{
    using var client = new HttpClient();

    var request = new HttpRequestMessage(HttpMethod.Post,
        $"https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/associates/{associateId}/transactions/transfer")
    {
        Content = new FormUrlEncodedContent(transferData)
    };

    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 transfer = await CreateAssociateTransferAsync(123, new Dictionary<string, string>
{
    { "destination_associate_id", "456" },
    { "amount", "10" },
    { "currency", "usd" },
    { "exchange_rate", "40" },
    { "destination_currency", "eur" },
    { "destination_exchange_rate", "50" },
    { "cash_flow_direction", "-1" },
    { "description", "Virman açıklaması" },
    { "project_ids[0]", "7" },
    { "expenses[0][source_type]", "Vault" },
    { "expenses[0][source_id]", "1" },
    { "expenses[0][amount]", "50" },
    { "expenses[0][currency]", "try" },
    { "transaction_currency_rates[0][quote_currency]", "gbp" },
    { "transaction_currency_rates[0][rate]", "1.25" },
});

Yanıt

{
  "data": {
    "id": 59,
    "creator": {
      "id": 4,
      "user_type": {
        "value": "regular",
        "key": "REGULAR",
        "description": "Regular",
        "group": "visible"
      },
      "name": "Test Name",
      "surname": "Test Surname",
      "full_name": "Test Full Name"
    },
    "transaction_type": {
      "value": "transfer",
      "key": "TRANSFER",
      "description": "Virman",
      "group": null
    },
    "issue_date": "2026-10-11 10:00:00",
    "amount": 10,
    "currency": "usd",
    "description": "Virman açıklaması"
  },
  "message": "TRANSACTION.TRANSFER.SUCCESS",
  "description": null,
  "success": true
}

Yanıt Alanları

Alan	Tip	Açıklama
id	integer	Kayıtlı virman işleminin ID'si
creator	object	İşlemi oluşturan kullanıcı bilgileri
transaction_type	object	İşlem tipi bilgisi (transfer)
issue_date	string	İşlem tarihi (YYYY-MM-DD HH:mm:ss)
amount	number	Kaynak caride işlem gören tutar
currency	string	Kaynak tutarın para birimi
description	string	Açıklama
message	string	Servis mesajı
success	boolean	İşlem sonucu

Hata Durumları

Durum	Yanıt
Eksik alan veya kur; bulunamayan cari ya da masraf hesabı; pasif masraf kasası; birden fazla proje; hedef tutar 0	400, code: 10400 ("Doğrulama hataları bulundu.")
Kaynak ve hedef cari aynı	412 ("Aynı hesaba transfer yapılamaz.")
Kaynak veya hedef cari pasif	İşlem reddedilir
API anahtarı sahibinin nakit transferi oluşturma yetkisi yok	İşlem reddedilir