Eine Einkaufsrechnung übermitteln

Sie haben eine Lieferantenrechnung im Format PDF, Bild oder XML (UBL, Peppol BIS). Dieser Leitfaden lädt sie in den Importer hoch, stößt die Analyse an und validiert sie anschließend, um den Beleg und seine Buchung zu erzeugen. Das ist genau der Ablauf des Reiters Belege in der Anwendung.

Voraussetzungen: ein Token mit den Berechtigungen read und write sowie das public_token des Mandats.

Der Lebenszyklus eines Imports durchläuft folgende Status:

Schritt 1: die Datei hochladen#

Der Upload verwendet multipart/form-data. Das Feld heißt files[] und akzeptiert bis zu 20 Dateien mit jeweils 25 MB.

curl -X POST https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/document-imports \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Accept: application/json" \
  -H "X-Client-Mutation-Id: 9a7d1a0c-2b1f-4d0e-bb0d-6d5a3d7f2c41" \
  -F "files[]=@/chemin/vers/F-2026-0918.pdf" \
  -F "batch_id=3f5c2b9e-8f0a-4f6a-9a0e-1b7b2a6f4c10"

Antwort 201:

{
  "batch_id": "3f5c2b9e-8f0a-4f6a-9a0e-1b7b2a6f4c10",
  "imports": [
    {
      "id": 5120,
      "company_id": 318,
      "batch_id": "3f5c2b9e-8f0a-4f6a-9a0e-1b7b2a6f4c10",
      "original_name": "F-2026-0918.pdf",
      "mime": "application/pdf",
      "size": 84213,
      "kind": "pdf",
      "status": "queued",
      "progress": 0,
      "extracted": null,
      "warnings": null,
      "file_url": "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/document-imports/5120/file?expires=1791190000&preview=1&signature=...",
      "has_preview": false,
      "version": 1
    }
  ]
}

Ein ZIP-Archiv erzeugt einen übergeordneten Import mit dem Status expanded und einen Import pro enthaltener Datei, höchstens 50. Eine Datei mit nicht akzeptierter Erweiterung lässt den gesamten Upload mit 422 scheitern.

Schritt 2: die Analyse starten#

Die Analyse ist synchron: Der Aufruf antwortet, sobald sie abgeschlossen ist. Sehen Sie auf Client-Seite ein Timeout von mindestens 150 Sekunden vor.

curl -X POST https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/document-imports/5120/process \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Accept: application/json" \
  --max-time 180

{
  "id": 5120,
  "original_name": "F-2026-0918.pdf",
  "kind": "pdf",
  "status": "ready",
  "progress": 100,
  "step": "done",
  "engine": "api",
  "suggested_direction": "purchase",
  "suggested_third_party_id": 41,
  "suggested_third_party": {"id": 41, "code": "BRASSCOL", "name": "Brasserie des Collines SA", "type": "supplier", "vat_number": "BE0999900134"},
  "extracted": {
    "document_type": "invoice",
    "direction": "purchase",
    "counterparty": {
      "name": "Brasserie des Collines SA",
      "vat_number": "BE0999900134",
      "iban": "BE71096123456769",
      "bic": "GKCCBEBB"
    },
    "number": "F-2026-0918",
    "date": "2026-10-02",
    "due_date": "2026-11-01",
    "structured_communication": "+++091/8202/60018+++",
    "currency": "EUR",
    "lines": [
      {"description": "Fûts 20 L blonde", "quantity": 10, "unit_price": 125, "vat_rate": 21, "amount_net": 1250, "amount_vat": 262.5, "amount_gross": 1512.5}
    ],
    "totals": {"net": 1250, "vat": 262.5, "gross": 1512.5, "vat_breakdown": [{"rate": 21, "base": 1250, "amount": 262.5}]},
    "payment": {"iban": "BE71096123456769", "bic": "GKCCBEBB", "paid": false},
    "nature": null,
    "confidence": 0.94,
    "language": "fr"
  },
  "warnings": [],
  "error": null,
  "duplicate_of_import_id": null,
  "duplicate_of_document_id": null,
  "imported_document_id": null,
  "file_url": "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/document-imports/5120/file?expires=...&signature=...",
  "has_preview": false
}

Wenn Sie process nicht aufrufen, analysiert ein geplanter Job die Importe in der Warteschlange jede Minute. Sie können dann einfach die Liste abfragen:

