Avtentikacija v API 4invoices

Zamenjate client_id in client_secret za enourni žeton Bearer, izključno strežnik-strežnik.

Zamenjate client_id in client_secret za enourni žeton Bearer, izključno strežnik-strežnik.

← Nazaj na dokumentacijo API

Prvi račun v 6 korakih

  1. Poverilnico ustvarite v panelu, pod Izstavljanje računov → Nastavitve → Dostop do API, in takoj kopirajte client_secret — prikaže se samo enkrat.
  2. Pošljite POST /v1/auth/token z grant_type client_credentials, client_id in client_secret.
  3. V odgovor dobite access_token, token_type Bearer, expires_in 3600 in seznam dodeljenih obsegov.
  4. Žeton vstavite v glavo Authorization: Bearer <access_token> pri vseh drugih klicih.
  5. Kaj ste dejansko dobili, preverite z GET /v1/me: najemnik, obsegi in trenutne kvote omejitev.

Vse končne točke

MetodaKončna točkaScopeIdempotency-KeyZahtev / minuto
POST/auth/token
Zamenjaj poverilnice za dostopni žeton
——120
GET/me
Najemnik, scopi in trenutne omejitve
invoices:read—120

Kaj je API 4invoices

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"

# → najemnik, odobreni scopi in trenutne omejitve
javascript
// Žeton shranite v predpomnilnik; ne ustvarjajte ga za vsak zahtevek.
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

Scopi

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Samo strežnik-strežnik. Nikoli ne kličite API iz brskalniškega JavaScripta: client_secret bi prišel do obiskovalca, CORS pa tako ali tako blokira vsak origin.

Napake

StanjeTipKoda
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Pogoste napake

  • Končna točka za žetone ima lastno omejitev na IP-naslov. En žeton na proces, osvežen pred potekom — ne en na zahtevo.
  • client_secret se hrani samo kot zgoščena vrednost; če ga izgubite, ustvarite novo poverilnico in prekličete staro.
  • Za ERP, spletno trgovino in notranje skripte izdajte ločene poverilnice, vsako z najmanjšimi obsegi. Preklic ene ne vpliva na druge.
  • CORS ne dovoli nobenega izvora iz brskalnika: API je zasnovan izključno za komunikacijo strežnik-strežnik.

Vprašanja in odgovori za razvijalce

Kaj se zgodi, če je client_secret napačen?

Dobite 401 s kodo invalid_client. Prekratka skrivnost pade že prej, pri validaciji, z 422 validation_failed in param client_secret.

Ali obstaja ločen peskovnik?

Ne. Obstaja en produkcijski gostitelj. Testirajte s predračuni (document_kind proforma) in z /invoices/preview-totals, ki ne porabi davčne številke.

Ali lahko obstoječi poverilnici zožim obsege?

Da, v panelu. Že izdani žetoni obdržijo obsege, s katerimi so bili ustvarjeni, do poteka, torej najpozneje v eni uri.