5 API – Flux

5 API – Flux

5.1 Respect du Swagger Flow Service

5.1 Respect du Swagger Flow Service L’API publiée par le Fournisseur API doit respecter le SWAGGER décrit dans l’Annexe A selon les règles décrites en 4.1. Les routes obligatoires sont listées dans le Tableau 1 ci-dessous : Tableau 1 — Routes obligatoires de l’API Flow Service Route Description Chapitre 5.2POST/flows Déposer des flux POST/search Rechercher des flux 5.3 GET/flows/{flowId} Récupérer un flux 5.4 GET/healthcheck Vérifier si le service API est opérationnel.

5.2 Déposer un flux (Route POST / Flows)

5.2 Déposer un flux (Route POST / Flows)

5.2.1 Flux acceptés

5.2.1 Flux acceptés Route Description POST/flows Déposer des flux La route POST /flows, de l’API publiée par le Fournisseur APIdoit permettre de déposer : • Une facture constituée dans un format du socle (Syntaxe CII, UBL, Factur-X) • Un cycle de vie sur une facture (Syntaxe CDAR) • Une transmission de données de E-Reporting (Syntaxe FRR pour FRench Reporting) • Un cycle de vie sur une transmission de données de E-reporting (Syntaxe CDAR) Le body de la route POST/ Flows est un multi-part composéd’un objetpayload JSON ‘flowInfo’ et d’un fichier binaire.

5.2.2 ‘trackingId’ [Champ optionnel]

5.2.2 ‘trackingId’ [Champ optionnel] Le Fournisseur API doit accepter un ‘trackingId’et le stocker. Ce paramètre doit être optionnel pour le Client API. Il permet à ce dernier de retrouver plus facilement le flux avec son propre identifiant interne. Le Fournisseur API ne doitpascontrôler l’unicitéde cet identifiantquiestunidentifiantinterne auClient API.

5.2.3 ‘sha256’ [Champ optionnel]

5.2.3 ‘sha256’ [Champ optionnel] Casd’usage n°1 : Lorsque la propriété ‘sha256’ est alimentée par le Client API, il est recommandé au Fournisseur API de contrôler cette valeur avec l’empreinte numériquedu fichier déposé calculée en utilisant l’algorithme sha256. Si la comparaison est différente, le fournisseur API retourne un code 4XXCasd’usage n°2: Siladonnée n’estpasalimentée par le clientAPIlors de dépôt API Flux , le fournisseur API peut calculer ce sha256 et retourne ce résultat dans le message de réponse. Dans ce cas de figure, c’estle Client Api qui peut vérifier que son flux a été correctement transmis lors de l’appel en analysant le sha256 retourné. PA

5.2.4 ‘processingRule’ et ‘processingRuleSource’

5.2.4 ‘processingRule’ et ‘processingRuleSource’ La propriété ‘processingRule’ permet de qualifier le type de traitement attendu. Pour un flux facture, cela fait référence à la règle de gestion ‘BR-FR-20’de la norme XPZ12-012. Lorsquele paramètre ‘processingRule’ est contradictoire avec ce qui est mentionné dans la facture (BT-21 avec le code ‘BAR’) le Fournisseur API doit considérer le flux comme irrecevable. Le Fournisseur API doit alimenter la propriété ‘processingRuleSource’ avec la valeur ‘input’ si la règle de traitement était un paramètre d’entrée fourni par le Client API et avec la valeur ‘Computed’sila règle de traitement a été calculée. Il est recommandé au Fournisseur API d’appliquer les règlesde gestion selonle Tableau 2 ci-dessous. Tableau 2 — Traitement attendu pour la propriété ‘processingRule’ Code Traitement attendu processingRule’ non alimenté ou vide Il est recommandé au Fournisseur API : 1] Pour un flux facture, de rechercher le code indiqué en BT-22 dans le flux facture en recherchantun code ‘BAR’dans le BT-21. 2] Pour un flux facture, de considérer que la facture relève du B2G si le code note (BT-21) est égal à ADN et si le contenu (BT-22) est égal à B2G. 3] Si le Fournisseur API propose cette fonctionnalité, ce dernier peut qualifier automatiquement le traitement attendu en alimentant la propriété ‘processingRule’avec la règle calculée. La propriété ‘processingRuleSource’doit alors avoir la valeur ‘Computed’. Il est rappelé que si le Fournisseur API propose cette fonctionnalité, les règles doivent être clairement exprimées auprès du Client API. 3] A défaut de considérer le flux comme irrecevable. Liste de valeur Codifié pour le champ ProcessingRule : processingRule B2B Description et Règle de gestion Le Fournisseur API doit traiter le flux comme un flux qui relève du e-invoicing sauf incohérence avec la note de facture (BG-1 : BAR/B2B) ci présente B2G Le Fournisseur API doit de traiter le flux comme un flux qui relève du e-invoicing des ventes B2G sauf incohérence avec la note de facture (BG-1 : ADN/B2G) si présente B2GOutOfScope Le Fournisseur API doit de traiter le flux comme un flux qui relève du e-invoicing des ventes B2G « hors réforme » sauf incohérence avec la note de facture (BG-1 : ADN/B2G et BAR/OUTOFSCOPE) si présente Exemple : Frais de justice. Bint2G Le Fournisseur API doit de traiter le flux comme un flux qui venant d’une société non française àtransmettre àl’administration française sauf incohérence avec la note de facture (BG-1 : ADN/B2G et BAR/B2BINT) si présente B2Bint Le Fournisseur API doit traiter le flux comme un flux qui relève du e-reporting des ventes ou des acquisitions B2B internationales sauf incohérence avec la note de facture (BG-1 : BAR/B2BINT) si présente. B2C Le Fournisseur API doit traiter le flux comme un flux qui relève du e-reporting des ventes B2C sauf incohérence avec la note de facture (BG-1 : BAR/B2C) si présente. processingRule OutOfScope Description et Règle de gestion Le Fournisseur API doit traiter le flux comme un flux « hors réforme » sauf incohérence avec la note de facture (BG-1 : BAR/OUTOFSCOPE) si présente. ArchiveOnly Le Fournisseur API doit traiter le flux comme un flux qui ne doit pas faire l’objet d’un traitement e-invoicing (pas de flux 1, pas de transmission au destinataire) sauf incohérence avec la note de facture (BG-1 : BAR/ARCHIVEONLY) si présente. Exemple : Il peut s’agir d’un AVOIR interne créé pour annuler une facture REJETÉE ou REFUSÉE oud’une reprise d’historique; NotApplicable Il est recommandé auClient API et auFournisseur API d’utiliser ce code pour qualifier les flux qui ne nécessitent pas de préciser le traitement à appliquer : Les flux de Cycle de vie (syntaxe CDAR) ou les flux de E-Reporting (syntaxe FRR)

