REST API

API-Dokumentation

Neben der Erstellung über die Website kann dieser Dienst auch direkt per API angesprochen werden. Sie können entweder eine PDF-Rechnung zur automatischen Auslesung senden oder bereits vorbereitete Rechnungsdaten zusammen mit der Original-PDF übergeben. Für jeden Zugriff ist ein gültiger API-Key erforderlich, den angemeldete Benutzer im Bereich Konto anlegen können. Als Ergebnis erhalten Sie Download-URLs für XML und PDF.

Basis

https://einvoice.niedziela.rocks

Content-Type

`multipart/form-data` oder `application/json`

Authentifizierung

`Authorization: Bearer <api-key>` oder `x-api-key`

Überblick

Variante 1

PDF hochladen

Die Rechnung wird automatisch ausgelesen und daraus direkt die E-Rechnung erstellt.

Variante 2

JSON + PDF senden

Sie übergeben die Rechnungsdaten selbst und nutzen die API für Validierung, XML und PDF.

Ergebnis

Temporäre Download-URLs

Die API gibt eine URL für XML und eine URL für die fertige PDF zurück.

POST/api/convert

PDF senden und automatisch auslesen

Verwende diesen Modus, wenn du nur die Original-PDF hast. Die API liest die Rechnung mit OpenAI aus, validiert die Angaben und erstellt anschließend XML und Hybrid-PDF.

Request

Feld	Typ	Pflicht	Beschreibung
Authorization	Header	ja	Bearer-Token mit einem gültigen API-Key.
file	PDF-Datei	ja	Die Originalrechnung als PDF. Maximale Größe: 10 MB.

Beispiel-Requests

Sprache

curl -X POST https://einvoice.niedziela.rocks/api/convert \
  -H "Authorization: Bearer <api-key>" \
  -F "file=@rechnung.pdf"

Hinweise

Content-Type: multipart/form-data
Für diesen Modus muss der Server mit OPENAI_API_KEY konfiguriert sein.
Ein API-Key ist verpflichtend. Ohne gültigen Key wird die Anfrage mit 401 abgelehnt.
API-Aufrufe stehen nur in den API-Tarifen zur Verfügung und zählen auf das monatliche Gesamtkontingent aus Web und API.
Wenn Pflichtangaben fehlen, liefert die API statt Dateien eine Fehlermeldung mit Validierungshinweisen.

POST/api/convert

Rechnungsdaten und PDF direkt senden

Verwende diesen Modus, wenn die Rechnungsdaten bereits bei dir vorliegen. Die API übernimmt Validierung, XML-Erzeugung und das Einbetten in die Original-PDF.

Request

Feld	Typ	Pflicht	Beschreibung
Authorization	Header	ja	Bearer-Token mit einem gültigen API-Key.
invoice	Objekt	ja	Rechnungsdaten im erwarteten Format.
originalPdfBase64	String	ja	Die Originalrechnung als Base64-kodierte PDF.
filename	String	nein	Optionaler Dateiname für deinen eigenen Request-Kontext.

Beispiel-Requests

Sprache

curl -X POST https://einvoice.niedziela.rocks/api/convert \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "invoice": {
    "invoiceNumber": "RE-2026-0042",
    "invoiceDate": "2026-03-11",
    "currency": "EUR",
    "seller": {
      "name": "Muster GmbH",
      "address": "Musterstraße 1",
      "postalCode": "10115",
      "city": "Berlin",
      "countryCode": "DE",
      "vatId": "DE123456789",
      "taxNumber": "",
      "email": "",
      "phone": "",
      "iban": "DE02100100109307118603",
      "bic": "PBNKDEFF",
      "reference": "",
      "customerNumber": ""
    },
    "buyer": {
      "name": "Kunde GmbH",
      "address": "Beispielweg 5",
      "postalCode": "20095",
      "city": "Hamburg",
      "countryCode": "DE",
      "vatId": "",
      "taxNumber": "",
      "email": "",
      "phone": "",
      "iban": "",
      "bic": "",
      "reference": "",
      "customerNumber": ""
    },
    "lineItems": [
      {
        "lineId": "1",
        "name": "Beratung",
        "description": "Monatliche Beratung",
        "quantity": 1,
        "unitCode": "C62",
        "unitPriceNet": 1000,
        "taxRate": 19,
        "taxCategoryCode": "S",
        "lineTotalNet": 1000
      }
    ],
    "totals": {
      "sumNet": 1000,
      "sumTax": 190,
      "sumGross": 1190,
      "prepaidAmount": 0,
      "payableAmount": 1190
    },
    "taxBreakdown": [
      {
        "taxableAmount": 1000,
        "taxAmount": 190,
        "taxRate": 19,
        "taxCategoryCode": "S"
      }
    ],
    "paymentTerms": "Zahlbar sofort",
    "paymentMeansCode": "58",
    "notes": "",
    "orderReference": "",
    "buyerReference": "",
    "projectReference": "",
    "filenameOriginal": "rechnung.pdf",
    "extractionMeta": {
      "fieldConfidence": [],
      "uncertainFields": [],
      "warnings": [],
      "source": "fallback"
    }
  },
  "originalPdfBase64": "JVBERi0xLjcK..."
}'

