REST API Dokümanı

curl https://kurumsalhesap.com/api/v1/me \
  -H "X-Company-Code: FIRMA_KODUNUZ" \
  -H "X-Api-Secret: khs_GIZLI_ANAHTARINIZ"

<?php
// Kurumsal Hesap REST API — PHP 8+ (cURL, ek kütüphane gerekmez)

const KH_BASE = 'https://kurumsalhesap.com/api/v1';

function kh(string $method, string $path, ?array $body = null): array
{
    $headers = [
        'X-Company-Code: ' . getenv('KH_COMPANY_CODE'),   // firma kodunuz
        'X-Api-Secret: ' . getenv('KH_API_SECRET'),       // khs_ ile başlayan gizli anahtar
        'Accept: application/json',
    ];

    $ch = curl_init(KH_BASE . $path);
    if ($body !== null) {
        $headers[] = 'Content-Type: application/json';
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_UNICODE));
    }
    curl_setopt_array($ch, [
        CURLOPT_CUSTOMREQUEST  => $method,
        CURLOPT_HTTPHEADER     => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 60,
    ]);

    $raw  = curl_exec($ch);
    $http = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
    $json = json_decode((string) $raw, true);

    if ($raw === false || $http >= 400 || empty($json['status'])) {
        throw new RuntimeException(($json['message'] ?? curl_error($ch)) . " (HTTP $http)");
    }

    return $json;
}

// 1) Carileri listele (sayfa başına en fazla 500)
$page = kh('GET', '/customers?per_page=100&page=1');
foreach ($page['data'] as $customer) {
    echo $customer['id'], ' - ', $customer['title'], PHP_EOL;
}

// 2) Yeni cari ekle
$customer = kh('POST', '/customers', [
    'title' => 'Örnek Teknoloji Ltd. Şti.',
    'mail'  => '[email protected]',
    'phone' => '0212 000 00 00',
])['data'];

// 3) Yalnızca telefonu güncelle (gönderilmeyen alanlar korunur)
kh('PATCH', '/customers/' . $customer['id'], ['phone' => '0212 111 11 11']);

// 4) Teklif oluştur (ürün numaraları: GET /products)
$offer = kh('POST', '/offers', [
    'customer_id'  => $customer['id'],
    'date'         => date('Y-m-d'),
    'product_list' => [
        ['product_id' => 12, 'amount' => 2, 'price' => 1500, 'description' => 'Yıllık lisans'],
    ],
])['data'];

echo 'Teklif no: ', $offer['code'], PHP_EOL;

// Kurumsal Hesap REST API — C# (.NET 6+), ek paket gerekmez
using System.Net.Http;
using System.Net.Http.Json;
using System.Text.Json.Nodes;

var api = new KurumsalHesapClient(
    Environment.GetEnvironmentVariable("KH_COMPANY_CODE")!,   // firma kodunuz
    Environment.GetEnvironmentVariable("KH_API_SECRET")!);    // khs_ ile başlayan gizli anahtar

// 1) Carileri listele (sayfa başına en fazla 500)
var page = await api.SendAsync(HttpMethod.Get, "customers?per_page=100&page=1");
foreach (var customer in page["data"]!.AsArray())
    Console.WriteLine($"{customer!["id"]} - {customer["title"]}");

// 2) Yeni cari ekle
var created = await api.SendAsync(HttpMethod.Post, "customers", new
{
    title = "Örnek Teknoloji Ltd. Şti.",
    mail = "[email protected]",
    phone = "0212 000 00 00",
});
var customerId = (int)created["data"]!["id"]!;

// 3) Yalnızca telefonu güncelle (gönderilmeyen alanlar korunur)
await api.SendAsync(HttpMethod.Patch, $"customers/{customerId}", new { phone = "0212 111 11 11" });

// 4) Teklif oluştur (ürün numaraları: GET /products)
var offer = await api.SendAsync(HttpMethod.Post, "offers", new
{
    customer_id = customerId,
    date = DateTime.Today.ToString("yyyy-MM-dd"),
    product_list = new[] { new { product_id = 12, amount = 2, price = 1500m, description = "Yıllık lisans" } },
});
Console.WriteLine($"Teklif no: {offer["data"]!["code"]}");

public sealed class KurumsalHesapClient
{
    private readonly HttpClient _http;

    public KurumsalHesapClient(string companyCode, string apiSecret, string baseUrl = "https://kurumsalhesap.com/api/v1/")
    {
        _http = new HttpClient { BaseAddress = new Uri(baseUrl), Timeout = TimeSpan.FromSeconds(60) };
        _http.DefaultRequestHeaders.Add("X-Company-Code", companyCode);
        _http.DefaultRequestHeaders.Add("X-Api-Secret", apiSecret);
        _http.DefaultRequestHeaders.Add("Accept", "application/json");
    }

