Ανταλλάσσετε client_id και client_secret με ένα Bearer τόκεν μιας ώρας, μόνο μεταξύ διακομιστών.
← Επιστροφή στην τεκμηρίωση του API
Το πρώτο τιμολόγιο σε 6 βήματα
- Δημιουργήστε τα διαπιστευτήρια στο πάνελ, στο Τιμολόγηση → Ρυθμίσεις → Πρόσβαση API, και αντιγράψτε αμέσως το client_secret — εμφανίζεται μόνο μία φορά.
- Στείλτε POST /v1/auth/token με grant_type client_credentials, client_id και client_secret.
- Λαμβάνετε access_token, token_type Bearer, expires_in 3600 και τη λίστα των πεδία που παραχωρήθηκαν.
- Βάλτε το τόκεν σε κεφαλίδα Authorization: Bearer <access_token> σε κάθε άλλη κλήση.
- Ελέγξτε τι πήρατε στην πράξη με GET /v1/me: Τενάντ, πεδία και τους τρέχοντες κουβάδες ορίων.
Όλα τα Ένδποιντς
| Μέθοδος | Endpoint | Scope | Idempotency-Key | Αιτήματα / λεπτό |
|---|---|---|---|---|
| POST | /auth/token Ανταλλαγή διαπιστευτηρίων με διακριτικό πρόσβασης | — | — | 120 |
| GET | /me Τενάντ, πεδία και τρέχοντα όρια | invoices:read | — | 120 |
Τι είναι το API 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"
# → Τενάντ, τα χορηγημένα πεδία και τα τρέχοντα όρια ρυθμούjavascript
// Αποθηκεύστε το τόκεν στην κρυφή μνήμη· μην δημιουργείτε ένα ανά αίτημα.
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
Scopes
- invoices:read
- invoices:write
- clients:read
- clients:write
- efactura:read
- efactura:submit
Μόνο μεταξύ διακομιστών. Μην καλείτε ποτέ το API από JavaScript του browser: το client_secret θα έφτανε στον επισκέπτη και το CORS μπλοκάρει κάθε πηγή.
Σφάλματα
| Κατάσταση | Τύπος | Κωδικός |
|---|---|---|
| 401 | authentication_error | invalid_client |
| 401 | authentication_error | token_expired |
| 401 | authentication_error | invalid_token |
| 403 | permission_error | insufficient_scope |
Συχνά λάθη
- Το τόκεν Ένδποιντ έχει δικό του όριο ανά IP. Ένα τόκεν ανά διεργασία, που ανανεώνεται πριν τη λήξη — όχι ένα ανά αίτημα.
- Το client_secret αποθηκεύεται μόνο ως Χας· αν το χάσετε, δημιουργείτε νέα διαπιστευτήρια και ανακαλείτε τα παλιά.
- Εκδώστε ξεχωριστά διαπιστευτήρια για το ERP, το κατάστημα και τα εσωτερικά σενάρια, το καθένα με ελάχιστα πεδία. Η ανάκληση του ενός δεν επηρεάζει τα άλλα.
- Το CORS δεν επιτρέπει κανένα πρόγραμμα περιήγησης origin: το API είναι μεταξύ διακομιστών εκ σχεδιασμού.
Ερωτήσεις και απαντήσεις για προγραμματιστές
Τι συμβαίνει αν το client_secret είναι λάθος;
Λαμβάνετε 401 με code invalid_client. Ένα πολύ σύντομο μυστικό αποτυγχάνει νωρίτερα, στον έλεγχο εγκυρότητας, με 422 validation_failed και param client_secret.
Υπάρχει ξεχωριστό περιβάλλον δοκιμών;
Όχι. Υπάρχει ένας διακομιστής παραγωγής. Δοκιμάστε με προτιμολόγια (document_kind προτιμολόγιο) και με το /invoices/preview-totals, που δεν καταναλώνει φορολογικό αριθμό.
Μπορώ να περιορίσω τα πεδία υπαρχόντων διαπιστευτηρίων;
Ναι, από το πάνελ. Τα ήδη εκδοθέντα τόκεν διατηρούν τα πεδία με τα οποία δημιουργήθηκαν μέχρι να λήξουν, μέσα σε μία ώρα.