İçindekiler

API referansı

Panelin, saha uygulamasının ve B2B portalının kullandığı API’nin aynısı. Bu sayfa API’nin şeklini anlatır; uçların tek tek imzaları canlı referanstadır.

Canlı referans

Çalışan API, OpenAPI dokümanını ve gezilebilir bir referansı kendi üzerinden yayınlar. Her ucun gerçek istek ve cevap şeması oradadır ve koddan üretildiği için gerçekten güncel olan tek kaynak odur.

Referans arayüzü ve /openapi/v1.json yalnızca geliştirme ortamında yayınlanır, bu kurulumda kapalıdır — bu yüzden buraya bir bağlantı konmuyor. Depoyu kendi makinenizde çalıştırdığınızda API’nin kendi adresi üzerinden /scalar/v1 açılır; şemanın üretimde bir kopyası gerekiyorsa bir ortamdan alınıp dağıtılması gerekir.

Kimlik doğrulama #

Giriş kiracı, e-posta ve parola üçlüsüyle yapılır. Kiracı bir kısaltmadır (örneğin ege): aynı e-posta iki farklı dağıtıcıda bulunabilir ve hangisine girildiği kullanıcının değil, isteğin bilgisidir.

Cevap bir JWT ve süresini döner; ayrıca kullanıcının adı, dili, kiracı kimliği, para birimi, birincil organizasyon birimi ve yetki listesi gelir. Yetki listesi arayüzün neyi göstereceğine karar vermesi içindir — yetkilendirmenin kendisi sunucuda uygulanır.

POST /auth/login

{
  "tenant": "ege",
  "email": "[email protected]",
  "password": "•••••••••",
  "device": {
    "installationId": "b7f1…",
    "platform": "android",
    "model": "SM-A155F",
    "osVersion": "14",
    "appVersion": "1.4.0"
  }
}

→ 200
{
  "accessToken": "eyJhbGciOi…",
  "expiresAt": "2026-08-20T19:23:00+00:00",
  "userId": "…", "fullName": "…", "email": "…", "locale": "tr-TR",
  "tenantId": "…", "tenantSlug": "ege", "currency": "TRY",
  "primaryOrgUnitId": "…",
  "permissions": ["orders.write", "pricing.read", "…"],
  "deviceId": "…"
}

Giriş isteği. Cihaz bloğu isteğe bağlıdır ve yalnızca el terminalleri gönderir.

Sonraki isteklerde Authorization: Bearer <token> gönderilir. GET /auth/me jetonun çözülmüş hâlini döner: kiracı, kullanıcı, cihaz, organizasyon kökleri, yetkiler ve para birimi.

Jeton uzun ömürlüdür — varsayılan on iki saat, bir tam çalışma günü. Bu bilinçli bir tercih: 09:00’da bir köyde bağlantısını kaybeden bir temsilcinin bütün turu çalışabilmesi gerekir, ve gün ortasında biten bir jeton bir ağ sorununu kaybedilen bir güne çevirir. Gerçekten önemli olan iptaller — engellenmiş cihaz, askıya alınmış kullanıcı — istek yolunda veritabanına karşı kontrol edilir.

Kiracı ve organizasyon yalıtımı jetondan okunur ve PostgreSQL satır düzeyi güvenliğine aktarılır. Yani bir sorgunun ne göreceği uygulama kodundaki bir filtreye değil, veritabanı politikasına bağlıdır.

Hata sözleşmesi #

Hatalar RFC 7807 problem detayı olarak döner ve her biri makine tarafından okunabilir bir code taşır. İstemciler koda göre dallanır, metne göre değil: order.credit_hold onay akışını açar, visit.outside_geofence sebep sorar, sync.transient sonra yeniden dene demektir. Metne göre dallanmak, kopya çevrildiği an bozulur.

Durum	Ne zaman
400 request.malformed	Gövde ya da sorgu değeri okunamadı. Çağıranın hatasıdır, sunucunun değil.
401 auth.invalid_credentials, auth.no_access	Kimlik doğrulanamadı.
403 auth.forbidden, sync.device_blocked	Yetki yok ya da cihaz engellenmiş.
404 not_found, sync.unknown_device	Kayıt ya da cihaz bulunamadı.
409 order.credit_hold, inventory.insufficient_stock, concurrency.conflict	İstek geçerli ama şu anki durumla çelişiyor.
422 (diğer tüm iş kuralı kodları)	Bir iş kuralı isteği reddetti.

Problem gövdesi ayrıca kodun kendi ek alanlarını taşır — örneğin geçersiz bir teslimat sebep kodu, kabul edilen kodların tamamını yanında getirir; bir eşzamanlılık çakışması beklenen ve gerçekleşen sürümü verir.

Kaynak grupları #

Uçlar tek bir ağaçta toplanır. Yazma uçları, ait oldukları okuma uçlarıyla aynı yolda durur: bir ürün POST /catalog/products altında oluşturulur, ayrı bir /admin/products altında değil — ayrı bir yönetim API’si zaman içinde aynı satırlar hakkında kendi farklı görüşünü geliştirir.

