Autentimine 4invoices API-s

Vaheta client_id ja client_secret ühetunnise Bearer-tokeni vastu — ainult serverist serverisse.

Vaheta client_id ja client_secret ühetunnise Bearer-tokeni vastu — ainult serverist serverisse.

← Tagasi API dokumentatsiooni juurde

Esimene arve 6 sammuga

  1. Loo volitus paneelis jaotises Arveldus → Seaded → API juurdepääs ja kopeeri client_secret kohe — see kuvatakse üks kord.
  2. Saada POST /v1/auth/token koos grant_type client_credentials, client_id ja client_secret.
  3. Saad tagasi access_token, token_type Bearer, expires_in 3600 ja antud scope'ide loetelu.
  4. Pane token päisesse Authorization: Bearer <access_token> kõigil teistel päringutel.
  5. Kontrolli, mida tegelikult said, lõpp-punktiga GET /v1/me: tenant, scope'id ja praegused piirangud.

Kõik lõpp-punktid

MeetodLõpp-punktScopeIdempotency-KeyPäringuid / minut
POST/auth/token
Vaheta volitus juurdepääsutõendi vastu
——120
GET/me
Tenant, scope'id ja praegused piirangud
invoices:read—120

Mis on 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, antud scope'id ja praegused piirangugrupid
javascript
// Puhverda token; ära loo igale päringule uut.
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'id

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Ainult serverist serverisse. Ära kutsu API-d kunagi brauseri JavaScriptist: client_secret jõuaks külastajani ja CORS blokeerib igal juhul kõik päritolud.

Vead

StaatusTüüpKood
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Levinud vead

  • Tokeni lõpp-punktil on oma IP-põhine piirang. Üks token protsessi kohta, uuendatud enne aegumist — mitte üks päringu kohta.
  • client_secret salvestatakse ainult räsina; kui kaotad selle, loo uus volitus ja tühista vana.
  • Loo eraldi volitused ERP-le, poele ja sisemistele skriptidele, igaühele minimaalsete scope'idega. Ühe tühistamine ei mõjuta teisi.
  • CORS ei luba ühtegi brauseri päritolu: API on disainitud serverist serverisse.

Arendajate küsimused ja vastused

Mis juhtub, kui client_secret on vale?

Saad 401 koodiga invalid_client. Liiga lühike secret ebaõnnestub varem, valideerimisel: 422 validation_failed, param client_secret.

Kas on eraldi testkeskkond?

Ei. On ainult üks tootmishost. Testi proformaarvetega (document_kind proforma) ja lõpp-punktiga /invoices/preview-totals, mis ei kuluta fiskaalnumbrit.

Kas olemasoleva volituse scope'e saab kitsendada?

Jah, paneelist. Juba välja antud tokenid säilitavad loomisel antud scope'id kuni aegumiseni, ühe tunni jooksul.