API für Entwickler

Mit der API von NumNum erstellen Sie programmatisch Dokumente in Ihrer eigenen NumNum-Umgebung. Einmal erstellt, können Sie diese Dokumente per E-Mail, Peppol oder Post versenden, genau wie manuell erstellte Dokumente.

Die API ist für Server-zu-Server-Integrationen gedacht, zum Beispiel:

E-Commerce: automatisch eine Rechnung nach einem Online-Verkauf erstellen
ERP / CRM: Rechnungen aus Ihrem bestehenden System erstellen
Self-Billing (Gutschriftverfahren): periodische Abrechnungen (Einkaufsbelege) für Ihre Lieferanten, z. B. Genossenschaften oder Produzenten
Eigene Workflows: die Rechnungserstellung in Ihre eigene Anwendung integrieren

Was kann die API?

Die API ist schreibgeschützt im Sinne von „nur erstellen" (write-only): Sie erstellen damit Dokumente. Es gibt drei Endpunkte:

Was	Endpunkt	Dokumentation
Verkaufsrechnungen erstellen	`POST /api/v1/webhooks/create-invoice`	Rechnungen erstellen
Ausgestellten Einkaufsbeleg (Self-Billing) erstellen	`POST /api/v1/webhooks/create-purchase-borderelle`	Self-Billing / Einkaufsbeleg
Gutschrift zu einem Einkaufsbeleg erstellen	`POST /api/v1/webhooks/create-purchase-borderelle-creditnote`	Self-Billing / Einkaufsbeleg

Was ist (noch) nicht möglich

Um die Erwartungen klar zu setzen:

❌ Dokumente lesen, ändern oder löschen ist mit Ihrem persönlichen API-Token nicht möglich. Die API dient nur zum Erstellen von Dokumenten.
❌ Eigene Dokumentnummern übermitteln ist nicht möglich: NumNum nummeriert automatisch gemäß Ihren Unternehmenseinstellungen (gesetzlich vorgeschriebene lückenlose Reihenfolge).
❌ Idempotenz ist nicht eingebaut: dieselbe Nutzlast zweimal zu senden erstellt zwei Dokumente. Verfolgen Sie selbst, was Sie bereits übermittelt haben (z. B. über das Feld reference oder die zurückgegebenen IDs).

ℹ️ Der Versand über Peppol oder E-Mail ist nicht Teil dieser API; er erfolgt anschließend in der App oder über Ihren üblichen Versandablauf.

Zugang

Sie generieren Ihren API-Token selbst auf der Seite Meine APIs in Ihren Unternehmenseinstellungen (siehe Authentifizierung). Sehen Sie diese Seite nicht? Kontaktieren Sie den Support (help@numnum.be).

Authentifizierung

Jede API-Anfrage benötigt zwei Header: Ihren persönlichen API-Token und das Unternehmen, für das Sie arbeiten.

1. Persönlicher API-Token

Melden Sie sich bei NumNum an
Gehen Sie zu Einstellungen → Verbindungen → Meine APIs (https://app.numnum.be/company/connection/myapi)
Klicken Sie auf API-Token generieren

Einige wichtige Eigenschaften:

Der Token ist eine Zeichenfolge von exakt 64 Zeichen (Ziffern und Buchstaben). Kopieren Sie stets den vollständigen Wert, wie er auf der Seite angezeigt wird; er bleibt dort sichtbar, solange Sie keinen neuen generieren.
Der Token gehört zu Ihrem Benutzer, nicht zu einem einzelnen Unternehmen. Derselbe Token funktioniert für alle Unternehmen, auf die Sie Zugriff haben; das Unternehmen wählen Sie pro Anfrage über den Header X-Company-Id.
Es gibt keinen separaten „Widerrufen"-Button: erneutes Klicken auf API-Token generieren erstellt einen neuen Token und macht den vorherigen sofort ungültig.
Behandeln Sie den Token wie ein Passwort: speichern Sie ihn in einer Umgebungsvariablen / einem Secrets-Manager, teilen Sie ihn niemals per E-Mail oder Chat und committen Sie ihn nicht in git.

2. Company ID

Ihre X-Company-Id bestimmt, in welchem Unternehmen das Dokument erstellt wird. Sie finden sie:

neben Ihrem Token auf der Seite Meine APIs, oder
in der NumNum-URL (z. B. https://app.numnum.be/company/12345/... → Company ID = 12345).

Basis-URL & Header

https://app.numnum.be/api/v1

Header	Erforderlich	Beispiel
`Authorization`	Ja	`Bearer <ihr-api-token>`
`X-Company-Id`	Ja	`12345`
`Content-Type`	Ja	`application/json`
`Accept`	Empfohlen	`application/json`

Achten Sie auf das Leerzeichen zwischen Bearer und dem Token.

Fehlerbehandlung

Behandeln Sie nur HTTP 201 als Erfolg. Jeder andere Statuscode bedeutet, dass das Dokument nicht erstellt wurde; stellen Sie die Anfrage in eine Warteschlange und versuchen Sie es später erneut (mit exponentiellem Back-off bei 429 und 5xx).

Status	Bedeutung	Antwort-Body
`201 Created`	Dokument(e) erstellt	`{ "invoices": [1234] }` (je nach Endpunkt)
`400 Bad Request`	Header fehlen	`{ "error": "Required headers are missing." }`
`400 Bad Request`	Falsches `Authorization`-Format	`{ "error": "Authorization header format is invalid." }`
`400 Bad Request`	Validierungsfehler in der Nutzlast	`{ "error": "invalid_body", "errors": { "0.client.email": ["..."] } }`
`401 Unauthorized`	Ungültiger API-Token	`{ "error": "Invalid API token." }`
`403 Forbidden`	Ihr Benutzer hat keinen Zugriff auf dieses Unternehmen	`{ "error": "Access to this company is forbidden." }`
`404 Not Found`	Unbekannte Company ID	`{ "error": "Invalid company ID." }`
`429 Too Many Requests`	Ratenlimit oder Monatslimit erreicht	`{ "error": "Monthly API document limit reached." }`
`500`	Unerwarteter Serverfehler	Kontaktieren Sie help@numnum.be

Bei Validierungsfehlern (400 invalid_body) verweist der Schlüssel auf die Position im Array und das Feld, z. B. 0.client.email = erstes Dokument, Feld client.email.

Limits & Kontingente

Batch: eine Anfrage enthält ein Array von Dokumenten (max. 50 pro Anfrage). Die Verarbeitung ist atomar: schlägt ein Dokument fehl, wird kein Dokument erstellt.
Ratenlimit (pro Unternehmen): 30 Anfragen pro Minute und 2000 pro Tag.
Monatslimit: es gilt eine maximale Anzahl von Dokumenten pro Monat (Richtwert ± 200/Monat). Eine Überschreitung gibt 429 zurück.
Halten Sie parallele Anfragen begrenzt (± 5 gleichzeitig), um den Server nicht zu überlasten.

Veralteter Endpunkt (Legacy)

Ein älterer Endpunkt, POST /webhooks/create-invoice (ohne /api/v1), existiert noch für bestehende Integrationen. Er verwendet denselben Token, gibt aber eine einfache Liste ([10232, 10233]) und andere Fehlercodes (406, 401) zurück. Dieser Endpunkt ist veraltet; verwenden Sie für neue Integrationen immer POST /api/v1/webhooks/create-invoice.

Nächste Schritte

Fragen? Kontaktieren Sie help@numnum.be.