5.2.5 Retour de la route

5.2.5 Retour de la route Le Fournisseur API doit retourner en synchrone un objet payload json, selon la structure suivante avec en particulier une propriété ‘flowId’ permettant d’identifier de manière unique le flux dans son système d’information pour un Client API donné, Construction du message de retour : Champs Description du champ flowId Identifiant unique de dépôt : peut être construit selon différentes méthodes, un UUID ou une construction propre à chaque système mettant en oeuvre l’API Flux submittedAt Date et heure de dépôt du fichier dans l’API Flux trackingId Identifier externe, qui permet de rechercher les données name Nom du fichier déposé processingRul e Nature / Typologie de l’objet : [B2B, B2BInt,B2C, B2G, BInt2G, OutOfScope, B2GOutOfScope, ArchiveOnly, NotApplicable] flowSyntax Format du fichier déposé [ CII, UBL, Factur-X, CDAR, FRR ] flowProfile Profil du fichier Facture déposé [ Basic, CIUS, Extended-CTC-FR ] ** Caractéristique non renseigné pour un flux Cycle et Vie ou E-reporting sha256 Il est recommandé au Fournisseur API de calculer l’empreinte numérique du fichierdéposé en utilisantl’algorithme sha256 et de la retourner dansce message de retour.

5.2.6 Traitement attendu : la qualification du flux avec un ‘FlowType’

