Dépôt de fichiers

Un ERP qui ne sait qu’écrire des fichiers peut remettre les factures par un seul dossier. Le service surveille le dossier et traite chaque fichier comme une soumission : un fichier JSON comme POST /invoices, un fichier XML comme POST /invoices/xml. Les résultats reviennent sous forme de fichiers dans le même dossier.

ConfigurationCopier le lien vers cette section

Le dossier est défini à l’installation du service. Le service le vérifie une fois par seconde, et ne surveille rien quand aucun dossier n’est défini. Un fichier passe par la même entrée qu’un appel d’API : il est donc refusé pour les mêmes raisons.

Nommer le fichierCopier le lien vers cette section

• Une référence de facture compte jusqu’à 100 caractères et ne contient ni / ni \.
• Un fichier de plus de 5 Mo est refusé.
• Un nom qui commence par un point, contient .. ou ne correspond à aucun des deux modèles est ignoré.
• La clé Idempotency-Key correspond aux 32 premiers caractères du SHA-256 du fichier. Déposer à nouveau un fichier identique est un rejeu, et non une seconde facture.

Ce qui revientCopier le lien vers cette section

drop/
  DE-4711.json            you write this
  status/
    DE-4711-1.json        one file per status event
    DE-4712-error.json    the answer to a refused file
  done/
    DE-4711.json          an accepted file moves here
  failed/
    DE-4712.json          a refused file moves here

Un fichier accepté est déplacé dans done/. Les événements de la facture sont écrits dans status/, un fichier par événement, nommé INVOICE-REF-<sequence>.json. Chacun est un élément de la réponse de GET /invoices/{id}/events. Ils contiennent l’empreinte de la facture et aucun contenu de facture.

{
  "occurred_at": "2026-10-02T17:17:55.857Z",
  "sequence": 1,
  "environment": "sandbox",
  "invoice_ref": "CAPTURE-JSON-1790961440",
  "document_sha256": "3b41395db498666777b74f9f5b9fae82871720304bc25bbb590e25b7b75ea1d4",
  "event_id": "evt_200c0def79ed702df81d702f",
  "country_route": "DE-XRECHNUNG",
  "invoice_number": "CAPTURE-JSON-1790961440",
  "status": "validated"
}

Les événements qui existent au moment où le fichier est accepté sont écrits aussitôt. Chaque événement ultérieur est écrit à son arrivée, jusqu’à ce que la facture atteigne un état final (accepted, delivered, rejected, validation_failed, dead_letter ou cancelled) ou que 30 jours se soient écoulés.

Un fichier refusé est déplacé dans failed/, et status/INVOICE-REF-error.json contient la réponse qu’aurait donnée l’API. Pour un fichier qui n’est pas une facture, il s’agit du 422 ci-dessous. Corrigez les données et déposez à nouveau le fichier sous le même nom.

{
  "type": "https://eurinvoice.com/problems/validation-failed",
  "title": "The invoice did not pass the checks",
  "errors": [
    {
      "code": "EI-XML-TYPE",
      "fix_hint": "Send the invoice itself, in the format agreed for the route.",
      "who_fixes": "erp",
      "source": "XML-safety",
      "message": "The file is not an invoice in a format this route accepts. Please send the invoice in the agreed format."
    }
  ],
  "status": 422
}

Ce qui manqueCopier le lien vers cette section

• Le SFTP et le stockage objet.
• Un moyen de lire depuis le dossier l’identifiant inv_ d’une facture acceptée. Les fichiers de statut contiennent invoice_ref et invoice_number.