Billvox E-Rechnungs-API

Erstellt und finalisiert eine E-Rechnung. Alle EN 16931 Felder (BT-1 bis BT-160) werden unterstuetzt.

Request-Body (JSON)

Position-Objekt

Beispiel

curl -X POST https://app.billvox.de/api/v1/invoices \
  -H "Authorization: Bearer bvx_IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientName": "Musterfirma GmbH",
    "recipientStreet": "Musterstrasse 1",
    "recipientPostalCode": "10115",
    "recipientCity": "Berlin",
    "buyerReference": "991-01234-56",
    "projectReference": "PRJ-2026-042",
    "paymentReference": "RE-2026-0042",
    "positions": [
      {
        "description": "Beratungsleistung",
        "quantity": 10,
        "unitCode": "HUR",
        "unitPrice": 12000,
        "taxRate": 19,
        "taxCategory": "S",
        "orderLineReference": "1"
      }
    ]
  }'

Erfolgs-Antwort (201)

Datumsangaben (z. B. invoiceDate) kommen als Kalenderdatum ohne Zeitzone, Zeitpunkte (z. B. createdAt) als UTC im Format ISO 8601 mit Z.

{
  "invoiceId": "inv_abc123",
  "invoiceNumber": "2026-0001",
  "status": "Finalisiert",
  "format": "XRechnung",
  "sha256Hash": "a1b2c3d4...",
  "netAmountCents": 120000,
  "taxAmountCents": 22800,
  "grossAmountCents": 142800,
  "currency": "EUR",
  "downloadUrl": "https://app.billvox.de/api/v1/invoices/inv_abc123/xml",
  "validationWarnings": [],
  "createdAt": "2026-03-03T10:00:00Z",
  "finalizedAt": "2026-03-03T10:00:01Z"
}

Erstellt und finalisiert eine Gutschrift (Voll-Stornierung) zu einer finalisierten oder versendeten Rechnung. Alle Positionen werden automatisch negiert, die Gutschrift referenziert die Originalrechnung (BT-25) und die Originalrechnung wird als storniert markiert.

Request-Body (JSON)

Beispiel

curl -X POST https://app.billvox.de/api/v1/invoices/inv_abc123/credit-note \
  -H "Authorization: Bearer bvx_IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Falsche Leistungsabrechnung"
  }'

Erfolgs-Antwort (201)

Gleiches Format wie beim Erstellen einer Rechnung. Die Gutschrift erhaelt eine eigene Nummer aus Ihrem Nummernkreis; Betraege sind negativ.

Versendet eine finalisierte E-Rechnung per E-Mail. Die XML-Datei wird automatisch als Anhang mitgesendet.

Request-Body (JSON)

Beispiel

curl -X POST https://app.billvox.de/api/v1/invoices/inv_abc123/send \
  -H "Authorization: Bearer bvx_IHR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipientEmail": "rechnung@musterfirma.de"
  }'

Erfolgs-Antwort (200)

{
  "message": "Rechnung erfolgreich versendet.",
  "invoiceId": "inv_abc123",
  "sentTo": "rechnung@musterfirma.de"
}

Laed die generierte XML-Datei einer finalisierten E-Rechnung herunter.

Beispiel

curl -O -J https://app.billvox.de/api/v1/invoices/inv_abc123/xml \
  -H "Authorization: Bearer bvx_IHR_API_KEY"

Antwort

Die XML-Datei wird direkt als Download geliefert (Content-Type: application/xml).

Laed das PDF einer finalisierten E-Rechnung herunter. Bei Hybridformaten (ZUGFeRD / Factur-X) ist das PDF mit eingebettetem XML die eigentliche Rechnung.

Beispiel

curl -O -J https://app.billvox.de/api/v1/invoices/inv_abc123/pdf \
  -H "Authorization: Bearer bvx_IHR_API_KEY"

Prueft eine E-Rechnung (XML, ZUGFeRD-/Factur-X-PDF oder signierte .p7m-Datei) gegen XML-Schema, EN 16931, § 14 UStG und das Rechenwerk. Anfrage als multipart/form-data mit dem Feld file (max. 10 MB). Mit ?preview=true enthaelt die Antwort zusaetzlich eine HTML-Ansicht der Rechnung. Die Datei wird nicht gespeichert.

Beispiel

curl https://app.billvox.de/api/v1/validate \
  -H "Authorization: Bearer bvx_IHR_API_KEY" \
  -F "file=@rechnung.xml"

Antwort (200)

Gesamtstatus (gueltig, warnung, fehler oder unlesbar), erkanntes Format, die Einzelbefunde mit Regel-ID und die ausgelesenen Eckdaten der Rechnung.

Wandelt eine E-Rechnung in ein anderes Format um. target ist zugferd-pdf, xrechnung-ubl oder xrechnung-cii; die Antwort ist die erzeugte Datei.

Beispiel

curl -O -J "https://app.billvox.de/api/v1/convert?target=xrechnung-ubl" \
  -H "Authorization: Bearer bvx_IHR_API_KEY" \
  -F "file=@rechnung.pdf"