API

API genel bakış

Tüm Kerte ürünleri REST API üzerinden erişilebilir. Auth, OpenAPI sözleşme ve typed clients standart.

Auth

Her API çağrısı Bearer token ile authenticate olur. Token’ı panelden oluşturursun (Hesap → API Keys).

curl https://api.kerte.tr/v1/tesvik/calculations \
  -H "Authorization: Bearer YOUR_TOKEN"

Token’lar:

• Personal access — kullanıcıya bağlı, tüm yetkiler
• Service account — uygulamaya özel, scope’lu (ör. tesvik:read)
• Kısa-ömürlü — opsiyonel TTL (1 saat – 90 gün)

Endpoint’ler

Modül	Base URL
Tesvik	https://api.kerte.tr/v1/tesvik
E-Vizite	https://api.kerte.tr/v1/e-vizite
Common	https://api.kerte.tr/v1/common

OpenAPI sözleşme

Her API’nin OpenAPI 3.1 dokümanı https://api.kerte.tr/v1/<module>/openapi.json adresinde. Bu sözleşmeden:

• TypeScript client (openapi-typescript-codegen)
• Python client (openapi-python-client)
• Postman collection

otomatik üretilebilir. Resmi @kerte/api-client paketi (TS) yakında.

Rate limit

Tier	Limit
Başlangıç	60 req/min
Büyüme	600 req/min
Ölçek	6000 req/min
Enterprise	Anlaşmaya göre, sınırsız mümkün

429 dönerse Retry-After header’ına bakıp bekle.

Webhook

Olay-odaklı entegrasyon için webhook (Ölçek tier ve üzeri):

Olay	Açıklama
tesvik.calculation.completed	Hesaplama tamamlandı
tesvik.error.detected	Hatalı teşvik tespit edildi
e-vizite.report.created	Yeni e-vizite raporu sync edildi
e-vizite.approval.changed	Onay durumu değişti

Payload HMAC-SHA256 imzalıdır; doğrulama docs/api/webhooks (yakında) sayfasında.