JSON-Beispiel

Payload

{
  "invoice": {
    "invoiceNumber": "RE-2026-0042",
    "invoiceDate": "2026-03-11",
    "currency": "EUR",
    "seller": {
      "name": "Muster GmbH",
      "address": "Musterstraße 1",
      "postalCode": "10115",
      "city": "Berlin",
      "countryCode": "DE",
      "vatId": "DE123456789",
      "taxNumber": "",
      "email": "",
      "phone": "",
      "iban": "DE02100100109307118603",
      "bic": "PBNKDEFF",
      "reference": "",
      "customerNumber": ""
    },
    "buyer": {
      "name": "Kunde GmbH",
      "address": "Beispielweg 5",
      "postalCode": "20095",
      "city": "Hamburg",
      "countryCode": "DE",
      "vatId": "",
      "taxNumber": "",
      "email": "",
      "phone": "",
      "iban": "",
      "bic": "",
      "reference": "",
      "customerNumber": ""
    },
    "lineItems": [
      {
        "lineId": "1",
        "name": "Beratung",
        "description": "Monatliche Beratung",
        "quantity": 1,
        "unitCode": "C62",
        "unitPriceNet": 1000,
        "taxRate": 19,
        "taxCategoryCode": "S",
        "lineTotalNet": 1000
      }
    ],
    "totals": {
      "sumNet": 1000,
      "sumTax": 190,
      "sumGross": 1190,
      "prepaidAmount": 0,
      "payableAmount": 1190
    },
    "taxBreakdown": [
      {
        "taxableAmount": 1000,
        "taxAmount": 190,
        "taxRate": 19,
        "taxCategoryCode": "S"
      }
    ],
    "paymentTerms": "Zahlbar sofort",
    "paymentMeansCode": "58",
    "notes": "",
    "orderReference": "",
    "buyerReference": "",
    "projectReference": "",
    "filenameOriginal": "rechnung.pdf",
    "extractionMeta": {
      "fieldConfidence": [],
      "uncertainFields": [],
      "warnings": [],
      "source": "fallback"
    }
  },
  "originalPdfBase64": "JVBERi0xLjcK..."
}

GET/api/artifacts/:id

Erzeugte Dateien herunterladen

Mit den IDs aus der erfolgreichen Response kannst du die erzeugten Dateien direkt herunterladen.

Response

Code	Bedeutung
200	Datei wird direkt als Download ausgeliefert.
404	Die Datei ist nicht mehr verfügbar oder die URL ist abgelaufen.

Responses

200 Erfolgreich

Response

{
  "message": "E-Rechnung erfolgreich erstellt.",
  "invoiceNumber": "RE-2026-0042",
  "urls": {
    "xml": "https://einvoice.niedziela.rocks/api/artifacts/abc123",
    "pdf": "https://einvoice.niedziela.rocks/api/artifacts/def456"
  },
  "expiresAt": {
    "xml": "2026-03-11T12:30:00.000Z",
    "pdf": "2026-03-11T12:30:00.000Z"
  }
}

400 Fehlende Parameter

Response

{
  "message": "Für den OpenAI-Modus wird das Feld 'file' mit einer PDF-Datei benötigt.",
  "missingParameters": ["file"]
}

401 API-Key fehlt oder ist ungültig

Response

{
  "message": "Für den Zugriff auf diese API wird ein gültiger API-Key benötigt. Verwende 'Authorization: Bearer <key>' oder den Header 'x-api-key'."
}

400 Validierungsfehler

Response

{
  "message": "Die E-Rechnung konnte nicht erstellt werden.",
  "validationIssues": [
    {
      "path": "invoiceNumber",
      "message": "Rechnungsnummer fehlt.",
      "severity": "error"
    }
  ]
}

403 Tarif oder Kontingent blockiert die Anfrage

Response

{
  "message": "Ihr aktueller Tarif erlaubt keine API-Nutzung. Bitte wechseln Sie zu einem API-Tarif.",
  "billing": {
    "plan": "Kostenlos",
    "used": 2,
    "limit": 5,
    "remaining": 3
  }
}

415 Falscher Content-Type

Response

{
  "message": "Nicht unterstützter Content-Type. Verwende multipart/form-data für PDF + OpenAI oder application/json für Rechnungsdaten + PDF."
}

503 OpenAI nicht verfügbar

Response

{
  "message": "Die automatische Extraktion über OpenAI ist derzeit nicht verfügbar."
}