Grup	Ne yapar
/auth	Giriş ve çağıranın kimliği.
/customers	Müşteri listesi ve müşteri 360, yakındaki müşteriler, müşteri oluşturma ve güncelleme. Ekstre de bu ağacın altındadır.
/catalog	Ürünler, barkod arama, markalar, kategoriler; ürün, marka ve kategori yazma, ürün arşivleme.
/pricing	Fiyat açıklaması, fiyat listeleri ve satırları, liste ve satır yazma/silme.
/promotions	Kampanya listesi, mekanik kataloğu, simülasyon, yayına alma ve duraklatma, performans, kampanya yazma.
/orders	Teklif, sipariş oluşturma ve listeleme, sipariş takibi, onay, iptal, risk askısı serbest bırakma ve siparişin olay akışı.
/field	Günün rutu, ziyaret açılış/kapanış/atlama, rutlar ve rut yazma, canlı saha görünümü.
/inventory	Depolar, stok seviyeleri, stok hareketleri; depo ve araç yazma. Stok sayım oturumları da buradadır: sayım açma, satır kaydetme, kapatma ve terk etme.
/approvals	Bekleyen onaylar, onay talepleri ve tek bir talebin zinciri, onaylama ve reddetme, onaya gidebilen konuların listesi ve onay kuralları.
/shipments	Sevkiyat listesi ve detayı, planlanabilir siparişler, planlama, yükleme, durak teslimi ve durak başarısızlığı, teslimat sebep kodları.
/invoices	Fatura listesi ve detayı, fatura kesme.
/payments	Tahsilat listesi, tahsilat alma, çek tahsili ve karşılıksız işaretleme.
/sync	Cihaz gönderimi ve çekişi. Aşağıda ayrıca anlatılıyor.
/analytics	Panel özeti ve güne göre satış.
/ai	Yapay zekâ katmanı: durum, günün özeti, soru sorma, müşteri brifingi, önerilen sepet, öneri geri bildirimi, doğal dilden sipariş ayrıştırma, kullanım ve bütçe.
/integrations	Bağlayıcı türleri, bağlayıcılar, yoklama, iş kuyruğu (kuyruğa alma, çalıştırma, yeniden çalıştırma, boşaltma), sağlık ve web kancası abonelikleri.
/imports	İçe aktarma türleri, şablon indirme ve dosya işleme.
/media	Medya türleri, kayıt, içerik yükleme ve indirme. Kayıt ve baytlar ayrı adımlardır: bir teslimat, baytları henüz gelmemiş bir medya kimliğine karşı kapanabilir.
/admin	Organizasyon birimleri, kullanıcılar, roller ve yetki kataloğu; kullanıcı ve rol yazma.
/health	Sağlık kontrolü. Kimlik doğrulaması istemez.

Senkronizasyon protokolü #

İki uç: bir gönderim, bir çekiş. Protokolün tamamı ve gerekçesi çevrimdışı model sayfasında; burada yalnızca aktarım şekli var.

Gönderim — POST /sync/push #

Gövde bir cihaz kimliği ve bir işlem listesi taşır. Her işlem şu zarfı kullanır:

id — istemcinin ürettiği kimlik. Bu işlemin tekrarsızlık anahtarıdır.
clientSequence — cihazın yerel günlüğündeki sırası. Sunucu işlemleri dizideki sıraya değil buna göre uygular.
command — işlem türü.
entityId — varsa hedef varlık.
payload — komuta özel gövde; burada opak tutulur, işleyicisi doğrular.
occurredAt — temsilcinin işlemi yaptığı andaki cihaz saati.

Cevap işlem başına bir satır döner: durum (applied, duplicate, rejected, failed), varlık kimliği, hata kodu ve mesajı, ve cihazın benimsemesi gereken sunucu hesabı değerler. Yığın özeti olarak kabul edilen, reddedilen ve mükerrer sayıları ile sunucunun o anki dizi imleci de gelir.

POST /sync/push

{
  "deviceId": "<cihaz>",
  "operations": [
    {
      "id": "0192f0c1-…",
      "clientSequence": 4417,
      "command": "order.create",
      "entityId": null,
      "payload": { "customerId": "…", "lines": [ … ] },
      "occurredAt": "2026-08-20T07:41:12+03:00"
    }
  ]
}

→ 200
{
  "results": [
    { "id": "0192f0c1-…", "status": "applied", "entityId": "…",
      "result": { "number": "ORD-2026-004417", "status": "confirmed",
                  "netTotal": 12480.00, "discountTotal": 940.00,
                  "creditHoldReasonCode": null,
                  "creditHoldReasonValues": {},
                  "creditHoldReason": null } }
  ],
  "serverCursor": 48991,
  "accepted": 1, "rejected": 0, "duplicates": 0
}

Bir gönderim ve cevabı. Aynı yığın tekrar gönderilse ikinci işlem duplicate dönerdi.

Çekiş — GET /sync/pull #

Sorgu parametreleri: deviceId, cursor ve limit. İmleç tek bir tam sayıdır ve her senkronize satıra global bir diziden damgalanan sürüm numarasına karşılık gelir. Cevap, imleçten büyük satırları koleksiyon adına göre gruplanmış olarak, yeni imleci, devamı olup olmadığını, sunucu saatini ve koleksiyon başına satır sayılarını döner.

Sınır tablo başına uygulanır, sayfa başına değil; varsayılanı ve tavanı 500’dür. Böylece tek bir büyük tablo diğerlerini aç bırakamaz. Boş koleksiyonlar cevaba hiç konmaz.

Sunucunun cihaz kaydındaki imleç, yalnızca bir sayfa eksiksiz teslim edildiğinde ilerler. Tablo tablo ilerletmek, yarıda kesilen bir çekişin cihazın hiç almadığı satırların üzerinden atlamasına izin verirdi.

Entegratör için not #

ERP bağlantısı için doğru yol bu API’dir, veritabanına doğrudan bağlanmak değil. Simüle edilmiş bağlayıcılar bilinçli olarak gerçek hata biçimlerini üretir — kabul edilmiş ama kaydedilmemiş belge, mali numarasız e-Fatura, kapanmış muhasebe dönemi — ve bağlayıcı yapılandırmasına yazılabilen bir zorlanmış hata ayarı, bir entegratörün kendi hata yollarını belirlenimci biçimde kanıtlamasına yarar. Ayrıntısı entegrasyonlar sayfasında.