Déposer, rechercher et récupérer des flux

Déposer

POST /v1/flows

Le dépôt utilise multipart/form-data. Le mécanisme d'appel est identique pour une facture CII, UBL ou Factur-X :

Taille maximale du fichier

Le Flow Service refuse les fichiers dépassant les limites suivantes :

• CustomerInvoice, SupplierInvoice, StateInvoice : 100 MB maximum ;
• CustomerInvoiceLC, SupplierInvoiceLC, StateLC : 5 MB maximum.

Contrôlez la taille du fichier avant l'appel à POST /v1/flows.

➡️ Comprendre les limites de taille des flux

Partie multipart	Type	Obligatoire	Contenu
flowInfo	application/json	Oui	Objet JSON décrivant le document déposé
file	application/xml ou application/pdf	Oui	Fichier de facture transmis

Choisir la syntaxe de la facture

La valeur de flowSyntax doit correspondre exactement au document placé dans la partie file.

Document envoyé	flowInfo.flowSyntax	Fichier	Type MIME de file
Facture CII	CII	XML CII	application/xml
Facture UBL	UBL	XML UBL	application/xml
Facture Factur-X	Factur-X	PDF/A-3 contenant le XML Factur-X	application/pdf

Une facture Factur-X doit être envoyée comme le PDF/A-3 complet, et non comme le seul XML embarqué. La casse et le trait d'union de la valeur Factur-X doivent être conservés.

Attributs de flowInfo

Le contrat AFNOR distingue les deux attributs obligatoires des enrichissements facultatifs.

Attribut	Présence	Rôle
name	Obligatoire	Nom du fichier transmis, extension comprise ; il doit correspondre à la partie file
flowSyntax	Obligatoire	Syntaxe du document : CII, UBL, Factur-X, CDAR ou FRR selon le flux
trackingId	Facultatif	Identifiant externe choisi par l'ERP ou le SI pour corréler et rechercher le dépôt
processingRule	Facultatif	Règle de traitement attendue ; si elle est omise, la plateforme peut la déterminer à partir du document
flowProfile	Facultatif	Profil du document
sha256	Facultatif	Empreinte SHA-256 du fichier, sous la forme de 64 caractères hexadécimaux minuscules, pour en contrôler l'intégrité

Valeurs de flowProfile

Les valeurs possibles sont :

Valeur
Basic
CIUS
Extended-CTC-FR

Le profil déclaré doit être cohérent avec le profil réellement contenu dans le document.

Valeurs de processingRule

Les valeurs possibles sont :

Valeur
B2B
B2BInt
B2C
B2G
B2GInt
OutOfScope
B2GOutOfScope
ArchiveOnly
NotApplicable

Ne fournissez processingRule que lorsque la règle est connue. Le Swagger de l'environnement reste la référence du contrat technique exposé.

Les attributs flowId, flowType, flowDirection, submittedAt, updatedAt, processingRuleSource et acknowledgement sont produits par la plateforme. Ils ne doivent pas être ajoutés au flowInfo envoyé.

Exemples de flowInfo pour une facture

Le même appel multipart est utilisé dans les trois cas. Seuls le JSON et le fichier associé changent.

CII

{
  "name": "facture-F202600123-cii.xml",
  "flowSyntax": "CII",
  "trackingId": "ERP-F202600123"
}

UBL

{
  "name": "facture-F202600123-ubl.xml",
  "flowSyntax": "UBL",
  "trackingId": "ERP-F202600123"
}

Factur-X

{
  "name": "facture-F202600123-factur-x.pdf",
  "flowSyntax": "Factur-X",
  "trackingId": "ERP-F202600123"
}

:::warning Valeur du profil

N'envoyez flowProfile que lorsque vous connaissez le profil réellement porté par le document.

:::

Appel multipart commun

curl -X POST "https://<flow-api-host>/v1/flows" \
  -H "Authorization: Bearer <access_token>" \
  -H "Organization-Id: <organization-id>" \
  -F 'flowInfo={"name":"facture-F202600123-cii.xml","flowSyntax":"CII","trackingId":"ERP-F202600123"};type=application/json' \
  -F 'file=@facture-F202600123-cii.xml;type=application/xml'

Pour UBL, remplacez le nom du fichier et utilisez flowSyntax: "UBL". Pour Factur-X, utilisez flowSyntax: "Factur-X", un fichier PDF/A-3 et type=application/pdf.

Le retour 202 Accepted confirme la prise en compte technique du dépôt, et non la livraison métier complète.