curl "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/document-imports?batch_id=3f5c2b9e-8f0a-4f6a-9a0e-1b7b2a6f4c10&status=ready,needs_review,error,duplicate" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

Eine UBL-XML-Datei wird direkt gelesen, ohne Analyse durch künstliche Intelligenz. Das Ergebnis liegt sofort vor und ist exakt.

Schritt 3 (optional): die Daten korrigieren#

Lautet der Status needs_review, lesen Sie warnings: Jede Warnung trägt einen code (counterparty_missing, date_missing, totals_missing, totals_mismatch...) und eine message. Korrigieren Sie das Datenblatt, ohne zu validieren:

curl -X PATCH https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/document-imports/5120 \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"extracted": {"number": "F-2026-0918", "date": "2026-10-02", "due_date": "2026-11-01"}}'

Senden Sie das vollständige Datenblatt extracted so, wie Sie es wünschen: NovaFisko normalisiert es erneut und berechnet die Summen neu.

Schritt 4: validieren und buchen#

Die Validierung erzeugt den Beleg, ordnet ihn einem Geschäftspartner zu und bucht mit book: true die Buchung in das Einkaufsjournal.

curl -X POST https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/document-imports/5120/validate \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Client-Mutation-Id: 1c7f5e2a-90c4-4a55-8f0b-5f6e6a3d9b72" \
  -d '{
    "direction": "purchase",
    "third_party_id": 41,
    "lines": [{"account_id": 118, "vat_code_id": 12}],
    "book": true,
    "push_to_novadesko": false
  }'

Antwort 201:

{
  "import": {"id": 5120, "status": "validated", "imported_document_id": 7741, "progress": 100},
  "document": {
    "id": 7741,
    "type": "purchases",
    "direction": "purchase",
    "number": "F-2026-0918",
    "document_date": "2026-10-02T00:00:00.000000Z",
    "status": "booked",
    "third_party": {"id": 41, "name": "Brasserie des Collines SA", "type": "supplier", "code": "BRASSCOL"},
    "lines": [
      {
        "id": 19022,
        "description": "Fûts 20 L blonde",
        "actual_account": {"id": 118, "number": "604000", "label": "Achats de marchandises"},
        "vat_code": {"id": 12, "code": "A21", "rate": "21.00"}
      }
    ]
  },
  "entry": {
    "id": 1842,
    "number": 212,
    "entry_date": "2026-10-02T00:00:00.000000Z",
    "reference": "F-2026-0918",
    "status": "posted",
    "journal": {"id": 3, "code": "ACH"},
    "lines": [
      {"id": 5521, "debit": "1250.00", "credit": "0.00", "account": {"id": 118, "number": "604000", "label": "Achats de marchandises"}},
      {"id": 5522, "debit": "262.50", "credit": "0.00", "account": {"id": 77, "number": "411000", "label": "TVA à récupérer"}},
      {"id": 5523, "debit": "0.00", "credit": "1512.50", "account": {"id": 90, "number": "440000", "label": "Fournisseurs"}}
    ]
  },
  "novadesko": {"status": "skipped", "document_id": null, "token": null, "locked": false, "error": null, "message": null}
}

Mit book: false hat entry den Wert null, und der Beleg bleibt zu buchen.

Variante: die Buchung direkt erfassen#

Wenn Sie die strukturierten Daten bereits besitzen und das PDF nicht aufbewahren müssen, erfassen Sie die Buchung mit einem einzigen Aufruf. NovaFisko berechnet die MwSt. und die Zeile des Geschäftspartners.

curl -X POST https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries/invoice \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Client-Mutation-Id: 0b0f7a52-63f4-4f1f-8a43-0d4f6b0b8a10" \
  -d '{
    "journal_id": 3,
    "third_party_id": 41,
    "entry_date": "2026-10-02",
    "due_date": "2026-11-01",
    "reference": "F-2026-0918",
    "lines": [
      {"account": "604000", "amount": "1250.00", "vat_code": "A21", "label": "Fûts 20 L blonde"}
    ]
  }'

Der Betrag jeder Zeile versteht sich ohne MwSt. Der Typ des Journals (purchase oder sale) bestimmt die Richtung der Buchung.

Häufige Fehler#

Siehe auch#

• Belegimporter
• Validierung der Belege
• Idempotenz
• Webhooks