Autentikimi në API-n e 4invoices

Shkëmben client_id dhe client_secret për një token Bearer me vlefshmëri një orë, vetëm server-me-server.

Shkëmben client_id dhe client_secret për një token Bearer me vlefshmëri një orë, vetëm server-me-server.

← Kthehu te dokumentacioni i API-t

Fatura jote e parë në 6 hapa

  1. Krijo kredencialin në panel te Faturim → Cilësime → Aksesi API dhe kopjo client_secret menjëherë — shfaqet vetëm një herë.
  2. Dërgo POST /v1/auth/token me grant_type client_credentials, client_id dhe client_secret.
  3. Merr access_token, token_type Bearer, expires_in 3600 dhe listën e fushëveprimeve të dhëna.
  4. Vendose tokenin në header-in Authorization: Bearer <access_token> në çdo thirrje tjetër.
  5. Kontrollo çfarë more me të vërtetë me GET /v1/me: klientin, fushëveprimet dhe grupet aktuale të kufijve.

Çdo pikë fundore

MetodaPika fundoreFushëveprimiIdempotency-KeyKërkesa / minutë
POST/auth/token
Shkëmbe kredencialet me një token aksesi
——120
GET/me
Klienti, fushëveprimet dhe kufijtë aktualë
invoices:read—120

Çfarë është API e 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"

# → klienti, fushëveprimet e dhëna dhe grupet aktuale të kufijve
javascript
// Ruaje tokenin në memorie të përkohshme; mos krijo një për çdo kërkesë.
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

Fushëveprimet

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Vetëm server-me-server. Mos e thirr kurrë API nga JavaScript i shfletuesit: client_secret do të arrinte te vizitori, dhe CORS e bllokon çdo origjinë në çdo rast.

Gabimet

StatusiLlojiKodi
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Gabimet e zakonshme

  • Pika fundore e tokenit ka kufirin e vet për IP. Një token për proces, i rinovuar para skadimit — jo një për kërkesë.
  • client_secret ruhet vetëm si hash; nëse e humbet, krijon një kredencial të re dhe revokon të vjetrën.
  • Lësho kredenciale të veçanta për ERP-në, dyqanin dhe skriptet e brendshme, secila me fushëveprime minimale. Revokimi i një prej tyre s'prek të tjerat.
  • CORS nuk lejon asnjë origjinë shfletuesi: API është server-me-server me projektim.

Pyetje dhe përgjigje për zhvilluesit

Çfarë ndodh nëse client_secret është i gabuar?

Merr 401 me kodin invalid_client. Një sekret shumë i shkurtër dështon më herët, në validim, me 422 validation_failed dhe param client_secret.

A ekziston sandbox i veçantë?

Jo. Ekziston vetëm një host prodhimi. Testo me proforma (document_kind proforma) dhe me /invoices/preview-totals, që s'konsumon asnjë numër fiskal.

A mund t'i ngushtoj fushëveprimet e një kredenciali ekzistues?

Po, nga paneli. Tokenet e lëshuara më parë mbajnë fushëveprimet me të cilat u krijuan deri në skadim, brenda një ore.