Nexvera · Geliştirici Dokümantasyonu

Mimari

Bridge gateway URL slug'a göre arka uçları yönlendirir; her ürün bağımsız deploy edilir, ortak gateway sadece TLS, auth ve rate-limit yapar. Mevcut ürünler, slug haritası:

URL	Ürün	Audience
`bridge.nexvera.ai/v1/logo/*`	Logo ERP Bridge	`bridge.api`
`bridge.nexvera.ai/v1/menu/*`	NexveraQR menü	`qr.menu`
`bridge.nexvera.ai/v1/pos/*`	MaxResto POS	`pos.resto`
`bridge.nexvera.ai/v1/fiyatgor/*`	FiyatGör API	`fiyatgor`
`ai.nexvera.ai/v1/ocr/*`	OCR (Tesseract TR/EN)	—
`ai.nexvera.ai/v1/face/*`	Yüz tanıma (FaceRecognition)	—
`ai.nexvera.ai/v1/embedding/*`	Ürün embedding + vision	—
`auth.nexvera.ai`	Identity (passkey + JWT)	—

Kimlik — passkey-first

Tüm Nexvera ürünleri auth.nexvera.ai üzerinden federate olur. Yeni kullanıcı için FIDO2 / WebAuthn passkey öncelikli, password fallback olarak mevcut. Token RS256 ile imzalanır; public anahtar /.well-known/jwks.json üzerinden yayınlanır.

Login akışı

POST https://auth.nexvera.ai/auth/login
Content-Type: application/json

{
  "tenantSlug": "demo",
  "email":      "user@example.com",
  "password":   "opsiyonel — passkey kullanılıyorsa boş",
  "audience":   "qr.menu"     // hangi ürüne giriş — token aud claim
}

JWKS & discovery

GET https://auth.nexvera.ai/.well-known/openid-configuration
GET https://auth.nexvera.ai/.well-known/jwks.json

Audience listesi

bridge.api · qr.menu · pos.resto · fiyatgor · arsiv · envanter · crm · panel

Bridge — Logo ERP

On-premise nexvera-agent (Rust) Logo MSSQL veritabanını okur, değişiklikleri Bridge.Api'ye HMAC v1 imzalı POST'larla akıtır. Enterprise tier'da agent ayrıca yazma jobs'larını /jobs/pending'den çekip yerel sidecar üzerinden Logo Object Designer'a uygular.

HMAC v1 (agent imzası)

Canonical string (LF ayraçlı):

timestamp \n nonce \n METHOD \n PATH \n sha256_hex(body)

HMAC-SHA256, hex'e dönüştür, header'a koy:

X-Bridge-Key-Id:     agent-acme-001
X-Bridge-Timestamp:  1779030000          (unix seconds, ±5dk pencere)
X-Bridge-Nonce:      16-byte hex, replay korumalı 10dk
X-Bridge-Signature:  hmac-sha256 hex

Okuma endpoint'leri (ingest)

Agent şu path'lere POST atar:

/ingest/cari · /ingest/stok · /ingest/hizmet · /ingest/fatura · /ingest/irsaliye · /ingest/siparis · /ingest/cek-senet · /ingest/banka{/hesap,/hareket} · /ingest/kasa{/hareket}

Yazma akışı (Enterprise)

POST   bridge.nexvera.ai/v1/logo/api/v1/cari        (JWT, kullanıcı)
            ↓ enqueue
       bridge_jobs (Postgres, status=pending)
            ↑ poll
GET    bridge.nexvera.ai/api/v1/jobs/pending        (HMAC, agent)
POST   /jobs/{id}/start    → 204 | 409              (claim)
POST   sidecar:/tiger/execute  (bearer)              (yerel OD COM)
POST   /jobs/{id}/complete  body: {logoLogicalRef}   (sonuç)
POST   /jobs/{id}/fail      body: {errorMessage}

AI

ai.nexvera.ai altında üç servis:

OCR — Tesseract Türkçe/İngilizce + pdf2image. Fatura, arşiv belgesi, e-arşiv PDF.
Face — dlib + face_recognition. PDKS demo, kimlik doğrulama.
Embedding & Vision — torch + ultralytics YOLO + Claude Vision. FiyatGör'ün ürün tanıma altyapısı.

Hızlı başlangıç

Curl ile health

curl https://bridge.nexvera.ai/health
{"status":"ok"}

Identity ile token al

curl -X POST https://auth.nexvera.ai/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"tenantSlug":"demo","email":"...","password":"...","audience":"bridge.api"}'

Token ile bir endpoint çağır

curl https://bridge.nexvera.ai/v1/logo/api/v1/cari \
  -H "Authorization: Bearer $TOKEN"

Tier matrisi

Özellik	Core	Pro	Enterprise
Okuma (Logo → Bridge)	✓	✓	✓
Hazır raporlar (XLSX/PDF)	5	20	tümü
Yazma (Bridge → Logo)	—	—	✓
Job kuyruğu	—	—	✓
Tiger Object Designer sidecar	—	—	✓
FIDO2 passkey	✓	✓	✓
HMAC v1 agent auth	✓	✓	✓
Rate limit (req/dk)	60	300	özel

Operasyonel

status.nexvera.ai — Uptime Kuma monitor
logs.nexvera.ai — Grafana + Loki (auth gerekli)
git.nexvera.ai — Gitea + Actions runner

Tek API.Tüm Nexvera ürünleri.