Autentifikavimas 4invoices API

Pakeiskite client_id ir client_secret į vienos valandos Bearer žetoną — tik serveris–serveris.

Pakeiskite client_id ir client_secret į vienos valandos Bearer žetoną — tik serveris–serveris.

← Atgal į API dokumentaciją

Pirmoji sąskaita per 6 žingsnius

  1. Sukurkite prieigos duomenis skydelyje, skiltyje Sąskaitos → Nustatymai → API prieiga, ir iš karto nukopijuokite client_secret — jis rodomas vieną kartą.
  2. Siųskite POST /v1/auth/token su grant_type client_credentials, client_id ir client_secret.
  3. Gausite access_token, token_type Bearer, expires_in 3600 ir suteiktų scope'ų sąrašą.
  4. Kiekvienam kitam kvietimui įdėkite žetoną į Authorization: Bearer <access_token> antraštę.
  5. Patikrinkite, ką tiksliai gavote, su GET /v1/me: tenant, scope'ai ir dabartiniai limitai.

Visi galiniai taškai

MetodasGalinis taškasScopeIdempotency-KeyUžklausų / min.
POST/auth/token
Pakeiskite prieigos duomenis į prieigos žetoną
——120
GET/me
Tenant, scope'ai ir dabartiniai limitai
invoices:read—120

Kas yra 4invoices API

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"

# → tenant, suteikti scope'ai ir dabartinės limitų grupės
javascript
// Įsiminkite žetoną; neimkite naujo kiekvienai užklausai.
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'ai

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Tik serveris–serveris. Niekada nekvieskite API iš naršyklės JavaScript: client_secret pasiektų lankytoją, o CORS vis tiek blokuoja visas kilmes.

Klaidos

BūsenaTipasKodas
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Dažniausios klaidos

  • Žetono galiniam taškui taikomas atskiras IP limitas. Vienas žetonas kiekvienam procesui, atnaujinamas prieš galiojimo pabaigą — ne vienas kiekvienai užklausai.
  • client_secret saugomas tik kaip maiša; jei jį praradote, sukurkite naujus prieigos duomenis ir panaikinkite senus.
  • Sukurkite atskirus prieigos duomenis ERP, parduotuvei ir vidiniams scenarijams, kiekvienam su minimaliais scope'ais. Panaikinus vienus, kiti nenukenčia.
  • CORS neleidžia jokios naršyklės kilmės: API sukurta pagal modelį serveris–serveris.

Kūrėjų klausimai ir atsakymai

Kas nutinka, jei client_secret neteisingas?

Gausite 401 su kodu invalid_client. Per trumpas secret nukrenta anksčiau, validacijoje: 422 validation_failed ir param client_secret.

Ar yra atskira testavimo aplinka?

Ne. Yra tik vienas gamybinis serveris. Testuokite su proforma sąskaitomis (document_kind proforma) ir su /invoices/preview-totals, kuris nesunaudoja fiskalinio numerio.

Ar galiu susiaurinti esamų prieigos duomenų scope'us?

Taip, skydelyje. Jau išduoti žetonai išlaiko sukūrimo metu suteiktus scope'us iki galiojimo pabaigos, per vieną valandą.