Proforma Oluşturma

Yeni bir proforma faturası oluşturur.

Endpoint

POST /kolaybi/v1/proformas

Parametreler

Parametre	Tip	Zorunlu	Açıklama
contact_id	integer	Evet	Müşteri/cari ID değeri
address_id	integer	Evet	Adres ID değeri
order_date	string	Evet	Proforma tarihi (YYYY-MM-DD)
currency	string	Evet	Para birimi
items	array	Evet	Proforma kalemleri
serial_no	string	Hayır	Proforma seri numarası
due_date	string	Hayır	Geçerlilik tarihi (YYYY-MM-DD)
description	string	Hayır	Proforma açıklaması

Items Array

Parametre	Tip	Zorunlu	Açıklama
product_id	integer	Evet	Ürün ID değeri
quantity	string	Evet	Miktar
unit_price	string	Evet	Birim fiyat
vat_rate	string	Evet	KDV oranı
description	string	Hayır	Kalem açıklaması
discount_amount	number	Hayır	İndirim tutarı

Örnekler

cURL

curl -X POST "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/proformas" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Channel: YOUR_CHANNEL" \
  -H "Content-Type: multipart/form-data" \
  -F "contact_id=1" \
  -F "address_id=1" \
  -F "order_date=2024-01-15" \
  -F "currency=TRY" \
  -F "items[0][product_id]=1" \
  -F "items[0][quantity]=2" \
  -F "items[0][unit_price]=100.00" \
  -F "items[0][vat_rate]=18" \
  -F "serial_no=PROF-001" \
  -F "description=Örnek proforma açıklaması"

JavaScript

async function createProforma(data) {
  const formData = new FormData();

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

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

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

  const response = await fetch(
    "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/proformas",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        Channel: channel,
      },
      body: formData,
    }
  );

  return await response.json();
}

// Kullanım
const proforma = await createProforma({
  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: "18",
    },
  ],
  serial_no: "PROF-001",
  description: "Örnek proforma açıklaması",
});

PHP

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

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

    // Items
    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'];
    }

    // 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'];

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

// Kullanım
$proforma = createProforma([
    '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' => '18'
        ]
    ],
    'serial_no' => 'PROF-001',
    'description' => 'Örnek proforma açıklaması'
]);

Python

import requests

def create_proforma(data):
    url = "https://ofis-sandbox-api.kolaybi.com/kolaybi/v1/proformas"
    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']
    }

    # Items
    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']

    # 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']

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

# Kullanım
proforma = create_proforma({
    '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': '18'
        }
    ],
    'serial_no': 'PROF-001',
    'description': 'Örnek proforma açıklaması'
})

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

    var formContent = new MultipartFormDataContent();
    
    // Ana parametreler
    formContent.Add(new StringContent(data["contact_id"]), "contact_id");
    formContent.Add(new StringContent(data["address_id"]), "address_id");
    formContent.Add(new StringContent(data["order_date"]), "order_date");
    formContent.Add(new StringContent(data["currency"]), "currency");

    // Items
    if (data.ContainsKey("items"))
    {
        var items = JsonConvert.DeserializeObject<List<dynamic>>(data["items"]);
        for (int i = 0; i < items.Count; i++)
        {
            var item = items[i];
            formContent.Add(new StringContent(item.product_id.ToString()), $"items[{i}][product_id]");
            formContent.Add(new StringContent(item.quantity.ToString()), $"items[{i}][quantity]");
            formContent.Add(new StringContent(item.unit_price.ToString()), $"items[{i}][unit_price]");
            formContent.Add(new StringContent(item.vat_rate.ToString()), $"items[{i}][vat_rate]");
        }
    }

    // Opsiyonel parametreler
    if (data.ContainsKey("serial_no"))
        formContent.Add(new StringContent(data["serial_no"]), "serial_no");
    if (data.ContainsKey("description"))
        formContent.Add(new StringContent(data["description"]), "description");

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

    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 proforma = await CreateProformaAsync(new Dictionary<string, string>
{
    { "contact_id", "1" },
    { "address_id", "1" },
    { "order_date", "2024-01-15" },
    { "currency", "TRY" },
    { "serial_no", "PROF-001" },
    { "description", "Örnek proforma açıklaması" },
    { "items", "[{\"product_id\":1,\"quantity\":\"2\",\"unit_price\":\"100.00\",\"vat_rate\":\"18\"}]" }
});

Yanıt

Başarılı Yanıt

{
  "data": {
    "id": 1,
    "document_id": "PROF-001",
    "contact_id": 1,
    "address_id": 1,
    "order_date": "2024-01-15",
    "currency": "TRY",
    "total_amount": 236.0,
    "vat_amount": 36.0,
    "net_amount": 200.0,
    "status": "active",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Yanıt Alanları

Alan	Tip	Açıklama
id	integer	Proforma ID
document_id	string	Proforma numarası
contact_id	integer	Müşteri/cari ID
address_id	integer	Adres ID
order_date	string	Proforma tarihi
currency	string	Para birimi
total_amount	number	Toplam tutar
vat_amount	number	KDV tutarı
net_amount	number	Net tutar
status	string	Durum
created_at	string	Oluşturulma tarihi

Kurallar

Önemli

• Müşteri: Geçerli bir müşteri/cari ID'si olmalı
• Adres: Geçerli bir adres ID'si olmalı
• Ürünler: Geçerli ürün ID'leri olmalı
• Tarih: Geçerli tarih formatı (YYYY-MM-DD)
• Geçerlilik: Belirtilmezse 30 gün geçerli
• Yasal: Proforma faturaları yasal geçerliliği olmayan teklif dokümanlarıdır