4invoices API'sinde kimlik doğrulama

client_id ve client_secret'ı bir saat geçerli Bearer token ile değiştirirsiniz, yalnızca sunucudan sunucuya.

client_id ve client_secret'ı bir saat geçerli Bearer token ile değiştirirsiniz, yalnızca sunucudan sunucuya.

← API dokümantasyonuna dön

6 adımda ilk fatura

  1. Kimlik bilgisini panelde Faturalama → Ayarlar → API erişimi altında oluşturun ve client_secret değerini hemen kopyalayın — yalnızca bir kez gösterilir.
  2. grant_type client_credentials, client_id ve client_secret ile POST /v1/auth/token gönderin.
  3. Karşılığında access_token, token_type Bearer, expires_in 3600 ve verilen scopes listesini alırsınız.
  4. Diğer her çağrıda token’ı Authorization: Bearer <access_token> başlığına koyun.
  5. Gerçekte ne aldığınızı GET /v1/me ile kontrol edin: tenant, scopes ve güncel hız kovaları.

Tüm uç noktalar

MetotUç noktaScopeIdempotency-Keyİstek / dakika
POST/auth/token
Kimlik bilgilerini erişim token'ı ile değiştir
——120
GET/me
Kiracı, scope'lar ve mevcut limitler
invoices:read—120

4invoices API'si nedir

bash
curl -sS -X POST https://api.4invoices.net/v1/auth/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "cli_XXXXXXXXXXXX",
    "client_secret": "sec_XXXXXXXXXXXXXXXXXXXX"
  }'

# → {"access_token":"eyJ...","token_type":"Bearer","expires_in":3600,
#    "scope":"invoices:read invoices:write efactura:submit"}
bash
curl -sS https://api.4invoices.net/v1/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → kiracı, verilen scope'lar ve mevcut hız limiti kovaları
javascript
// Token'ı önbelleğe alın; her istekte yeni bir token üretmeyin.
let cached = { token: "", expiresAt: 0 };

async function getToken() {
  if (cached.token && Date.now() < cached.expiresAt - 60_000) return cached.token;

  const res = await fetch("https://api.4invoices.net/v1/auth/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "client_credentials",
      client_id: process.env.FOURINVOICES_CLIENT_ID,
      client_secret: process.env.FOURINVOICES_CLIENT_SECRET,
    }),
  });
  if (!res.ok) throw new Error(`token ${res.status}`);

  const data = await res.json();
  cached = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return cached.token;
}

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Scope'lar

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Yalnızca sunucudan sunucuya. API'yi tarayıcı JavaScript'inden asla çağırmayın: client_secret ziyaretçiye ulaşır ve CORS zaten her origin'i engeller.

Hatalar

DurumTipKod
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Sık yapılan hatalar

  • Token endpoint’inin IP başına kendi sınırı vardır. Süresi dolmadan yenilenen, süreç başına bir token — istek başına bir tane değil.
  • client_secret yalnızca hash olarak saklanır; kaybederseniz yeni bir kimlik bilgisi oluşturur ve eskisini iptal edersiniz.
  • ERP, mağaza ve iç betikler için her biri en az scopes’a sahip ayrı kimlik bilgileri oluşturun. Birini iptal etmek diğerlerini etkilemez.
  • CORS hiçbir browser origin’e izin vermez: API tasarım gereği server-to-server’dır.

Geliştiriciler için soru ve cevaplar

client_secret yanlışsa ne olur?

invalid_client code değeriyle 401 alırsınız. Fazla kısa bir gizli anahtar daha erken, doğrulama aşamasında, 422 validation_failed ve param client_secret ile başarısız olur.

Ayrı bir test ortamı var mı?

Hayır. Tek bir üretim sunucusu vardır. Proformalarla (document_kind proforma) ve mali numara tüketmeyen /invoices/preview-totals ile test edin.

Mevcut bir kimlik bilgisinin scopes’unu daraltabilir miyim?

Evet, panelden. Daha önce verilmiş token’lar, oluşturuldukları scopes’u süreleri dolana kadar, yani en fazla bir saat içinde korur.