5.2.6 Traitement attendu : la qualification du flux avec un ‘FlowType’ [la suite du dépôt d’un Flux par la Route POST/Flows,leFournisseurAPI doitqualifierle flux en luiassociant un FlowType pour permettre une segmentation des Flux selon 3 familles : • Invoice : CustomerInvoice, SupplierInvoice, StateInvoice • LifeCycle : CustomerInvoiceLC, StateCustomerInvoiceLC, StateSupplierInvoiceLC , SupplierInvoiceLC • TransactionReport et PaymentReport : AggregatedCustomerTransactionReport, UnitaryCustomerTransactionReport, AggregatedCustomerPaymentReport, UnitaryCustomerPaymentReport, UnitarySupplierTransactionReport, MultiFlowReport PA Voir le détail des flowType dans le tableau 3 si dessous. D’autre part : • Lorsde la transmissiond’unFlux1au Concentrateur de Données du PPF, il est recommandé au Fournisseur API de créer un flux avec un flowType « StateInvoice » • Lorsde la transmission d’un FluxCDAR auConcentrateur de Données du PPF, il est recommandé au Fournisseur API de créer un flux avec un flowType « StateCustomerInvoiceLC » et « StateSupplierInvoiceLC ». • Il est recommandé au Fournisseur API de créer des flux reflétant les flux envoyés au Concentrateur de Données du PPF. • Si un flux 10 contient plusieurs types de flux de E-Reporting (10.1, 10.2, 10.3, 10.4), le Fournisseur API doit qualifier un flowType « MultiFlowReport ». Tableau 3 — Qualification des flux avec un FlowType FlowType Règle de gestion CustomerInvoice Un flux « facture de vente ». Doit être utilisé pour qualifier une facture sortante non auto- facturée ou pour une facture entrante en auto-facturation SupplierInvoice Un flux « facture d’achat ». Doit être utilisé pour qualifier une facture entrante non auto- facturée ou pour une facture sortante en auto-facturation StateInvoice Peut être utilisé pour qualifier un Flux 1 envoyé par la PAe au Concentrateur de Données du PPF CustomerInvoiceLC Doit être utilisé pour qualifier un flux cycle de vie (CDAR) d’une facture de type ‘CustomerInvoice’ StateCustomerInvoiceLC Peut être utilisé pour qualifier un flux cycle de vie (CDAR) envoyé au Concentrateur de Données du PPF d’une facture de type ‘CustomerInvoice’ StateSupplierInvoiceLC Peut être utilisé pour qualifier un flux cycle de vie (CDAR) envoyé au Concentrateur de Données du PPF d’une facture de type ‘SupplierInvoice’ (Facture sortante auto-facturée) SupplierInvoiceLC Doit être utilisé pour qualifier un flux cycle de vie (CDAR) d’une facture de type ‘SupplierInvoice’ AggregatedCustomerTransactionRe port Doit être utilisé pour qualifier un flux de E-Reporting de transaction contenant des ventes B2Cagrégées (FRR 10.3) UnitaryCustomerTransactionReport Doit être utilisé pour qualifier un flux de E-Reporting de transaction contenant des ventes B2B à l’international (FRR 10.1) Si le Fournisseur API accepte un flux de transaction B2C déclaré unitairement, le Fournisseur API doit utiliser ce flowType pour qualifier le flux AggregatedCustomerPaymentRepor t Doit être utilisé pour un flux de E-Reporting d’encaissements contenant des encaissements liés à des ventes B2C (FRR 10.4) UnitaryCustomerPaymentReport Doit être utilisé pour un flux de E-Reporting d’encaissements contenant des encaissements liés à des ventes B2B internationales unitaires (FRR 10.2) Si le Fournisseur API accepte un flux de paiement B2C déclaré unitairement, le Fournisseur API doit utiliser ce flowType pour qualifier le flux UnitarySupplierTransactionReport Doit être utilisé pour qualifier un flux de E-Reporting de transaction contenant des achats B2B à l’international (FRR flux 10.1) MultiFlowReport Doit être utilisé pour qualifier un flux de E-Reporting lorsque le flux contient au moins 2 types de flux différents (FRR flux 10) PA

5.3 Rechercher un flux (Route POST / Search)

5.3 Rechercher un flux (Route POST / Search) Ce service permet de récupérer un ensemble de flux correspondant aux critères de recherche fournis : Critères de recherche Critères Type Description updatedAfter Date-Time Date début de période de recherche : 15/01/2026 updatedBefore Date-Time Date fin de période de recherche : 30/01/2026 processingRule Liste de valeurs codifiées Nature / Typologie de l’objet Facture • [ B2B, B2BInt, B2C, OutOfScope, etc< ArchiveOnly, NotApplicable ] flowProfile Liste de valeurs/ codifiées Profil de l’objet Facture [BT-24] • [ Basic, CIUS, Extended-CTC-FR ] flowType Liste de valeurs/ codifiées Typologie de l’objet • [CustomerInvoice, SupplierInvoice, StateInvoice, CustomerInvoiceLC, SupplierInvoiceLC, StateCustomerInvoiceLC, StateSupplierInvoiceLC, AggregatedCustomerTransactionReport <;\ flowDirection Liste de valeurs codifiées Sens de flux • In: Incoming flow, from the PDP to the OD • Out: Outgoing flow, from the OD to the PDP trackingId Texte Id externe fixé par le système source, permettant à l’émetteur de cibler la facture ackStatus Liste de valeurs codifiées Statut du traitement consommateur de ce flux • Pending : le flux n’estpasencore intégré • Error : le flux a été traité, une erreur a été identifiée • OK : l’ensemble descontrôles a été effectué avec un résultat Correct Il faut qu’au moins un critère soit spécifié. Conditions de recherche : La recherche s’exécute en appliquant l’opérateurAND afin de combiner les critères. Exemple : Une recherche avec 4 critères cumulatifs : • Recherche de facture • traitée entre le 1er et le 15 janvier ET • Dans le sens sortant : OUT ET • Avec le statut « Error » • where : { • updatedAfter : 2026 01 01T22:03:07.255Z , • updatedBefore : 2026 01 15T22:03:07.255Z , • flowDirection : [ • Out • ], • ackStatus : Error • } Condition de cumul pour les listes de valeurs : La recherche s’exécute en appliquantl’opérateur OR afinde combiner les valeurs. Exemple : une recherchede l’ensemble des factures ayant pour typologie: B2B ou B2G ou B2C. • processingRule : [ • B2B , B2G , B2C • ], Pagination : La pagination fonctionne avec la propriété updatedAfter. La comparaison avec la date actuelle est stricte : updatedAt > updatedAfter

5.3.1 Gestion du différentiel

5.3.1 Gestion du différentiel Le Fournisseur API doit mettre à disposition la route POST / Search pour permettre la récupération des flux en différentiel en permettant à ce dernier de ne récupérer que les dernières factures / statuts nouveaux depuis sa dernière requête.

5.3.2 Garantir l’exhaustivité des flux

5.3.2 Garantir l’exhaustivité des flux Le Fournisseur API doit trier les résultats selon le critère ‘updatedAt’ en ordrestrictement croissant. Le Fournisseur doit garantir au Client API suivant les recommandations ci-dessous de pouvoir récupérer l’exhaustivité desflux; Il est recommandé au Client API de renseigner la valeur ‘updatedAfter’ avec la date du dernier élément récupéré. Note 1 au 5.3.2 Larécupérationdel’exhaustivitédesfluxpeut être garantie par le Fournisseur API lorsque ‘updatedAt’ est une séquence strictement monotone atomiquement. Un moyen permettant de le garantir est de laisser le temps aux transactions de la base de données et aux traitements parallèles de se terminer. Par exemple, sionconsidèrequ’undélaide minutes est suffisant, il s’agit de retourner un jeu de données avec ‘updatedAt’compris entre la valeur ‘updatedAfter’passée en paramètre et la date système du serveur de la base de données moins 15 minutes.

5.4 Récupérer un flux (Route GET / flows / {flowId} )

5.4 Récupérer un flux (Route GET / flows / &#123;flowId&#125; )

5.4.1 Paramètre ‘docType’

5.4.1 Paramètre ‘docType’ Lorsque le flux est une facture, le paramètre ‘docType’de la Route GET/flowspermet auClientAPI d’indiquer le composant de facture demandé, avec les valeurs suivantes : • « Metadata » :l’objet Json décrivant le flux. • « Original » : La facture telle que reçue. • « ReadableView » : La représentation lisible de la facture. • « Converted ». Une version convertie (préalablement ou à la volée) de façon à pouvoir choisir un format préféré. PA Note 1 au 5.4.1 : le Fournisseur API peut permettre au Client API de configurer la règle suivante :l’ensembledesfactures reçues en UBL sont converties en Factur-x, pour que ces conversions puissent être préparées en amont.

5.4.2 Récupération du lisible d’une facture

5.4.2 Récupération du lisible d’une facture Le lisible mis à disposition par la PA doit l’être par la route GET / flows. Lorsquele lisible d’une facture n’estpasfournipar l’émetteur et quecette facture estdansun format du socle, le Fournisseur API doit pouvoir le générer et le retourner par la route GET / flows / &#123;flowId&#125;.

5.5 Gestion des flux irrecevables et des rejets

5.5 Gestion des flux irrecevables et des rejets Le Fournisseur API doit distinguer • Les contrôles techniques et applicatifs qui,en casd’erreur, peuvent conduire à une irrecevabilité d’un Flux • Les contrôles fonctionnels qui, encasd’erreur, peuvent conduire à un Rejet du Flux. Le Fournisseur API doit retourner l’erreur au Client API ; • Par un flux CDAR lorsqu’ils’agitd’un Rejet et qu’il existe unCDAR pour le flux • Par la propriété FlowAckStatus lorsque le flux est irrecevable ou qu’iln’existe pasde CDAR pour le flux (Exemple Flux CDAR envoyé où on ne retourne pas un autre CDAR pour informer de l’irrecevabilité)

5.5.1 Irrecevabilité d’un flux envoyé par le Client API au Fournisseur API

5.5.1 Irrecevabilité d’un flux envoyé par le Client API au Fournisseur API La propriété « FlowAckStatus » doit être renseignée par le Fournisseur API par un statut ‘Error’lorsque le flux est irrecevable et par un statut « Ok » lorsque le flux est recevable. Lorsque le flux est irrecevable, le Fournisseur API doit retourner un code erreur dansla propriété‘reasonCode’ de l’objet ‘AcknowledgementDetail’. Le Fournisseur API doit utiliser les codes du tableau 4 ci-dessous mais est libre de rajouter d’autrescodes erreurs. Tableau 4 — Codes erreurs pour un flux irrecevable Code erreur (reasonCode) Code Z12 012 Description EmptyAttachement IRR_VID_PJ Lune ou plusieurs piècesjointessont vides AttachmentTypeError IRR_EXT_DOC Le type et/ou l’extension d’une ou plusieurs pièce jointes n’estpas conforme EmptyFlow IRR_VIDE_F Le flux est vide OtherTechnicalError AUTRE Autre problème technique InvalidSchema IRR_SYNTAX Schéma XML invalide FileSizeExceeded IRR_TAILLE_F Taille limite de fichier atteinte FlowTypeError IRR_TYPE_F Le type et/ou l’extension du flux ne sont pas conformes AlreadyExistingFlow N/A Le flux a déjà été envoyé et réceptionné (Exemple : empreinte numérique identique) A ne pas confondre avec le contrôle sur le doublon du n° de facture. VirusFound IRR_ANTIVIRUS Contrôle anti-virus Le flux ne respecte pas les conditions de sécurité ChecksumMismatch N/A Lempreinte numérique nest pas cohérente;

5.5.2 Rejet d’un flux facture par la PAe ou la PAr

5.5.2 Rejet d’un flux facture par la PAe ou la PAr Lorsqu’une factureest rejetée par la PA émettrice (PAe) ou par la PA de réception (PAr) le Fournisseur API doit créer et mettre à disposition au Client API un flux CDAR avec un statut 213. Note 1 au 5.5.2 : Pour rappel, la norme XP Z12-014 indique que statut 213 doit également être envoyé au concentrateur public. Note 2 au 5.5.2 : Un motif de rejet peut par exemple un problème de routage ou une règle métier en erreur.

5.5.3 Rejet d’un flux Cycle de Vie sur une Facture

5.5.3 Rejet d’un flux Cycle de Vie sur une Facture La propriété « FlowAckStatus » doitêtre renseignée par le Fournisseur API par un statut ‘Error’lorsque le flux est rejeté. Le Fournisseur API doit utiliser les codes du tableau 5 ci-dessousmaisestlibre de rajouter d’autres codes erreurs. Tableau 5 — Codes erreurs pour un flux de Cycle de Vie rejeté Code erreur (reasonCode) Code des spécifications externes Description InvoiceLCInvalidStatu s REJ_INC Lun ou plusieurs statuts sont incohérents InvoiceLCStatusError REJ_INEX Lun ou plusieurs statuts sont incorrectes ou non autorisées InvoiceLCRuleError REJ_RG Lune ou plusieurs règlesde gestion ne sont pas respectées InvoiceLCAccesDenied REJ_HAB Lune des requêtes nest pas autorisées et/ou requiert une habilitation InvoiceLCAmountErro r REJ_ENCAISSEMENT Lun ou plusieursmontants encaissés ne sont pas conformes à la répartition par taux de TVA déclarée

5.6 Informer le Client API de l’arrivée ou de la modification d’un flux par un Webhook

5.6 Informer le Client API de l’arrivée ou de la modification d’un flux par un Webhook Ce chapitre sera complété ultérieurement. Vous trouverez en « Annexe D –Préversion des Webhook » l’état actuelde nos travaux qui ne sont pas finalisés.

6 API – Annuaire

6 API – Annuaire

6.1 Respect du Swagger Directory Service

6.1 Respect du Swagger Directory Service L’API publiée par le Fournisseur API doitrespecterle SWAGGER dansl’Annexe Bselon les règles décrites en 4.1.

6.2 Consultation de l’Annuaire

6.2 Consultation de l’Annuaire

6.2.1 Routes

6.2.1 Routes Le Fournisseur API doit publier les routes API obligatoires listées dans le Tableau 6 ci-dessous. Pour les routes POST/siren/search, POST/siret/search, POST/routing-code/search et POST/directoryline/ search le Fournisseur API doit à minima permettre au Client API de récupérer toutesleslignesd’annuaire respectivement lorsqu’un SIRENcomplet est passé en paramètre. PA Il est recommandé au Fournisseur API de proposer les autres fonctionnalités avancées de recherche (recherche sur un libellé, un SIREN ou un SIRET incomplet etc<);LeFournisseur API doitretourner uncode erreur explicite si la requête en consultation n’estpas prise encharge; Note 1 au 6.2 : Ilestrappeléau FournisseurAPI, qu’il ne doit retourner que les données publiables. Tableau 6 — Routes de consultation de l’Annuaire Ressource Route Description SIREN POST/siren/search Rechercher un SIREN avec plusieurs critères en JSON GET/siren/code-insee:{siren} Rechercher un SIREN avec le SIREN (test d’existence ou récupération des informations du SIREN) SIRET POST/siret/search Rechercher un SIRET avec plusieurs critères en JSON GET/siret/code-insee:{siret} Rechercher un SIRET avec le SIRET (test d’existence ou récupération des informations du SIRET) Code routage POST/routing-code/search Rechercher un code routage avec plusieurs critères en JSON GET/routingcode/ siret:{siret]/code:{routingidentifier} Rechercher un code routage avec le SIRET de rattachement et le code routage (test d’existence ou récupération des informations du code routage) Ligne d’adressage POST/directory-line/search Rechercher une ligne d’annuaire avec plusieurs critères en JSON GET/directory-line/code: {addressing-identifier} Rechercher une ligne d’adressage avec l’identifiant d’adressage (test d’existence ou récupération des informations de la ligne).

6.2.2 Propriété DirectoryLineStatus

6.2.2 Propriété DirectoryLineStatus Les routes ‘GET/directory-line’ et ‘POST/directory-line/search’ doivent retourner la propriété‘directoryLineStatus’ permettant d’indiquer au Client API le statut d’une ligne; Codification Valeur Description Disabled Désactivé Une ligne d’annuaire désactivée se voitpositionnée à la plateforme 9998 Enabled Activé Une plateforme a été définie, la ligne d’annuaireest active. Upcoming En cours Une plateforme ou une nouvelle plateforme a été fixée et sa date de début est strictement postérieure à la date du jour. A partir de la Datedébut, la ligne d’annuaire passera au statut Enabled/Activé. Le fournisseur de l’API doitappliquer des règles afin de déterminer les valeurs « disabled », « enabled » et « upcoming » du champ directoryLineStatus, tellesqu’expriméesci-dessous en pseudo-code : • Si (Nature = D) & (DateDebut <= J < DateFin (si renseignée)) & (plateforme = 9998) => disabled • Si (Nature = D) & (DateDebut <= J < DateFin (si renseignée)) & (plateforme != 9998) => enabled • Si (Nature = D) & (J < DateDebut & plateforme != 9998) => upcoming Notes au 6.2.2 : • J : Date du jour • DateDebut : Date de débutd’effet de la ligne • DateFin : Valeur minimale entre la date defind’effetet la date de fin effective de la ligne • Nature D : Nature « Définition » dans l’annuaire public • Nature M : Nature « Masqué » dansl’annuaire public • Plateforme 9998 :Lorsqu’une ligne d’adressage n’a pasde plateforme agréée associée

6.2.3 Propriété isSalesProspectingForbidden

6.2.3 Propriété isSalesProspectingForbidden Le critère « non-diffusible » est matérialisé dansl’annuaire PPF. Afin de partager cet élément lors de la consultation de l’annuaire, un critère Booléen Yes/No « isSalesProspectingForbidden », permet de notifier que les données concernéessur le bloc d’information SIREN et SIRET sont interdites à la diffusion pour des besoins de prospection et de vente. Le fournisseur API doit appliquer les règles suivantes pour déterminer la valeur booléenne de « isSalesProspectingForbidden ». Non Diffusible Description isSalesProspectingForbidden Conséquences O Non Diffusible false Données non présentes P Partiellement Diffusible false Données confidentielles non présentes : • le numéro + la voie de l’adresse postale M Diffusible avec un Refus de prospection commerciale true Données présentes, mais en précisant le cadre d’utilisation à respecter Ces règles sont exprimées ci-dessus à partir de la propriété Diffusible DT-3-6 (SIREN), DT-4-14 (SIRET) de l’annuaire.

6.3 Mise à jour de l’Annuaire

6.3 Mise à jour de l’Annuaire La mise à jour à l’annuaire pourra faire l’objet d’un travail de normalisation dans une version ultérieure; 7 Gestion de la délégation 7.1 Principes généraux La gestion de la délégation vise à faciliter l’accèsauxdonnéesstockéeschez le Fournisseur API par des tiers habilités par les entreprises (tels que les experts-comptables, les affactureurs, les tiers payeurs, les agents d’acheteurs, les sociétésholding, ...). PA La délégation implique donc 3 parties : • L’entreprise qui va donner accès à ces données et qui passera par un Client API • Le Fournisseur API • Le Tiers qui peut être une entreprise ou une organisation. 7.2 Exigences de la gestion de la délégation Il est recommandé que le Fournisseur d’API et le Tiers mettent en oeuvre un dispositif de

Gestion de la délégation

gestion de la délégation conforme aux exigences suivantes : • Assurer la sécurisation de la transmission du client id et du client secret, afin de garantir que ces éléments ne soient accessibles qu’aux personnesdûment habilitées; • Veiller à ce que la délégation ne soit pas rattachée à une personne physique susceptible de quitterl’organisationou l’entreprise. • Veiller à s’assurer de l’identité du Tiers.

7.1 Principes généraux

_Extrait OCR indisponible dans la source convertie._

7.2 Exigences de la gestion de la délégation

_Extrait OCR indisponible dans la source convertie._

7.3 Périmètre de la délégation

7.3 Périmètre de la délégation Ilestrecommandéque le Fournisseur d’API de permettre àl’entreprise de définirle périmètre de la délégation selon les droits ci-dessous : ⎯ Pour l’API Flux • Lecture (search et Get) et/ou Ecriture (Post) • Flowtype • Périmètre plus détaillé allant pour gérer par exemple des cas liésàl’affacturage, le tiers payeur etc... ⎯ Pour l’API Directory • Consultation : oui/non

7.4 Processus de délégation au tiers au travers d’un client id / client secret pour chaque entreprise

7.4 Processus de délégation au tiers au travers d’un client id / client secret pour chaque entreprise

7.4.1 Description du processus

7.4.1 Description du processus Ce processus se déroule en 3 grandes étapes : 1. Création d’un clientid/clientsecret par l’entreprise pour le Tiers dans une interface mise à disposition par le Fournisseur API. 2. La base URL, la « token URL », le client id et le client secret sont ensuite renseignés dans le système d’information du Tiers; 3. Le Tiers se connecte au Fournisseur API grâce à la base URL, la token URL, le client id et le client secret.

7.4.2 Conformité du processus

7.4.2 Conformité du processus La conformité du processus va dépendre des choixd’implémentationdu processus mis en place. Le Tableau 38 ci-dessous liste 3 exemples de processus : • L’exemple A\est un processus déconseillé car il ne répond pas aux exigences. • Les exemples B], C] permettent de répondre aux exigences. Sur l’objectifde veiller às’assurer de l’identité du Tiers, le Fournisseur API est dépendant du processus mis en place le Tiers. Tableau 7 — Exemples de processus Description du processus Objectif de sécurisation du client id/ client secret Délégation à une entreprise A] Processus non conforme A1. Création d’un client id/client secret par l’entreprise dans la PA; Non conforme : La transmission par email n’est pas sécurisée. Par exemple : A2. Transmission par un moyen non sécurisé (email) à un collaborateur du tiers. Ce mail peut être transféré à une boite email supplémentaire, conservé A3. Le collaborateur du tiers dans une messagerie renseigne l’URL , la « token URL », le personnelle, etc. client id et le client secret dans l’outil métier. B] Processus conforme sous réserves avec un Tiers ne disposant pas d’un Conforme sous réserved’une transmission Conforme sous condition Le collaborateur ayant portail accessible à l’entreprise; B1. Création d’un client id/client secret par l’entreprise dans la PA. B2. Transmission par un canal sécurisé à un collaborateur du Tiers. sécurisée. réceptionné le client id /client_secret doit associer cesélémentsd’identification au Tiers concerné, dansl’outil métierEt ne doiten aucun casl’associer à son compte personnel. B3. Le collaborateur du tiers renseigne l’URL, le client id et le client . secret dans l’outil métier C] Processus conforme avec un Tiers disposant d’un portail accessible à l’entreprise; C1; Création d’un Compte Tiers sur la PA C2. Accréditation du Tiers par l’entreprise C3. Identification d’une clé d’organisation pour l’entreprise; => Détail Chapitre ci-dessous Conforme : La transmission est sécurisée Conforme : En dehors des administrateurs du Tiers, aucun collaborateur du Tiers n’a accès au client secret.

