Een aankoopfactuur doorsturen

U beschikt over een leveranciersfactuur in PDF-, afbeeldings- of XML-formaat (UBL, Peppol BIS). Deze gids uploadt ze naar de importmodule, start de analyse en valideert ze daarna om het document en zijn boeking aan te maken. Het is exact het traject van het tabblad Documenten van de applicatie.

Vereisten: een token met de bevoegdheden read en write, en de public_token van het dossier.

De levenscyclus van een import volgt deze statussen:

Stap 1: het bestand uploaden#

De upload gebruikt multipart/form-data. Het veld heet files[] en aanvaardt tot 20 bestanden van elk 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"

Antwoord 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
    }
  ]
}

Een ZIP-archief levert een bovenliggende import op met de status expanded en één import per bestand in het archief, maximaal 50. Een bestand waarvan de extensie niet wordt aanvaard, doet de volledige upload mislukken met 422.

Stap 2: de analyse starten#

De analyse is synchroon: de aanroep antwoordt wanneer ze voltooid is. Voorzie aan clientzijde een time-out van minstens 150 seconden.

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
}

Als u process niet aanroept, analyseert een ingeplande verwerking elke minuut de imports in de wachtrij. U kunt dan gewoon de lijst bevragen:

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"

Een UBL-XML-bestand wordt rechtstreeks gelezen, zonder analyse door artificiële intelligentie. Het resultaat is onmiddellijk en exact.

Stap 3 (optioneel): de gegevens corrigeren#

Wanneer de status needs_review is, leest u warnings: elke waarschuwing draagt een code (counterparty_missing, date_missing, totals_missing, totals_mismatch...) en een message. Corrigeer de fiche zonder te valideren:

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"}}'

Stuur de volledige fiche extracted zoals u ze wenst: NovaFisko normaliseert ze opnieuw en herberekent de totalen.

Stap 4: valideren en boeken#

De validatie maakt het document aan, koppelt het aan een derde en boekt, met book: true, de boeking in het aankoopdagboek.

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
  }'

Antwoord 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}
}

Met book: false heeft entry de waarde null en blijft het document te boeken.

Variant: de boeking rechtstreeks invoeren#

Als u de gestructureerde gegevens al hebt en de pdf niet hoeft te bewaren, boekt u met één enkele aanroep. NovaFisko berekent de btw en de lijn van de derde.

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"}
    ]
  }'

Het bedrag van elke lijn is exclusief btw. Het type van het dagboek (purchase of sale) bepaalt de richting van de boeking.

Veelvoorkomende fouten#

Zie ook#

• Documentimport
• Validatie van de documenten
• Idempotentie
• Webhooks