Pousser une facture d'achat

Vous disposez d'une facture fournisseur au format PDF, image ou XML (UBL, Peppol BIS). Ce guide la dépose dans l'importateur, déclenche l'analyse, puis la valide pour créer le document et son écriture. C'est exactement le parcours de l'onglet Documents de l'application.

Prérequis : un jeton avec les capacités read et write, et le public_token du dossier.

Le cycle de vie d'un import suit ces statuts :

Étape 1 : déposer le fichier#

Le dépôt utilise multipart/form-data. Le champ s'appelle files[] et accepte jusqu'à 20 fichiers de 25 Mo chacun.

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"

Réponse 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
    }
  ]
}

Une archive ZIP produit un import parent au statut expanded et un import par fichier contenu, 50 au maximum. Un fichier dont l'extension n'est pas acceptée fait échouer tout le dépôt avec 422.

Étape 2 : lancer l'analyse#

L'analyse est synchrone : l'appel répond quand elle est terminée. Prévoyez un délai d'attente d'au moins 150 secondes côté client.

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
}

Si vous n'appelez pas process, un traitement planifié analyse les imports en file chaque minute. Vous pouvez alors simplement interroger la liste :

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"

Un fichier XML UBL est lu directement, sans analyse par intelligence artificielle. Le résultat est immédiat et exact.

Étape 3 (facultative) : corriger les données#

Quand le statut est needs_review, lisez warnings : chaque avertissement porte un code (counterparty_missing, date_missing, totals_missing, totals_mismatch...) et un message. Corrigez la fiche sans valider :

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

Envoyez la fiche extracted complète telle que vous la souhaitez : NovaFisko la renormalise et recalcule les totaux.

Étape 4 : valider et comptabiliser#

La validation crée le document, le rattache à un tiers et, avec book: true, passe l'écriture dans le journal des achats.

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

Réponse 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}
}

Avec book: false, entry vaut null et le document reste à comptabiliser.

Variante : saisir directement l'écriture#

Si vous possédez déjà les données structurées et n'avez pas besoin de conserver le PDF, passez l'écriture en un seul appel. NovaFisko calcule la TVA et la ligne du tiers.

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

Le montant de chaque ligne est hors TVA. Le type du journal (purchase ou sale) détermine le sens de l'écriture.

Erreurs fréquentes#

Voir aussi#

• Importateur de documents
• Validation des documents
• Idempotence
• Webhooks