7.5 Processus de délégation avec une authentification unique par Tiers au sein de chaque Fournisseur API

7.5 Processus de délégation avec une authentification unique par Tiers au sein de chaque Fournisseur API

7.5.1 Description du processus

7.5.1 Description du processus Ce processus se déroule comme suit : 1. Référencement du Tiers Le Tiers doit se référencer en créant un compte d’entreprise Tiersauprès de la PA / du Fournisseur API de l’Entreprise. 2. Délégation du Tiers par l’Entreprise Depuis son Fournisseur API, un utilisateur habilité de l’Entreprise accrédite le Tiers précédemment référencé en définissant son périmètre de délégation. PA 3. Transmission de l’identifiant d’Entreprise Lorsquecela estrequis, l’utilisateur de l’Entreprise communique au Tiers son identifiantd’Entreprise au sein de sa PA. Cet identifiant correspond soit : • au SIRENde l’Entreprise, • soit à un identifiant technique interne propre au Fournisseur API. Ilestrecommandéde privilégier l’utilisation du SIRENen tantqu’identifiantd’organisation dèslorsquecela est possible. 4. Action du Tiers pour le compte de l’Entreprise Lorsqu’ilsouhaite agir pour le compte d’une Entreprise, le Tiers s’authentifie à l’aide de ses propres mécanismesd’authentification et utilise l’identifiantd’Entreprise transmis;

