Self-Billing (Einkaufsbeleg) über die API

Diese Endpunkte erstellen ausgestellte Einkaufsbelege, im belgischen MwSt.-Jargon Self-Billing-Rechnungen (Gutschriftverfahren). Das ist ein Dokument, das Ihr Unternehmen im Namen eines Lieferanten erstellt (z. B. eine Milchgeldabrechnung, die eine Molkerei für einen Milchbauern erstellt).

Typische Nutzer: Produzenten und Genossenschaften, die periodisch Abrechnungen für ihre Lieferanten erstellen, oder externe Systeme, die Abrechnungen generieren und an NumNum übermitteln möchten, dabei aber ihr eigenes PDF-Layout behalten wollen.

ℹ️ Authentifizierung (persönlicher API-Token + X-Company-Id), Limits und allgemeine Fehlercodes finden Sie im API-Überblick für Entwickler. Header und Kundenabgleich sind identisch mit der Rechnungs-API.

Endpunkte

POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle
POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle-creditnote

Request-Body: Einkaufsbeleg

Ein JSON-Array von Einkaufsbelegen (atomar verarbeitet). Die Struktur ähnelt der Rechnungs-API, mit einigen Unterschieden.

Zeilen (lines)

"lines": [
  { "description": "Milchlieferung 1.–15. Mai (Liter)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 }
]

Gleiche Felder wie eine Rechnungszeile: description, unit_price, amount, vat_percentage. amount kann dezimal sein (z. B. Liter/kg). Die Summen werden serverseitig berechnet.

IBAN und BIC des Lieferanten

Die IBAN des Lieferanten ist nötig, um den Beleg über Peppol zu versenden: ein Einkaufsbeleg ist ein Self-Billing-Dokument, und die Peppol-UBL muss das Konto des Lieferanten enthalten (Regel BR-61). Ohne IBAN wird das Dokument zwar erstellt, NumNum verweigert aber den Peppol-Versand. Übermitteln Sie daher iban (und am besten auch bic) im client-Objekt.

Beide Schreibweisen sind gültig und liefern dasselbe Ergebnis:

"client": { "iban_country_code": "BE", "iban": "82103021737768", "bic": "GKCCBEBB" }

"client": { "iban": "BE82 1030 2173 7768", "bic": "GKCCBEBB" }

• Leerzeichen, Punkte und Bindestriche sind erlaubt; sie werden entfernt.
• Senden Sie sowohl iban_country_code als auch eine iban, die selbst schon mit einem Ländercode beginnt, müssen beide übereinstimmen. Bei einem Konflikt (z. B. NL bei BE82…) erhalten Sie 400 invalid_body.
• Ein ungültiges IBAN- oder BIC-Format ergibt ebenfalls 400 invalid_body; der gesamte Batch wird dann abgelehnt.
• Existiert der Lieferant bereits und hat er schon eine IBAN, bleibt diese unverändert: bestehende Bankdaten werden von der API nie überschrieben. Leere Felder werden hingegen ergänzt.
• Vergessen? Sie können die IBAN nachträglich in der Lieferantenkarte unter Finanzdaten ergänzen (siehe Self-Billing: Wie funktioniert es?).

Eigenes PDF anhängen (attachment_pdf)

Möchten Sie Ihr eigenes PDF-Layout behalten? Senden Sie ein Base64-codiertes PDF. Es wird als Anlage am Dokument gespeichert und beim Peppol-Versand mitgeschickt. NumNum generiert zusätzlich weiterhin ein Standard-PDF aus den Dokumentdaten.

• Max. Größe ± 15 MB (Base64). Bleiben Sie deutlich darunter.
• Fehlt attachment_pdf_filename, wird <beleg-nr>.pdf verwendet.
• Senden Sie nur echte PDFs; der Content-Type wird auf application/pdf gesetzt.

// Node.js
const fs = require('fs')
const pdfBase64 = fs.readFileSync('./milchgeld-mai-2026.pdf').toString('base64')

Request-Body: Gutschrift

Nahezu identisch mit einem Einkaufsbeleg, mit diesen Unterschieden:

Alle anderen Felder verhalten sich identisch. Verwenden Sie negative oder korrigierende Beträge je nach Korrektur.

Beispiel: Milchgeldabrechnung

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle \
  -H "Authorization: Bearer <ihr-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '[
    {
      "language": "de",
      "purchase_borderelle_date": "2026-05-20",
      "expire_days": 30,
      "reference": "Milchgeld Mai 2026",
      "payment_info": "no",
      "client": {
        "company_type": "company",
        "type": "onbekend",
        "email": "bauer@example.be",
        "first_name": "Jan",
        "last_name": "De Boer",
        "vat_country_code": "BE",
        "vat_id": "0123456789",
        "address": "Boerderijstraat 1",
        "address_zip": "9800",
        "address_city": "Deinze",
        "address_country": "BE",
        "iban_country_code": "BE",
        "iban": "82103021737768",
        "bic": "GKCCBEBB"
      },
      "lines": [
        { "description": "Milchlieferung 1.–15. Mai (Liter)", "unit_price": 0.45, "amount": 12500, "vat_percentage": 6 },
        { "description": "Milchlieferung 16.–31. Mai (Liter)", "unit_price": 0.46, "amount": 13200, "vat_percentage": 6 }
      ]
    }
  ]'

Beispiel: Gutschrift zu einem Einkaufsbeleg

curl -X POST https://app.numnum.be/api/v1/webhooks/create-purchase-borderelle-creditnote \
  -H "Authorization: Bearer <ihr-api-token>" \
  -H "X-Company-Id: 12345" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "language": "de",
      "purchase_borderelle_creditnote_date": "2026-05-21",
      "purchase_borderelle_uuid": "9c1a2b3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
      "reference": "Korrektur Milchgeld Mai",
      "client": { "company_type": "company", "type": "onbekend", "email": "bauer@example.be", "first_name": "Jan", "last_name": "De Boer", "vat_country_code": "BE", "vat_id": "0123456789", "address": "Boerderijstraat 1", "address_zip": "9800", "address_city": "Deinze", "address_country": "BE", "iban_country_code": "BE", "iban": "82103021737768", "bic": "GKCCBEBB" },
      "lines": [
        { "description": "Korrektur Qualitätsprämie", "unit_price": -50.00, "amount": 1, "vat_percentage": 6 }
      ]
    }
  ]'

Antwort

HTTP 201: Erstellt

Einkaufsbeleg:

{ "purchase_borderelles": [1234, 1235] }

Gutschrift:

{ "purchase_borderelle_creditnotes": [987] }

Das Array enthält die internen Datenbank-IDs in derselben Reihenfolge wie die Eingabe.

Fehler

Siehe die Fehlertabelle im API-Überblick. Validierungsfehler folgen demselben invalid_body-Format wie die Rechnungs-API, indexiert nach Position (0.client.email, 1.lines.0.unit_price, …). Eine purchase_borderelle_uuid eines anderen Unternehmens gibt 404 zurück.

Unterschied zur Rechnungs-API

Hinweise

• Nummerierung: die Belegnummer wird automatisch generiert (typischerweise mit AB-Präfix). Sie können keine eigene Nummer übermitteln.
• Nicht idempotent: dieselbe Nutzlast zweimal zu senden erstellt zwei Dokumente.
• Peppol erfordert eine IBAN: ohne client.iban wird der Beleg erstellt, aber nicht über Peppol versendet. Siehe Bankdaten.
• Empfangene Einkaufsbelege (von einem Lieferanten) kommen über Peppol herein; das ist kein Anwendungsfall dieser API.