Geliştiriciler

Hızlı başlangıç

1. Anahtar oluşturun. Uygulamada Yönetim › Entegrasyon › API Anahtarları ekranında yeni anahtar açın, entegrasyonun adını ve rollerini seçin. Anahtar yalnız bir kez gösterilir; sunucuda yalnız özeti saklanır.

2. İlk isteği gönderin.

curl "https://ozkaymak-erp-dotnet-rvfootuq6a-ew.a.run.app/api/v1/customers?size=2" \
  -H "X-Api-Key: ozk_…"

3. Yanıt. Her liste aynı zarfla döner:

{
  "items": [
    { "id": 482, "name": "…", "type": "customer", "tax_number": "…",
      "balance": { "amount": 0.00, "currency": "TRY" }, "active": true }
  ],
  "page": 1, "size": 2, "total": 57
}

Bütün uçlar, alanlar ve örnekler API başvurusunda (OpenAPI 3) — istemci kodu oradan üretilebilir.

Kimlik doğrulama

• Her istekte X-Api-Key başlığı. Anahtarsız ya da tanınmayan anahtar 401.
• Anahtar, onu oluşturan yöneticinin yetkisiyle çalışır ve onu aşamaz: seçilen roller yöneticinin verebileceği rollerle sınırlıdır; yönetici pasife alınırsa anahtar da çalışmaz.
• Anahtar yalnız /api/v1 uçlarında geçer; ekranların iç uçlarına giremez. Yalnız kendi firmanızın (ve grup şirketlerinizin) verisini görür.
• Anahtarı pasife aldığınız anda geçersiz olur. Ekranda her anahtarın son kullanım zamanı görünür.

Şirket seçimi

Hesabınızda birden çok şirket varsa şirketi şirket koduyla seçin — ekran adresindeki company değeriyle aynı kod:

-H "X-Company: 0002"

• Okumada seçim, sonucu o şirkete (ve alt şirketlerine) daraltır; yazmada kaydı o şirkete damgalar.
• Çok şirketli hesapta şirketsiz yazma isteği hiçbir şey yazmadan 400 döner. Bilinmeyen kod 400, erişiminiz olmayan şirket 403.
• Tek şirketli hesapta başlık gerekmez.

Sayfalama, sıralama, arama

Kayıt oluşturma ve güncelleme

• Tekrar güvenliği: POST isteğine Idempotency-Key başlığı ekleyin (en çok 80 karakter). Zaman aşımından sonra aynı anahtarla yeniden gönderdiğinizde ikinci kayıt açılmaz, ilk sonucun kendisi döner.
• Güncelleme: PUT gönderdiğiniz alanları değiştirir; göndermediğiniz ya da null gönderdiğiniz alana dokunmaz. Bir alanın değerini silmek bu sürümde desteklenmez.
• Silme: DELETE kaydı kalıcı silmez, pasife alır; yanıt 204. Tekrar silmek de 204 döner.
• Bugün yazmaya açık kaynaklar: customers, suppliers, business-partners, invoices, employees, sales-orders, webhook-subscriptions, accounting-source-transactions, payroll-change-packages, payroll-results, external-datasets, custom-objects. Ötekiler salt okunur.

Para, tarih, alan adları

• Tutarlar çıplak sayı değil, dövizle birlikte döner: { "amount": 150000.00, "currency": "TRY" }.
• Tarihler ISO 8601 (2026-10-08), zaman damgaları UTC (2026-10-08T09:46:41Z).
• Alan adları ve seçenek değerleri İngilizce ve snake_case: tax_number, "type": "customer".

Hatalar

Hatalar RFC 7807 biçimindedir; type hatanın sınıfıdır, detail İngilizce açıklamadır. Her yanıtta destek kaydına yazabileceğiniz bir trace_id bulunur.

{
  "type": "/errors/Forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The API key's user has no access to company '0002'.",
  "trace_id": "0HNP543SOILEB:00000001"
}

Hız sınırı

Firma başına dakikada 1.000 istek (kayan pencere). Aşımda 429 döner ve Retry-After başlığı ne kadar bekleneceğini söyler. Toplu aktarımda size=200 ile sayfalayın.

Sürümleme

Sürüm adrestedir: /api/v1. Bu sürüm içinde kırıcı değişiklik yapılmaz:

• Yanıta yeni alan eklemek, isteğe isteğe bağlı alan eklemek, yeni hata kodu eklemek aynı sürümde yapılır — istemciniz tanımadığı alanı yok saymalıdır.
• Alan kaldırmak ya da adını değiştirmek, tipini değiştirmek, isteğe bağlı alanı zorunlu yapmak, varsayılan sıralamayı ya da sayfa boyunu değiştirmek yalnız yeni sürümde (/api/v2) yapılır.
• Eski sürüm, kapanış tarihi önceden duyurulmadan kapatılmaz.

Webhook

Olayları sorgulamak yerine bildirim alın: fatura kesildi, sipariş onaylandı, sevkiyat çıktı …

• Abonelik: POST /api/v1/webhook-subscriptions — hedef adres (https), olay süzgeci (tam ad, invoice.* ya da *). İmza anahtarı (whsec_…) yalnız oluşturmada ve rotate-secret yanıtında bir kez döner.
• Olay kataloğu: GET /api/v1/webhook-events. Deneme için POST /{id}/test imzalı bir test.ping gönderir; teslimat geçmişi GET /{id}/deliveries.
• Teslimat: en az bir kez; başarısız teslimat geri çekilerek yeniden denenir, art arda başarısızlıkta abonelik kendiliğinden kapanır. Aynı teslimatı ikinci kez işlememek için X-Ozk-Delivery-Id başlığını saklayın.
• Hedef adres genel internette olmalıdır; özel ağ, yerel ve bulut meta veri adreslerine bağlanılmaz, yönlendirme izlenmez.

İmzayı doğrulayın — X-Ozk-Signature: t=<unix>,v1=<hex>, v1 = HMAC-SHA256(secret, "<t>.<raw body>"):

import crypto from "node:crypto";

function isValidSignature(header, rawBody, secret) {
  const p = Object.fromEntries(header.split(",").map((x) => x.split("=")));
  const expected = crypto.createHmac("sha256", secret).update(`${p.t}.${rawBody}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(p.t)) < 300;   // reject signatures older than 5 minutes
  return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
}

Kaynaklar (201)

Keşif ucu GET /api/v1 listeyi makine okur biçimde verir. Her kaynağın alanları API başvurusunda.