Authentifizierung bei der 4invoices-API

client_id und client_secret gegen ein einstündiges Bearer-Token tauschen — nur Server zu Server.

client_id und client_secret gegen ein einstündiges Bearer-Token tauschen — nur Server zu Server.

← Zurück zur API-Dokumentation

Die erste Rechnung in 6 Schritten

  1. Erstellen Sie die Zugangskennung im Panel unter Rechnungsstellung → Einstellungen → API-Zugriff und kopieren Sie das client_secret sofort – es wird nur einmal angezeigt.
  2. Senden Sie POST /v1/auth/token mit grant_type client_credentials, client_id und client_secret.
  3. Sie erhalten access_token, token_type Bearer, expires_in 3600 und die Liste der gewährten Scopes zurück.
  4. Setzen Sie das Token bei allen weiteren Aufrufen in einen Header Authorization: Bearer <access_token>.
  5. Prüfen Sie mit GET /v1/me, was Sie tatsächlich erhalten haben: Mandant, Scopes und die aktuellen Rate-Kontingente.

Alle Endpunkte

MethodeEndpunktScopeIdempotency-KeyAnfragen / Minute
POST/auth/token
Zugangsdaten gegen ein Zugriffstoken tauschen
——120
GET/me
Mandant, Scopes und aktuelle Limits
invoices:read—120

Was die 4invoices-API ist

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"

# → Mandant, erteilte Scopes und aktuelle Rate-Kontingente
javascript
// Token zwischenspeichern; nicht pro Anfrage einen neuen erzeugen.
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
Nur Server-zu-Server. Rufen Sie die API nie aus Browser-JavaScript auf: das client_secret gelangt zum Besucher, und CORS blockiert ohnehin jeden Origin.

Fehler

StatusTypCode
401authentication_errorinvalid_client
401authentication_errortoken_expired
401authentication_errorinvalid_token
403permission_errorinsufficient_scope

Häufige Fehler

  • Der Token-Endpunkt hat ein eigenes Limit pro IP. Ein Token pro Prozess, vor Ablauf erneuert – nicht eines pro Anfrage.
  • Das client_secret wird nur als Hash gespeichert; geht es verloren, erstellen Sie eine neue Zugangskennung und widerrufen die alte.
  • Legen Sie getrennte Zugangskennungen für das ERP, den Shop und interne Skripte an, jeweils mit minimalen Scopes. Der Widerruf einer Kennung betrifft die anderen nicht.
  • CORS lässt keinen Browser-Origin zu: Die API ist bewusst als Server-zu-Server-Schnittstelle konzipiert.

Fragen und Antworten für Entwickler

Was passiert, wenn das client_secret falsch ist?

Sie erhalten 401 mit dem Code invalid_client. Ein zu kurzes Secret scheitert schon früher, bei der Validierung, mit 422 validation_failed und param client_secret.

Gibt es eine separate Testumgebung?

Nein. Es gibt einen einzigen Produktions-Host. Testen Sie mit Proformarechnungen (document_kind proforma) und mit /invoices/preview-totals, das keine fiskalische Nummer verbraucht.

Kann ich die Scopes einer bestehenden Zugangskennung einschränken?

Ja, im Panel. Bereits ausgestellte Tokens behalten die Scopes, mit denen sie erzeugt wurden, bis sie ablaufen – innerhalb einer Stunde.