Kimlik Doğrulama

İki yöntem vardır. Hangisini seçeceğiniz, mükellefin kimlik bilgisini nasıl verdiğine bağlıdır.

	API Anahtarı	OAuth 2.0
Kurulum	mükellef anahtarı kopyalar, size yapıştırır	mükellef "Bağlan" der, onay ekranından geçer
Kim üretir	mükellef, kendi panelinden	siz, kayıtlı istemcinizle
Kaç mükellef	anahtar başına bir firma	istemci başına sınırsız firma
Uygun olduğu yer	tek mükellef, kendi mağazası, hızlı başlangıç	çok mükellefli ürünler, mağaza uygulamaları

Partner uygulaması mısınız?

Her ikisi de mükellefin kimliğidir. Sunucunuzun kendi kimliğini kanıtladığı HMAC imzası ayrıdır — bkz. Partner İmzası.

Yeni başlıyorsanız API anahtarıyla başlayın. Ürününüzü çok sayıda mükellefe satacaksanız OAuth'a geçin — kopyala-yapıştır adımı ortadan kalkar.

API anahtarı

Mükellef, panelinden Ayarlar → API Anahtarları yolundan anahtar üretir ve size verir. Anahtarın açık hâli yalnızca üretildiği anda gösterilir; sonrasında yalnız ilk 16 karakteri görünür.

Her istekte X-Api-Key başlığıyla gönderin:

curl https://sandbox-api.finansfatura.com/v1/integrations/orders \
  -H "X-Api-Key: ff_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Anahtarlar mükellef tarafından iptal edilebilir ve son kullanma tarihi taşıyabilir. İptal edilmiş ya da süresi geçmiş anahtar 401 döner.

Anahtarı istemci tarafında tutmayın

API anahtarı, mükellefin firmasında sizin adınıza işlem yapar. Tarayıcıda, mobil uygulamada veya mükellefin erişebileceği yapılandırma dosyalarında saklamayın. Sunucu tarafında, şifreli tutun.

OAuth 2.0

Standart authorization code akışıdır (RFC 6749), PKCE destekler. Çok mükellefli uygulamalar için doğru yöntemdir.

Önce bir istemci kaydı almanız gerekir — client_id, client_secret ve redirect_uri allowlist'i için [email protected] adresine yazın.

1. Mükellefi onay ekranına yönlendirin

https://sandbox-app.finansfatura.com/oauth/authorize
  ?client_id=<client_id>
  &redirect_uri=<kayıtlı redirect_uri>
  &response_type=code
  &scope=invoice:read invoice:write
  &code_challenge=<PKCE challenge>
  &code_challenge_method=S256

redirect_uri birebir kayıtlı adreslerden biri olmalıdır; kısmi eşleşme kabul edilmez. İstenen scope'lar istemcinize tanımlı scope'ların alt kümesi olmalıdır.

2. Kodu token'a çevirin

curl -X POST https://sandbox-api.finansfatura.com/v1/oauth/token/ \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=<kod> \
  -d redirect_uri=<redirect_uri> \
  -d client_id=<client_id> \
  -d client_secret=<client_secret> \
  -d code_verifier=<PKCE verifier>

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "invoice:read invoice:write"
}

Sondaki eğik çizgi zorunlu

Token ve revoke adresleri /v1/oauth/token/ ve /v1/oauth/revoke/ biçimindedir. Eğik çizgisiz hâli yönlendirilmez.

3. Token'ı kullanın

curl https://sandbox-api.finansfatura.com/v1/integrations/orders \
  -H "Authorization: Bearer <access_token>"

Yenileme ve iptal

refresh_token ile aynı uçtan grant_type=refresh_token göndererek yenilersiniz. Her yenilemede yeni bir refresh token verilir ve öncekiler geçersizleşir — en son aldığınızı saklayın.

Bağlantıyı sonlandırmak için /v1/oauth/revoke/ ucuna token'ı gönderin. Mükellef de panelinden bağlantıyı kesebilir. Revoke her zaman 200 döner ve yalnız refresh token'ı düşürür — ayrıntı ve mükellef kimliğini doğrulama için bkz. Üretim vs Sandbox.

Scope'lar

Scope	İzin
invoice:read	fatura ve satış durumu okuma
invoice:write	satış oluşturma, fatura kesme, iptal

Yalnızca ihtiyacınız olanı isteyin. Sipariş aktarıp durum okuyan bir entegrasyon için ikisi de gerekir; sadece rapor çeken bir entegrasyon için invoice:read yeterlidir.

Firma kapsamı

Anahtar ya da token, tek bir mükellef firmasına bağlıdır. Gönderdiğiniz her kayıt o firmanın verisidir; firma kimliğini istekte ayrıca belirtmezsiniz ve başka bir firmanın verisine erişemezsiniz.