Todennus 4invoices-API:ssa

Vaihda client_id ja client_secret yhden tunnin Bearer-tokeniin — vain palvelin-palvelin-yhteydessä.

Vaihda client_id ja client_secret yhden tunnin Bearer-tokeniin — vain palvelin-palvelin-yhteydessä.

← Takaisin API-dokumentaatioon

Ensimmäinen lasku 6 vaiheessa

  1. Luo tunnus paneelissa kohdassa Laskutus → Asetukset → API-käyttöoikeudet ja kopioi client_secret heti — se näytetään kerran.
  2. Lähetä POST /v1/auth/token, jossa grant_type client_credentials, client_id ja client_secret.
  3. Saat takaisin access_tokenin, token_type Bearer, expires_in 3600 ja listan myönnetyistä scopeista.
  4. Laita token Authorization: Bearer <access_token> -otsikkoon kaikissa muissa kutsuissa.
  5. Tarkista, mitä sait, kutsulla GET /v1/me: tenant, scopet ja nykyiset rajat.

Kaikki päätepisteet

MetodiPäätepisteScopeIdempotency-KeyPyyntöjä / minuutti
POST/auth/token
Vaihda tunnistetiedot access-tokeniin
——120
GET/me
Tenant, scopet ja nykyiset rajat
invoices:read—120

Mitä 4invoices-API on

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, myönnetyt scopet ja nykyiset rajaryhmät
javascript
// Välimuistita token; älä luo uutta jokaiseen pyyntöön.
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

Scopet

  • invoices:read
  • invoices:write
  • clients:read
  • clients:write
  • efactura:read
  • efactura:submit
Vain palvelin-palvelin-yhteys. Älä koskaan kutsu API:a selaimen JavaScriptistä: client_secret päätyisi kävijälle, ja CORS estää joka tapauksessa kaikki alkuperät.

Virheet

TilaTyyppiKoodi
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Yleiset virheet

  • Token-päätepisteellä on oma IP-kohtainen rajansa. Yksi token prosessia kohden, uusittuna ennen vanhenemista — ei yksi pyyntöä kohden.
  • client_secret tallennetaan vain tiivisteenä; jos menetät sen, luo uusi tunnus ja peruuta vanha.
  • Luo erilliset tunnukset ERP:lle, verkkokaupalle ja sisäisille skripteille, kullakin vähimmät scopet. Yhden peruminen ei vaikuta muihin.
  • CORS ei salli yhtään selaimen alkuperää: API on palvelin-palvelin-yhteyttä varten suunniteltu.

Kehittäjien kysymykset ja vastaukset

Mitä tapahtuu, jos client_secret on väärä?

Saat 401-vastauksen koodilla invalid_client. Liian lyhyt secret hylätään jo aiemmin, validoinnissa: 422 validation_failed, param client_secret.

Onko erillinen testiympäristö?

Ei. Tuotantoisäntä on vain yksi. Testaa proformalaskuilla (document_kind proforma) ja kutsulla /invoices/preview-totals, joka ei kuluta verotuksellista numeroa.

Voinko kaventaa olemassa olevan tunnuksen scopeja?

Kyllä, paneelista. Jo myönnetyt tokenit säilyttävät luomishetken scopet vanhenemiseensa asti, yhden tunnin sisällä.