Vaheta client_id ja client_secret ühetunnise Bearer-tokeni vastu — ainult serverist serverisse.
← Tagasi API dokumentatsiooni juurde
Esimene arve 6 sammuga
- Loo volitus paneelis jaotises Arveldus → Seaded → API juurdepääs ja kopeeri client_secret kohe — see kuvatakse üks kord.
- Saada POST /v1/auth/token koos grant_type client_credentials, client_id ja client_secret.
- Saad tagasi access_token, token_type Bearer, expires_in 3600 ja antud scope'ide loetelu.
- Pane token päisesse Authorization: Bearer <access_token> kõigil teistel päringutel.
- Kontrolli, mida tegelikult said, lõpp-punktiga GET /v1/me: tenant, scope'id ja praegused piirangud.
Kõik lõpp-punktid
| Meetod | Lõpp-punkt | Scope | Idempotency-Key | Pä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 piirangugrupidjavascript
// 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
| Staatus | Tüüp | Kood |
|---|---|---|
| 401 | authentication_error | invalid_client |
| 401 | authentication_error | token_expired |
| 401 | authentication_error | invalid_token |
| 403 | permission_error | insufficient_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.