Rechercher

POST /v1/flows/search

La requête respecte le modèle AFNOR :

• where est obligatoire et contient au moins un critère ;
• limit est facultatif, vaut 25 par défaut et ne peut pas dépasser 100 dans le contrat AFNOR 1.3 ;
• les critères différents placés dans where sont combinés par un ET logique ;
• plusieurs valeurs d'un même critère de type liste sont combinées par un OU logique.

Paramètres de recherche

Emplacement	Paramètre	Type	Utilisation
Racine	limit	Entier	Nombre maximal de résultats retournés
where	updatedAfter	Date-heure	Flux dont updatedAt est strictement postérieur à cette valeur
where	updatedBefore	Date-heure	Borne supérieure de la fenêtre de recherche
where	processingRule	Liste	Une ou plusieurs règles : B2B, B2C, B2G, etc.
where	flowType	Liste	Une ou plusieurs natures métier, par exemple CustomerInvoice ou SupplierInvoice
where	flowDirection	Liste	Sens du flux : In ou Out
where	trackingId	Chaîne	Identifiant externe fourni lors du dépôt
where	ackStatus	Chaîne	État technique : Pending, Ok ou Error

Le contrat AFNOR 1.3 ne prévoit pas de filtre direct sur flowSyntax, le nom de fichier, le numéro de facture, le SIREN du vendeur ou celui de l'acheteur. Pour ces besoins, recherchez d'abord les flux candidats, puis exploitez leurs métadonnées et, si nécessaire, le document récupéré.

Rechercher des factures reçues

{
  "limit": 100,
  "where": {
    "updatedAfter": "2026-09-20T08:00:00Z",
    "updatedBefore": "2026-09-20T08:05:00Z",
    "flowDirection": ["In"],
    "flowType": ["SupplierInvoice"]
  }
}

Cet exemple cible les factures fournisseurs entrantes hors auto-facturation. Le couple flowDirection / flowType dépend du scénario :

Scénario	flowDirection	flowType
Facture de vente émise, hors auto-facturation	Out	CustomerInvoice
Facture fournisseur reçue, hors auto-facturation	In	SupplierInvoice
Facture d'auto-facturation émise par l'acheteur	Out	SupplierInvoice
Facture d'auto-facturation reçue par le fournisseur	In	CustomerInvoice

Pour un polling qui ne doit perdre aucun flux encore en cours de qualification, il peut être préférable de filtrer d'abord sur la fenêtre temporelle et la direction, puis d'examiner flowType, flowSyntax et l'acquittement dans les résultats.

Rechercher un dépôt par corrélation

{
  "where": {
    "trackingId": "ERP-F202600123"
  }
}

Rechercher les flux en erreur technique

{
  "limit": 100,
  "where": {
    "updatedAfter": "2026-09-20T00:00:00Z",
    "flowDirection": ["Out"],
    "ackStatus": "Error"
  }
}

Les champs disponibles et les valeurs admises peuvent évoluer avec la version du standard implémentée. Le Swagger/OpenAPI publié pour l'environnement utilisé reste le contrat technique applicable.

Polling différentiel

La plateforme n'envoie actuellement aucun webhook lors de la réception d'une facture, d'un statut CDAR ou de l'évolution technique d'un flux. Le client API doit appeler régulièrement cette route.

À chaque cycle :

1. recherchez les flux modifiés depuis le dernier point de reprise ;
2. parcourez tous les résultats selon la pagination exposée ;
3. traitez les flux de manière idempotente à partir de flowId et de leur date de mise à jour ;
4. récupérez les documents utiles avec la route GET ;
5. enregistrez le nouveau point de reprise uniquement lorsque toute la fenêtre a été traitée.

Les factures entrantes et les statuts CDAR reçus sont des flux distincts. Le polling doit donc prendre en compte les directions et les types de flux attendus, sans se limiter au suivi des flowId déposés par le client.

➡️ Algorithme complet de polling Flow Service

Récupérer

GET /v1/flows/{flowId}

Le paramètre docType permet selon le type de flux de récupérer les métadonnées, l'original ou certaines représentations dérivées.

Cas des statuts CDAR

Un statut CDAR utilise la même route de dépôt. Le flowInfo contient au minimum le nom du fichier et flowSyntax: "CDAR". Le rattachement à la facture est porté par le XML, et non par un flowId de facture transmis dans flowInfo.

➡️ Publier un statut CDAR
➡️ Exemples fonctionnels des neuf statuts CDAR