    public async Task<JsonNode> SendAsync(HttpMethod method, string path, object? body = null)
    {
        using var request = new HttpRequestMessage(method, path);
        if (body != null) request.Content = JsonContent.Create(body);

        using var response = await _http.SendAsync(request);
        var json = JsonNode.Parse(await response.Content.ReadAsStringAsync())!;
        if (!response.IsSuccessStatusCode || json["status"]?.GetValue<bool>() != true)
            throw new HttpRequestException($"{json["message"]} (HTTP {(int)response.StatusCode})");

        return json;
    }
}

// Kurumsal Hesap REST API — Java 11+ (java.net.http), ek kütüphane gerekmez
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class KurumsalHesapClient {
    private static final String BASE_URL = "https://kurumsalhesap.com/api/v1/";

    private final HttpClient http = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(20)).build();
    private final String companyCode;
    private final String apiSecret;

    public KurumsalHesapClient(String companyCode, String apiSecret) {
        this.companyCode = companyCode;
        this.apiSecret = apiSecret;
    }

    /** İsteği gönderir, JSON yanıtı metin olarak döndürür; 4xx / 5xx yanıtta hata fırlatır. */
    public String send(String method, String path, String json) throws Exception {
        HttpRequest.Builder request = HttpRequest.newBuilder(URI.create(BASE_URL + path))
                .timeout(Duration.ofSeconds(60))
                .header("X-Company-Code", companyCode)
                .header("X-Api-Secret", apiSecret)
                .header("Accept", "application/json");

        if (json != null) {
            request.header("Content-Type", "application/json; charset=utf-8")
                   .method(method, HttpRequest.BodyPublishers.ofString(json));
        } else {
            request.method(method, HttpRequest.BodyPublishers.noBody());
        }

        HttpResponse<String> response = http.send(request.build(), HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": " + response.body());
        }
        return response.body();
    }

    public static void main(String[] args) throws Exception {
        KurumsalHesapClient api = new KurumsalHesapClient(
                System.getenv("KH_COMPANY_CODE"),   // firma kodunuz
                System.getenv("KH_API_SECRET"));    // khs_ ile başlayan gizli anahtar

        // 1) Carileri listele (JSON'u Jackson ya da Gson ile nesneye çevirebilirsiniz)
        System.out.println(api.send("GET", "customers?per_page=100&page=1", null));

        // 2) Yeni cari ekle — yanıttaki data.id yeni kaydın numarasıdır
        String created = api.send("POST", "customers",
                "{\"title\":\"Örnek Teknoloji Ltd. Şti.\",\"mail\":\"[email protected]\",\"phone\":\"0212 000 00 00\"}");
        System.out.println(created);

        // 3) Yalnızca telefonu güncelle (gönderilmeyen alanlar korunur)
        api.send("PATCH", "customers/1520", "{\"phone\":\"0212 111 11 11\"}");

        // 4) Teklif oluştur (ürün numaraları: GET /products)
        api.send("POST", "offers",
                "{\"customer_id\":1520,\"date\":\"2026-09-15\","
                + "\"product_list\":[{\"product_id\":12,\"amount\":2,\"price\":1500,\"description\":\"Yıllık lisans\"}]}");
    }
}

{
  "status": true,
  "message": "Cari kaydı eklendi.",
  "data": {
    "id": 1520,
    "code": "C00148",
    "title": "Örnek Teknoloji Ltd. Şti.",
    "phone": "0212 000 00 00",
    "update_date": "2026-09-15 10:42:07"
  }
}

{
  "status": false,
  "message": "Cari ünvanını girmelisiniz!",
  "error": "validation_failed"
}

"meta": { "page": 1, "per_page": 100, "total": 248, "last_page": 3, "cursor": 90412 }

{
  "status": true,
  "message": "",
  "data": {
    "cursor": 90458,
    "has_more": false,
    "changes": [
      { "cursor": 90431, "resource": "customers", "id": 1520, "type": "upsert", "user_id": 8, "changed_at": "2026-09-15 10:42:07" },
      { "cursor": 90458, "resource": "agenda", "id": 311, "type": "delete", "user_id": 12, "changed_at": "2026-09-15 10:44:51" }
    ],
    "rows": { "customers": [ { "id": 1520, "title": "Örnek Teknoloji Ltd. Şti." } ] },
    "deleted": { "agenda": [311] }
  }
}

<?php
// Değişiklik akışı: kendi sisteminizi Kurumsal Hesap ile eşit tutar (yukarıdaki kh() fonksiyonunu kullanır)
// HTTP 410 (cursor_expired) alırsanız imleç dosyasını silip ilk aktarımı yeniden yapın.

