Rechnungen über die API erstellen

Dieser Endpunkt erstellt Verkaufsrechnungen in NumNum. Einmal erstellt, können Sie diese per E-Mail, Peppol oder Post versenden.

ℹ️ Authentifizierung (persönlicher API-Token + X-Company-Id), Limits und allgemeine Fehlercodes finden Sie im API-Überblick für Entwickler. Lesen Sie diesen zuerst.

Endpunkt

POST https://app.numnum.be/api/v1/webhooks/create-invoice

Header:

Authorization: Bearer <ihr-api-token>
X-Company-Id: <ihre-company-id>
Content-Type: application/json
Accept: application/json

Request-Body

Der Body ist ein JSON-Array von Rechnungsobjekten. Sie können eine oder mehrere Rechnungen gleichzeitig erstellen (max. 50, atomar verarbeitet).

Rechnungsfelder

payment_info

vat_shifted

MwSt.-Verlagerungsregime:

⚠️ Bei jedem Wert außer 0 müssen alle Rechnungszeilen vat_percentage: 0 haben. Der Kunde benötigt in der Regel eine gültige USt-IdNr. (z. B. für innergemeinschaftliche Lieferungen).

Kundenobjekt

ℹ️ Das Feld type ist nur für Unternehmen (company / bedrijf) erforderlich, nicht für Privatpersonen.

Rechnungszeilen (invoice_lines)

Die Summen werden automatisch berechnet:

• netto = unit_price × amount
• mwst = netto × (vat_percentage / 100)
• gesamt = netto + mwst

Beispiel: Rechnung für ein Unternehmen

curl -X POST https://app.numnum.be/api/v1/webhooks/create-invoice \
  -H "Authorization: Bearer <ihr-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "de",
      "invoice_date": "2026-02-15",
      "expire_days": 30,
      "reference": "ORDER-2026-001",
      "intro": "Vielen Dank für Ihre Bestellung!",
      "remarks": "Bitte zahlen Sie innerhalb von 30 Tagen.",
      "payment_info": "yes",
      "vat_shifted": 0,
      "client": {
        "company_type": "company",
        "type": "bv",
        "email": "info@kunde.be",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "first_name": "Jan",
        "last_name": "Janssen",
        "address": "Kerkstraat 1",
        "address_zip": "1000",
        "address_city": "Brüssel",
        "address_country": "BE",
        "telephone": "+32 2 123 45 67"
      },
      "invoice_lines": [
        { "description": "Website-Entwicklung", "unit_price": 1500.00, "amount": 1, "vat_percentage": 21 },
        { "description": "Hosting (12 Monate)", "unit_price": 15.00, "amount": 12, "vat_percentage": 21 }
      ]
    }
  ]'

Beispiel: Privatkunde

Für eine Privatperson sind type und vat_id nicht erforderlich:

[
  {
    "language": "de",
    "invoice_date": "2026-02-20",
    "expire_days": 14,
    "client": {
      "company_type": "individual",
      "email": "john.doe@gmail.com",
      "first_name": "John",
      "last_name": "Doe",
      "address": "Dorpstraat 45",
      "address_zip": "9000",
      "address_city": "Gent",
      "address_country": "BE"
    },
    "invoice_lines": [
      { "description": "Grafikdesign Logo", "unit_price": 350.00, "amount": 1, "vat_percentage": 21 }
    ]
  }
]

Beispiel: MwSt. verlagert (innergemeinschaftlich)

Bei Verlagerung verwenden Sie vat_shifted und vat_percentage: 0:

[
  {
    "language": "en",
    "invoice_date": "2026-02-25",
    "expire_days": 30,
    "vat_shifted": 4,
    "remarks": "Reverse charge - VAT to be accounted for by the customer",
    "client": {
      "company_type": "company",
      "type": "gmbh",
      "email": "info@deutschefirma.de",
      "vat_country_code": "DE",
      "vat_id": "123456789",
      "first_name": "Hans",
      "last_name": "Müller",
      "address": "Hauptstraße 10",
      "address_zip": "10115",
      "address_city": "Berlin",
      "address_country": "DE"
    },
    "invoice_lines": [
      { "description": "Consulting services", "unit_price": 2500.00, "amount": 1, "vat_percentage": 0 }
    ]
  }
]

Antwort

HTTP 201: Erstellt

{
  "invoices": [1234, 5678]
}

invoices ist eine Liste interner Datenbank-IDs in derselben Reihenfolge wie die Eingabe; dies sind keine Rechnungsnummern. Rechnungsnummern werden automatisch gemäß Ihren Unternehmenseinstellungen generiert.

Fehler

Siehe die Fehlertabelle im API-Überblick. Ein Validierungsfehler sieht so aus:

{
  "error": "invalid_body",
  "errors": {
    "0.language": ["The language must be one of: nl, fr, en, de."],
    "0.client.email": ["The client email must be a valid email address."],
    "0.invoice_lines.0.unit_price": ["The unit price must be a number."]
  }
}

Kundenabgleich (Duplikate vermeiden)

Für jede Rechnung prüft NumNum, ob der Kunde bereits existiert, andernfalls wird er angelegt:

• Mit USt-IdNr. (vat_country_code + vat_id): Abgleich auf Ihr Unternehmen + die normalisierte USt-IdNr. Die Formatierung spielt keine Rolle: 0123456789 und 0123.456.789 treffen denselben Kunden.
• Ohne USt-IdNr.: Rückfall auf die Kombination Unternehmen + vat_id + email. Verwenden Sie eine einheitliche E-Mail-Adresse, um Duplikate zu vermeiden.

⚠️ Existiert der Kunde bereits (USt-Abgleich)? Dann wird er nicht mit den neuen Daten (Name, Adresse, E-Mail) überschrieben. Ändern Sie Kundendaten in NumNum selbst.

Hinweise

• Beträge: verwenden Sie einen Punkt als Dezimaltrennzeichen (1234.56), kein Komma und kein Tausendertrennzeichen.
• Datumsangaben: Format JJJJ-MM-TT mit führenden Nullen (2026-02-05).
• MwSt.: numerischer Wert ohne %-Zeichen (21, nicht "21%" oder 0.21).
• Atomar: schlägt eine Rechnung im Batch fehl, wird keine erstellt.
• Automatische Nummerierung: Sie können keine eigene Rechnungsnummer übermitteln.

Entitätstypen

Gültige Werte für client.type (nur bei Unternehmen erforderlich), u. a.: bv, nv, vzw, bvba, cvba, comm.v, comm.va, vof, eenmanszaak, sa, sarl, sas, srl, gmbh, ag, limited-ltd, limited-llc, natuurlijk-persoon, onbekend. Nicht sicher? Verwenden Sie onbekend.

Veralteter Endpunkt

Der alte Endpunkt POST /webhooks/create-invoice (ohne /api/v1) funktioniert noch für bestehende Integrationen, ist aber veraltet: er gibt eine einfache Liste ([10232, 10233]) zurück und verwendet andere Fehlercodes (406/401). Migrieren Sie zu POST /api/v1/webhooks/create-invoice.