Kimlik doğrulama (Authentication)

Tüm isteklere Authorization: Bearer entgr_… başlığını eklersin. Anahtar tek parçadır, tüm uçlarda aynı şekilde kullanılır.

Base URL: tüm uçlar https://api.entegrasyoner.com/v1/... altındadır.

API Anahtarı nasıl alınır

1. Portal'a (app.entegrasyoner.com) bir kere giriş yap (tarayıcı).

2. Sol menü → API Bağlantıları → Yeni Bağlantı.

3. Bağlantı Yönü: Kaynak · Kaynak Türü: Web Servis (API).

4. Bağlantı Adı: entegrasyonu temsil eden bir ad gir (örn. "Mikro ERP", "Logo Cron").

5. Kaydet → açılan modal'da anahtar bir kere görünür:

   entgr_a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6...
   [📋 Kopyala]

6. Anahtarı kopyala, ERP / cron config'ine (env var, secret manager) yapıştır → "Anladım, sakladım".

Bu anahtar bir daha gösterilmez. Veritabanında yalnızca SHA-256 özeti tutulur. Kaybedersen tek çare yeni anahtar üretmektir ("Anahtarı Yenile").

İstek atma

curl https://api.entegrasyoner.com/v1/me \
  -H 'Authorization: Bearer entgr_a1B2c3...' \
  -H 'Accept: application/json'

Accept: application/json mutlaka ekle — eksikse hatalar HTML olarak dönebilir.

Anahtarı doğrula — GET /v1/me

Anahtarın geçerli olduğunu ve hangi hesaba bağlı olduğunu test eder. Startup / health-check için idealdir.

Başarılı cevap (200):

{
  "user": {"id": 12, "email": "[email protected]", "name": "Örnek", "is_activated": true},
  "plan": "pro",
  "subscription": {
    "status": "active",
    "locked": false,
    "plan_code": "pro",
    "plan_name": "Pro",
    "trial_ends_at": null,
    "period_ends_at": "2026-12-01T00:00:00+00:00",
    "usage": { "products": 1240 }
  },
  "is_impersonating": false,
  "impersonator_email": null
}

• plan = subscription.plan_code (baslangic / pro / kurumsal). subscription.status: trial / active / expired; locked=true ise yazma işlemleri 403 döner (bkz. aşağıdaki abonelik hataları).
• Health-check için subscription.locked + status'a bakman önerilir.

Anahtar geçersiz veya süresi dolmuşsa 401 döner.

Test etme

Ayrı bir test/sandbox ortamı yoktur — tüm istekler canlı API'ye gider (https://api.entegrasyoner.com/v1). Bu API yazma yetkilidir: POST/PUT/DELETE gerçek kataloğu değiştirir ve uygun ürünler pazaryerlerine yayınlanabilir. Güvenli test için:

1. Önce salt-okunur dene: GET /v1/me (anahtar doğrulama) → GET /v1/products (liste). Bunlar hiçbir şeyi değiştirmez.
2. Yazma testinde pazaryerine sızma: test ürünlerini "publish_enabled": false ile oluştur — bu ürün hiçbir pazaryerine gönderilmez, sadece kataloğa yazılır. Akışını doğrula, sonra DELETE /v1/products/{id} ile temizle.
3. Ayrı bir anahtar kullan: entegrasyonu canlıya almadan önce ayrı bir "test" API anahtarı oluştur (portal); audit izi karışmaz, gerekirse tek başına iptal edersin.

Anahtarın özellikleri

Özellik	Davranış
Format	entgr_<rastgele> — tek parça. Sızıntı taraması regex'i: entgr_[A-Za-z0-9]{20,}
Ömür	Varsayılan süresiz. Portal'da opsiyonel expiry tarihi ayarlanabilir.
Tenant kapsamı	Anahtar tek bir tenant'a bağlıdır; başka tenant'ın verisi görünmez/düzenlenemez.
Çoklu anahtar	Aynı tenant'ta birden fazla anahtar olabilir (ERP + cron ayrı), her biri ayrı label ve audit izi taşır.
Kaynak izi	Bu anahtarla yazılan ürünler source_credential_id ile işaretlenir; portalde "🔌 API" rozeti görünür.

Anahtarı yenile / iptal et

• Yenile (rotate): Portal → bağlantının düzenleme ekranı → "Anahtarı Yenile". Eski anahtar derhal 401 döner (grace period yok), yeni anahtar tek seferlik modal'da gösterilir.
• İptal: Portal → "Bağlantıyı Sil". Anahtar 401 alır; bağlı ürünlerin source_credential_id değeri NULL'a düşer (ürünler kaybolmaz).

Hata cevapları

HTTP	Anlam
401 Unauthorized	Anahtar eksik, geçersiz, iptal edilmiş veya süresi dolmuş
422 Unprocessable Entity	Validation hatası — errors objesinde alan bazlı detay
429 Too Many Requests	Rate limit (şu an yalnız inbound/login uçlarında; public v1 API'de henüz aktif değil)
5xx	Sunucu hatası — geçici, üstel backoff ile tekrar dene

Güvenlik

• Anahtarı paylaşma (repo, screenshot, log, public doc). Sızdıysa portaldan "Anahtarı Yenile" ile derhal öldür.
• Yalnızca HTTPS üzerinden taşı — Bearer header açık metindir.
• Tek anahtar = tek entegrasyon ilkesini koru; sızıntıda yalnızca o anahtar iptal edilir.
• Logları entgr_[A-Za-z0-9]{20,} regex'i ile tara (Gitleaks, GitHub secret scanning vb.).