Ana içeriğe geç

Üretim vs Sandbox

Adresler​

ÜretimSandbox
APIhttps://api.finansfatura.comhttps://sandbox-api.finansfatura.com
OAuth onay ekranı (mükellefin tarayıcısı)https://app.finansfatura.com/oauth/authorizehttps://sandbox-app.finansfatura.com/oauth/authorize
TokenPOST {API}/v1/oauth/token/aynı yol
RevokePOST {API}/v1/oauth/revoke/aynı yol

Birbirine taşınmayanlar​

  • Anahtarlar. Sandbox API anahtarı üretimde çalışmaz, üretim anahtarı sandbox'ta çalışmaz.
  • OAuth istemcisi. client_id / client_secret ortam başınadır. Sandbox istemcinizi üretimde kullanamazsınız — her ortam için ayrı istemci kaydı gerekir.
  • Mükellef bağlantısı. Bir mükellefin sandbox'taki OAuth onayı, üretimdeki bağlantısını kurmaz. Her ortamda ayrı yetkilendirme akışı gerekir.
  • Veri. Sandbox'taki satış/fatura/mükellef kayıtları üretime kopyalanmaz.

Üretime geçiş​

  1. OAuth kullanıyorsanız üretim redirect_uri'nizi [email protected] adresine bildirin; üretim istemci kaydını açıp client_id / client_secret'ı tek seferlik paylaşırız. client_secret yalnız o an görünür — kaybederseniz rotasyon gerekir, güvenli saklayın.
  2. redirect_uri tam eşleşir — query/fragment dahil. Sandbox'ta kullandığınız adresle üretimdeki birebir aynı olmak zorunda değildir, ama kayıtlı adresle birebir eşleşmelidir.
  3. Mükellefleri üretim onay ekranına yönlendirin; sandbox'taki onayları taşımaz, her mükellef üretimde ayrıca "Bağlan" demelidir.
  4. İlk fatura kesiminden önce mükellefin e-belge kurulumu tamamlanmış olmalı — tamamlanmamışsa 412 ile döner. Bunu beklemeden görmek için Hesap Durumu ucunu önden sorgulayın.
Hata kodu detayı

412 yanıtının gövdesi ONBOARDING_NOT_STARTED, CONTRACT_PENDING ya da ONBOARDING_FAILED taşır — ayrıntı için Hata Kodları.

PKCE + confidential client birlikte

OAuth akışı hem PKCE (code_challenge + code_challenge_method=S256, takasta code_verifier) hem confidential client (takasta client_id + client_secret) ister — ikisi birbirinin yerine geçmez, ikisi de gerekir. Ayrıntı için Kimlik Doğrulama.

Refresh token rotasyonu​

Her yenilemede eski refresh token düşer, yenisi döner. (istemci, mükellef) başına tek aktif refresh token tutulur — sakladığınız eski token bir sonraki yenilemeden sonra artık geçersizdir, her yenilemede döneni üzerine yazın.

Bağlantıyı kaldırma​

POST {API}/v1/oauth/revoke/
Content-Type: application/json

{"token": "<refresh_token>"}
  • Kimlik doğrulaması gerekmez, her zaman 200 döner — tekrarlı çağrı hatasızdır, zaten iptal edilmiş bir token'ı tekrar göndermek sorun değildir.
  • Yalnız refresh token'ı düşürür. Elinizdeki erişim (access) token'ı kendi TTL'i dolana kadar geçerli kalır; iptal anında anlık kesinti beklemeyin, kısa bir kuyruk süresi vardır. Kendi tarafınızda da jetonları silin.
  • Panel karşılığı Bağlı Uygulamalar'dır (DELETE /v1/oauth/grants/{client_id}): o istemcinin tüm refresh token'larını iptal eder, ek bir adım gerekmez.

Değişmez mükellef kimliği​

GET /v1/companies/

OAuth erişim jetonuyla çağrılır, şirket id'si (tamsayı) ve VKN'yi döner — ikisi de değişmez. Bir mükellef bağlantıyı kesip tekrar kurduğunda, aynı mükellef mi bağlandı diye bunları karşılaştırın; onay ekranı metadata'sı da aynı bilgiyi taşır (GET /v1/oauth/authorize?client_id=… → company_id, company_title).

Farklı bir mükellef seçilirse devralma olmaz: tüm uçlar fk_company_id ile sınırlıdır, yeni jeton eski mükellefin belgelerini göremez (404).