$cursorFile = __DIR__ . '/kh-cursor.txt';

if (!is_file($cursorFile)) {
    // İlk çalıştırma: önce imleci alın, sonra kayıtları listeleyip aktarın
    file_put_contents($cursorFile, kh('GET', '/changes')['data']['cursor']);
    // kh('GET', '/customers?per_page=500&page=1') ... ile ilk aktarım
}

do {
    $cursor = (int) file_get_contents($cursorFile);
    $feed = kh('GET', "/changes?cursor=$cursor&include=rows")['data'];

    foreach ($feed['rows'] as $resource => $rows) {
        foreach ($rows as $row) {
            saveLocal($resource, $row);     // kendi veritabanınıza ekleyin / güncelleyin
        }
    }
    foreach ($feed['deleted'] as $resource => $ids) {
        foreach ($ids as $id) {
            deleteLocal($resource, $id);    // kendi veritabanınızdan kaldırın
        }
    }

    file_put_contents($cursorFile, $feed['cursor']);
} while ($feed['has_more']);

// Değişiklik akışı: kendi sisteminizi Kurumsal Hesap ile eşit tutar (KurumsalHesapClient yukarıda)
// HTTP 410 (cursor_expired) alırsanız ilk aktarımı yeniden yapıp yeni imleçle devam edin.

// İlk çalıştırmada: (long)(await api.SendAsync(HttpMethod.Get, "changes"))["data"]!["cursor"]!
long cursor = LoadCursor();
bool hasMore;

do
{
    var feed = (await api.SendAsync(HttpMethod.Get, $"changes?cursor={cursor}&include=rows"))["data"]!;

    foreach (var (resource, rows) in feed["rows"]!.AsObject())
        foreach (var row in rows!.AsArray())
            SaveLocal(resource, row!);          // kendi veritabanınıza ekleyin / güncelleyin

    foreach (var (resource, ids) in feed["deleted"]!.AsObject())
        foreach (var id in ids!.AsArray())
            DeleteLocal(resource, (int)id!);    // kendi veritabanınızdan kaldırın

    cursor = (long)feed["cursor"]!;
    SaveCursor(cursor);
    hasMore = (bool)feed["has_more"]!;
} while (hasMore);

// Değişiklik akışı (Jackson: com.fasterxml.jackson.core:jackson-databind)
// HTTP 410 (cursor_expired) alırsanız ilk aktarımı yeniden yapıp yeni imleçle devam edin.
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Iterator;
import java.util.Map;

ObjectMapper mapper = new ObjectMapper();

// İlk çalıştırmada: mapper.readTree(api.send("GET", "changes", null)).at("/data/cursor").asLong()
long cursor = loadCursor();
boolean hasMore;

do {
    JsonNode feed = mapper.readTree(api.send("GET", "changes?cursor=" + cursor + "&include=rows", null)).get("data");

    for (Iterator<Map.Entry<String, JsonNode>> it = feed.get("rows").fields(); it.hasNext(); ) {
        Map.Entry<String, JsonNode> entry = it.next();
        for (JsonNode row : entry.getValue()) {
            saveLocal(entry.getKey(), row);             // kendi veritabanınıza ekleyin / güncelleyin
        }
    }
    for (Iterator<Map.Entry<String, JsonNode>> it = feed.get("deleted").fields(); it.hasNext(); ) {
        Map.Entry<String, JsonNode> entry = it.next();
        for (JsonNode id : entry.getValue()) {
            deleteLocal(entry.getKey(), id.asInt());    // kendi veritabanınızdan kaldırın
        }
    }

    cursor = feed.get("cursor").asLong();
    saveCursor(cursor);
    hasMore = feed.get("has_more").asBoolean();
} while (hasMore);

# Dosya yükleme (multipart) — cariye bağlı, en fazla 50 MB
curl https://kurumsalhesap.com/api/v1/documents/upload \
  -H "X-Company-Code: FIRMA_KODUNUZ" -H "X-Api-Secret: khs_GIZLI_ANAHTARINIZ" \
  -F "[email protected]" -F "table_name=customer" -F "table_id=1520"

# Dosya indirme
curl -o dosya.pdf https://kurumsalhesap.com/api/v1/documents/3120/download \
  -H "X-Company-Code: FIRMA_KODUNUZ" -H "X-Api-Secret: khs_GIZLI_ANAHTARINIZ"

# Teklif PDF'i
curl -o teklif.pdf https://kurumsalhesap.com/api/v1/offers/845/pdf \
  -H "X-Company-Code: FIRMA_KODUNUZ" -H "X-Api-Secret: khs_GIZLI_ANAHTARINIZ"