Ταυτοποίηση στο API 4invoices

Ανταλλάσσετε client_id και client_secret με ένα Bearer τόκεν μιας ώρας, μόνο μεταξύ διακομιστών.

Ανταλλάσσετε client_id και client_secret με ένα Bearer τόκεν μιας ώρας, μόνο μεταξύ διακομιστών.

← Επιστροφή στην τεκμηρίωση του API

Το πρώτο τιμολόγιο σε 6 βήματα

  1. Δημιουργήστε τα διαπιστευτήρια στο πάνελ, στο Τιμολόγηση → Ρυθμίσεις → Πρόσβαση API, και αντιγράψτε αμέσως το client_secret — εμφανίζεται μόνο μία φορά.
  2. Στείλτε POST /v1/auth/token με grant_type client_credentials, client_id και client_secret.
  3. Λαμβάνετε access_token, token_type Bearer, expires_in 3600 και τη λίστα των πεδία που παραχωρήθηκαν.
  4. Βάλτε το τόκεν σε κεφαλίδα Authorization: Bearer <access_token> σε κάθε άλλη κλήση.
  5. Ελέγξτε τι πήρατε στην πράξη με GET /v1/me: Τενάντ, πεδία και τους τρέχοντες κουβάδες ορίων.

Όλα τα Ένδποιντς

ΜέθοδοςEndpointScopeIdempotency-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 μπλοκάρει κάθε πηγή.

Σφάλματα

ΚατάστασηΤύποςΚωδικός
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_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, που δεν καταναλώνει φορολογικό αριθμό.

Μπορώ να περιορίσω τα πεδία υπαρχόντων διαπιστευτηρίων;

Ναι, από το πάνελ. Τα ήδη εκδοθέντα τόκεν διατηρούν τα πεδία με τα οποία δημιουργήθηκαν μέχρι να λήξουν, μέσα σε μία ώρα.