Geliştiriciler / API

Name: OrbitCashFlow
Author: OrbitCashFlow

Orbit CashFlow'u harici sistemlerinize entegre etmek için salt okunur REST API referansı.

Giriş

Orbit CashFlow public API'si, şirketinizin finansal verilerini harici sistemlere çekmek için tasarlanmış salt okunur bir REST API'dir. Her istek, API anahtarının bağlı olduğu şirket/kiracı kapsamında değerlendirilir.

Base URLhttps://orbitcashflow.com/api/v1

Kimlik Doğrulama

API anahtarınızı her istekte x-api-key header'ı ile gönderin.

x-api-key: orbit_live_xxx

Şirket yöneticileri API anahtarlarını şuradan oluşturup iptal edebilir: Ayarlar → Şirket → API Anahtarları.

Tam anahtar yalnızca oluşturulduğu anda bir kez gösterilir. Hemen kopyalayıp güvenli bir yerde saklayın.
Mevcut anahtarlar salt okunurdur (read yetkisi).

Örnek anahtar

orbit_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Uç Noktalar

Tüm uç noktalar GET isteğidir ve JSON döndürür. Aşağıdaki yolları temel URL'nin sonuna ekleyin.

Metod	Yol	Açıklama	Sorgu parametreleri
`GET`	`/public-api/accounts`	Hesapları listele	`page`params.accounts.page `limit`params.accounts.limit `sortBy`params.accounts.sortBy `sortOrder`params.accounts.sortOrder `search`params.accounts.search `type`Hesap tipine göre filtrele. `isActive`Yalnızca aktif hesapları getirmek için true. `currency`Para birimi koduna göre filtrele (ör. TRY, USD, EUR).
`GET`	`/public-api/categories`	Kategorileri listele	`page`params.categories.page `limit`params.categories.limit `sortBy`params.categories.sortBy `sortOrder`params.categories.sortOrder `search`params.categories.search `type`Kategori tipine göre filtrele (income/gelir veya expense/gider). `parentId`Üst kategori ID'sine göre filtrele. `rootOnly`Yalnızca üst seviye kategorileri getirmek için true. `isActive`Yalnızca aktif kategorileri getirmek için true. `includeSystem`Sistem kategorilerini dahil etmek için true.
`GET`	`/public-api/contacts`	Kişileri listele	`page`params.contacts.page `limit`params.contacts.limit `sortBy`params.contacts.sortBy `sortOrder`params.contacts.sortOrder `search`params.contacts.search `type`Kişi tipine göre filtrele (müşteri veya tedarikçi). `isActive`Yalnızca aktif kişileri getirmek için true. `city`Şehir adına göre filtrele.
`GET`	`/public-api/budgets`	Bütçeleri listele	`page`params.budgets.page `limit`params.budgets.limit `sortBy`params.budgets.sortBy `sortOrder`params.budgets.sortOrder `search`Bütçe adına göre ara. `periodType`Bütçe dönem tipine göre filtrele. `status`Bütçe durumuna göre filtrele. `startDateFrom`Başlangıç tarihine göre filtrele (başlangıç), ISO 8601. `startDateTo`Başlangıç tarihine göre filtrele (bitiş), ISO 8601.
`GET`	`/public-api/budget-plans`	Kurumsal bütçe planlarını (V2) listele	—
`GET`	`/public-api/budget-plans/:planId/lines`	Bir bütçe planının satırlarını, dönem ve departman kırılımıyla dışa aktar	`versionId`Belirli bir plan versiyonu; verilmezse en son versiyon kullanılır.
`GET`	`/public-api/invoices`	Müşteri faturalarını listele	`skip`Atlanacak kayıt sayısı. `take`Döndürülecek maksimum kayıt sayısı. `status`Fatura durumuna göre filtrele.
`GET`	`/public-api/transactions`	İşlemleri listele	`page`params.transactions.page `limit`params.transactions.limit `sortBy`params.transactions.sortBy `sortOrder`params.transactions.sortOrder `search`params.transactions.search `accountId`Hesap ID'sine göre filtrele. `categoryId`Kategori ID'sine göre filtrele. `contactId`Kişi ID'sine göre filtrele. `type`İşlem tipine göre filtrele. `status`İşlem durumuna göre filtrele. `statuses`Birden fazla duruma göre filtrele (virgülle ayrılmış). `startDate`Başlangıç tarihine göre filtrele, ISO 8601. `endDate`Bitiş tarihine göre filtrele, ISO 8601. `minAmount`Minimum tutar. `maxAmount`Maksimum tutar. `tags`Etiketlere göre filtrele (virgülle ayrılmış veya tekrarlanan). `isRecurring`Yalnızca tekrarlayan işlemleri getirmek için true. `orgUnitIds`Departman ID'lerine göre filtrele (virgülle ayrılmış).
`GET`	`/public-api/transactions/:id`	Tekil işlem detayı getir	—

Hata Yanıtları

API standart HTTP durum kodlarını döndürür.

Status	Meaning
`401`	Eksik, geçersiz veya iptal edilmiş API anahtarı.
`403`	API anahtarı gerekli yetkiye sahip değil.
`404`	Kaynak, anahtarın bağlı olduğu şirkette/kiracıda bulunamadı.

Örnek İstekler

Aşağıdaki komutları kopyalayıp yapıştırabilirsiniz. orbit_live_xxx kısmını kendi API anahtarınızla değiştirin.

List accounts

curl -H "x-api-key: orbit_live_xxx" https://orbitcashflow.com/api/v1/public-api/accounts

List transactions (paginated)

curl -H "x-api-key: orbit_live_xxx" "https://orbitcashflow.com/api/v1/public-api/transactions?page=1&limit=50"

Get a single transaction

curl -H "x-api-key: orbit_live_xxx" https://orbitcashflow.com/api/v1/public-api/transactions/00000000-0000-0000-0000-000000000000

Webhooklar

Webhooklar, kaydettiğiniz uç noktalara gerçek zamanlı olay bildirimleri gönderir. Şirket yöneticileri webhook'ları şuradan oluşturup yönetebilir: Ayarlar → Şirket → Webhooklar.

Olay tipleri

Bir webhook kaydederken aşağıdaki olay tiplerinden bir veya daha fazlasını seçin:

transaction.created Bir işlem oluşturulduğunda gönderilir.
invoice.created Bir fatura oluşturulduğunda gönderilir.
budget.created Bir bütçe oluşturulduğunda gönderilir.

Payload

Her teslimat şu şekle sahip bir JSON POST'tur:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "event": "transaction.created",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "data": {}
}

Header'lar

Her istekte aşağıdaki header'lar bulunur:

X-Orbit-Event: transaction.createdX-Orbit-Signature: sha256=...

İmza doğrulama

Raw istek gövdesini webhook secret'ınızla HMAC-SHA256 ile hashleyerek teslimatları doğrulayın.

const crypto = require('crypto');

const signature = crypto
  .createHmac('sha256', secret)
  .update(rawBody)
  .digest('hex');

// Compare signature with the value after "sha256=" in X-Orbit-Signature

Hesaplanan hex digest değerini X-Orbit-Signature header'ındaki sha256= sonrasındaki değerle karşılaştırın.