Autentifikācija 4invoices API

Apmainiet client_id un client_secret pret vienas stundas Bearer žetonu — tikai serveris–serveris.

Apmainiet client_id un client_secret pret vienas stundas Bearer žetonu — tikai serveris–serveris.

← Atpakaļ uz API dokumentāciju

Pirmais rēķins 6 soļos

  1. Izveidojiet piekļuves datus panelī sadaļā Rēķini → Iestatījumi → API piekļuve un uzreiz nokopējiet client_secret — tas tiek parādīts vienu reizi.
  2. Nosūtiet POST /v1/auth/token ar grant_type client_credentials, client_id un client_secret.
  3. Saņemsiet access_token, token_type Bearer, expires_in 3600 un piešķirto scope sarakstu.
  4. Ievietojiet žetonu galvenē Authorization: Bearer <access_token> visos pārējos izsaukumos.
  5. Pārbaudiet, ko tieši saņēmāt, ar GET /v1/me: tenant, scope un pašreizējie ierobežojumi.

Visi galapunkti

MetodeGalapunktsScopeIdempotency-KeyPieprasījumi / minūtē
POST/auth/token
Apmainīt piekļuves datus pret piekļuves žetonu
——120
GET/me
Tenant, scope un pašreizējie ierobežojumi
invoices:read—120

Kas ir 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, piešķirtie scope un pašreizējās ierobežojumu grupas
javascript
// Saglabājiet žetonu kešatmiņā; neveidojiet jaunu katram pieprasījumam.
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

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Tikai serveris–serveris. Nekad neizsauciet API no pārlūkprogrammas JavaScript: client_secret nonāktu pie apmeklētāja, un CORS jebkurā gadījumā bloķē visus avotus.

Kļūdas

StatussTipsKods
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Biežākās kļūdas

  • Žetona galapunktam ir atsevišķs IP ierobežojums. Viens žetons vienam procesam, atjaunots pirms derīguma beigām — nevis viens katram pieprasījumam.
  • client_secret tiek saglabāts tikai kā hash; ja to pazaudējat, izveidojiet jaunus piekļuves datus un atsauciet vecos.
  • Izveidojiet atsevišķus piekļuves datus ERP, veikalam un iekšējiem skriptiem, katram ar minimāliem scope. Viena atsaukšana neietekmē pārējos.
  • CORS nepieļauj nevienu pārlūkprogrammas avotu: API pēc dizaina ir paredzēta serveris–serveris.

Izstrādātāju jautājumi un atbildes

Kas notiek, ja client_secret ir nepareizs?

Saņemsiet 401 ar kodu invalid_client. Pārāk īss secret tiek noraidīts jau agrāk, validācijā: 422 validation_failed un param client_secret.

Vai ir atsevišķa testa vide?

Nē. Ir tikai viens ražošanas serveris. Testējiet ar proforma rēķiniem (document_kind proforma) un ar /invoices/preview-totals, kas neizlieto fiskālo numuru.

Vai var sašaurināt esošo piekļuves datu scope?

Jā, no paneļa. Jau izdotie žetoni saglabā izveides brīdī piešķirtos scope līdz derīguma beigām, vienas stundas laikā.