7.5.2 Conformité du processus

7.5.2 Conformité du processus 1. Veiller à s’assurer de l’identité du Tiers: • Le fournisseur API peut mettre en place un système de vérification d’identité du Tiers; 2. Délégation à une entreprise et non à un utilisateur : Conforme. 3. Objectif de sécurisation du client id/ client secret : Conforme. • En dehorsdes administrateursdu Tiers, aucun collaborateur du Tiers n’a accès au client secret;

7.5.3 Indiquer le périmètre organisationnel de l’appel API

7.5.3 Indiquer le périmètre organisationnel de l’appel API Le client Id pouvant être unique pour un Tiers, le Client API doit pouvoir indiquer sur quelle(s) organisation(s) il veut agir. Le Client API doit indiquer l’identifiantde l’organisation sur laquelle ilfautagir en renseignant avec une balise ‘Organisation-Id’dans le header http.

Pré-version des Webhooks

Pré-version des Webhooks Version de travail pour information seulement. Définition Un webhook est une communication orientée événements qui transmet de façon automatique des données entre les applications via HTTP. • Déclenchés par des événements précis, les webhooks automatisent la communication retour vers le SI à l’origine de la demande de traitement; PA / PDP SC/ OD Évènement Webhooks API Flow Le webhook va permettre au Client API de recevoir les évènements traités ou reçus, par le Fournisseur API, afin de leur remonter les informations au fur à mesure de la journée. Il n’estplus nécessaire d’interroger en mode Pooling; les évènements remontent naturellement. Ce type de mécanisme se construit en 3 phases : • Un abonnement via un appel API • Le déclenchementd’un évènementde type webhook • La consommation de cet évènementdansle SI Clientd’origine par une API construite selon le swagger défini ci-dessous. Les avantages du webhook : • Il remplace l’interrogation continue. L’application client économise ainsi des ressources. • Il est rapide à configurer;Le webhook peut être facilementconfiguré via une API d’abonnement; C’est là que le client ajoute l’URL de son webhook et définit les paramètres de base, comme l’événement qui l’intéresse. • Il automatise le transfert de données. Les données utiles sont envoyées dès que l’événement recherché se produit. C’est cet événement qui déclenche l’échange, qui s’effectue donc aussi rapidement que tout transfert en temps réel. Complémentarité du Webhook et de la méthode /Flows/Search Casd’usage: Le endpoint /Flows/Search peut servir de solution de backup pour récupérer un historique de flux en cas d’indisponibilité de l’API à l’écoute des évènements Webhook; Principe général : Le clientAPI viendra s’abonner en utilisantles méthodesprésentéesau chapitre n°A-Abonnement Webhook (Tableau 2) Le ClientAPI doitconstruire un endpointAPI d’écoute desmessageswebhook, conforme aucontrat swagger en cours de construction au paragraphe N° B –Consommation de l’évènementWebhook (Tableau4) A -Abonnement Webhook Il est recommandé au Fournisseur API de mettre à disposition les routes décrites dans le tableau 1 ci-dessous : Tableau D1— Routes permettant d’administrer les abonnements Webhook Méthode POST Endpoint /v1/webhooks Description Créer un Webhook PATCH /v1/webhooks/{webhookUid} Permet de mettre à jour un abonnement, afin de changer la configuration DELETE /v1/webhooks/{webhookUid} Permet de supprimer l’abonnement à ce webhook GET /v1/webhooks Lister l’ensemble des abonnements GET /v1/webhooks/{webhookUid} Lire la configuration de l’abonnement concerné Créer / modifier un abonnement au webhook Méthode Endpoint Description POST /v1/webhooks Créer un Webhook Un appel en précisant plusieurs paramètres : • url de rappel • des métadonnées pour configurer cet abonnement (bloc callBack) • Rubrique Authentification • Rubrique Signature • Rubrique Headers • des métadonnées pour préciser les évènements métiers (bloc metadata) Rubrique Authentification : plusieurs méthodes de sécurisation des appels sont proposées par les Plateformes agréés. • Méthode Basic : Authentification via un compte technique, à l’aide d’un login et d’un password • Méthode Oauth2 – Client_Credentials with Secret [OAUTH2_CCWS] : Authentification à l’aided’un token, fourniàpartirdes éléments Client_Id / client_Secret • Méthode OIDC – Client credentials with assertions [OIDC_CCWA]: Authentificationàl’aided’un jeton JWT signé à l’aide de la clé privé • Al’arrivédela demande d’authentification, lasignature dujeton JWTestvérifiéeàl’aide de la clé publique. • Pointd’attention: ce mode d’authentification nécessite un processusd’échange de clé publique entre le Client_API et le Fournisseur_API, qui peut s’organiser en amont de l’utilisation du webbookou se partager au momentde l’abonnement • Renvoyer la clé publique dans la réponsede l’abonnement PA Rubrique Signature • Signature du message payload json via un algorithme proposé [RS256, HS256, ECDSA, EDDSA_25519] et une clé de signature. Voici la liste des champs à configurer dans le message JSON lors de l’appel API,via la méthode POST Tableau D2— Paramètres d’appel de création / modification d’un Webhook Param Type Valeur url (*) Text(uri) url d’appel du système source authType Liste de valeurs codifiées Méthode d’authentification [BASIC, OAUTH2_CCWS, OIDC_CCWA] BasicAuthentification -UserId -userPassword Texte Texte Configuration du mode Basic -UserId du compte technique concerné -userPassword oAuth2Authentification -tokenUrl -clientId -clientCredendials url Texte Texte Méthode oAuth2 Url à appeler pour obtenir un jeton d’accès Identifiant du compte techniqueAPI, lorsd’un échange entre 2 serveurs Chaine complexe quisert de motde passe lorsde l’échange Signature -algo -key Liste Texte Permet de signer les données selon l’un des algorithmes proposés [RS256, HS256, ECDSA, EDDSA_25519] Clé de signature (Base64 encoded string) Headers [] -hearderName -headerValue Texte Texte Couple de clé / valeur à répéter afin d’apporter des caractéristiques propres à votre SI Configuration des critères métiers qui permettent de cibler • Certains flux In/ Out • Certaines natures : B2B, B2C, etc • Certains objets : Invoice, LifeCycle,TransactionReport < • Certains évènements : Pending, Error, OK Tableau D3 -Paramètres métiers configurés sur l’abonnement Webhook Param Type Valeur processingRule Liste valeurs codifiées de Nature des factures reçues et traitées, [ B2B, B2BInt, B2C, OutOfScope, ArchiveOnly, NotApplicable ] flowType Liste valeurs codifiées de Type de flux reçus et traités [CustomerInvoice, SupplierInvoice, StateInvoice, CustomerInvoiceLC, SupplierInvoiceLC, StateCustomerInvoiceLC, StateSupplierInvoiceLC, AggregatedCustomerTransactionReport <;\ flowDirection Liste valeurs codifiées de Direction du flux [IN, OUT] ackstatus Liste valeurs codifiées de Statuts du document [Pending, Error, OK] -Pending: he flows is not yet integrated -Error: one of the previous tests has failed -OK: the following checks have passed Request-ID Permet de taguer l’abonnement avec une clé Réponse lors de l’abonnement au webhook : { "webhookId": apublicKeya "3fa85f64-5717-4562-b3fc-2c963f66afa6", : “string” } B – Consommation de l’évènement Webhook Flux d’utilisation : 4 méthodes de sécurisation Mode Basic Mode Client_Credential with_Secret PA Mode Client_Credential with_assertion Mode Signature Présentation de la structure du message L’évènement Webhook remonte un message payloadJSON contenant: • Un objet ‘WebhookCallbackContent’ • Paramétre IDOrganisation :ce paramètre permet d’identifier l’organisationinterne dansle cas d’unesociété ayant plusieurs • Lorsque le WebHook est utilisé dans un usage avec plusieurs organisations des propriétés permettantauClientAPId’identifier l’organisation, afinde permettre àcedernier d’utiliser la bonne authentification pour récupérer les flux. Note 1 : lespropriétéspermettantau ClientAPI d’identifierl’organisationpeuventêtre,parexemple: • Un identifiant société interne au Client API paramétré lors de la configuration du Webhook, • Un identifiant interne au Fournisseur API, • Un identifiant métier comme un SIREN, une adresse électronique etc. Tableau D4 – Message évènement remonté par le webhook Param Type Valeur Unique identifier supporting UUID but not only, for flexibility purpose flowId String name Texte Name of the file flowDirection • In: Incoming flow, from the PDP to the OD • Out: Outgoing flow, from the OD to the PDP processingRule Enum [ B2B, B2BInt, B2C, OutOfScope, ArchiveOnly, NotApplicable ] flowSyntax Enum [ CII, UBL, Factur-X, CDAR, FRR ] flowProfile Enum [ Basic, CIUS, Extended-CTC-FR ] flowType Enum [CustomerInvoice, SupplierInvoice, StateInvoice, CustomerInvoiceLC, SupplierInvoiceLC, StateCustomerInvoiceLC, StateSupplierInvoiceLC, AggregatedCustomerTransactionReport <;\ processingRuleSource Enum [ Input, Computed ] trackingId Texte The tracking id is an external identifier and is used to track the flow by the sender submittedAt Date The flow submission date and time (the date and time when the flow was created on the system) This property should be used by the API consumer as a time reference to avoid clock synchronization issues updatedAt Date The last update date and time of the flow. When the flow is submitted updatedAt is equal to submittedAt. When the flow acknowledgment status is changed updatedAt date and time is updated. Acknowledgement -Status -Détails • Level • Item • reasonCode • reasonMessage Enum Texte Enum Texte [ Error, Warning ] Item on which the error refers A predefined set of reason code values + ability to extend this set Liste des code retours : reasonCode Description EmptyAttachement One or more attachments are empty. (ie IRR_VID_PJ) AttachmentTypeError The type and/or extension of one or more attachments is not compliant. (ie IRR_EXT_DOC) EmptyFlow The binary flow is empty. (ie IRR_VID_F) OtherTechnicalError Other technical error. (ie AUTRE) InvalidSchema Invalid XML schema. (ie IRR_SYNTAX) FileSizeExceeded : File size limit reached. (ie IRR_TAILLE_F) FlowTypeError The flow type and/or extension are not compliant. (ie IRR_TYPE_F) AlreadyExistingFlow The flow has already been sent and received. (ie N/A) VirusFound Presence of a virus. (ie IRR_ANTIVIRUS) ChecksumMismatch Checksum provided is different from computed one InvoiceLCInvalidStatus One or more statuses are inconsistent InvoiceLCStatusError One or more statuses are incorrect or not allowed InvoiceLCRuleError One or more rules are not matched InvoiceLCAccessDenied One of the request is not authorized and requests permissions InvoiceLCAmountError One or more amounts are not consistent in regards to the VAT C –Mécanismes d’exploitation opérationnelles Les contraintesd’exploitation nécessitentde fixer des seuilsde gestion opérationnelles, par exemple une stratégie de retry, un delai de retry et un nombre maximum de retry. Ces éléments seront fixés par chaquePA, en fonctionde leur propre critère d’exploitation; PA Champs Type Description retryStrategy Enum Stratégie de rappel [Fixed , Exponential, Fibonacci] retryPeriod Numériqu e Délai dattente de retry retryMaxNb Numériqu e Nombre maximal de tentatives

Bibliographie

Bibliographie [1] Dossier de spécifications externes de la Facture électronique 3.1 -Dossier général -Agence pour l’informatique financière de l’État; [2] Norme AFNOR XP-Z12-012 : Formats et Profils des messages Factures et Statuts de cycle de vie, constitutifs du socle minimal applicable à la Réforme Facture Électronique en France [3] Norme AFNOR XP-Z12-014 : Cas d’usage B2B applicables dans le cadre la Réforme Facture Électronique en France

Standardisation des API SI/SC/OD • PA

_Extrait OCR indisponible dans la source convertie._