Interroger les APIs et synchroniser

L'intégration actuelle fonctionne en mode client initié : l'ERP ou le SI appelle les APIs pour consulter l'état des ressources et rechercher les nouveaux éléments.

Pas de webhook actuellement

La plateforme n'expose actuellement aucun webhook public pour notifier un changement d'onboarding, une nouvelle facture, un nouveau statut CDAR ou l'évolution technique d'un flux. L'intégration ne doit donc pas attendre un appel entrant de myBCS et doit mettre en œuvre le polling décrit sur cette page.

Le contrat AFNOR Flow Service peut prévoir des ressources de webhook. Cette possibilité du standard ne signifie pas qu'elles sont disponibles dans l'implémentation myBCS actuellement publiée. Le Swagger/OpenAPI de l'environnement fait foi pour les routes réellement exposées.

Quel mode utiliser selon l'API ?

Domaine	Mode d'interrogation	Route principale	Usage
Onboarding	Polling ciblé d'une unité légale	GET /v1/onboarding/legal-units/{legalUnitId}/state	Suivre une opération asynchrone et connaître l'état courant
Directory Service	Recherche à la demande	Routes POST /search et GET par identifiant	Déterminer ou vérifier l'adressage avant l'émission d'une facture
Flow Service	Polling différentiel continu	POST /v1/flows/search	Détecter les nouvelles factures, les nouveaux CDAR et les évolutions techniques des flux

Onboarding

Après une opération asynchrone telle que le démarrage ou le redémarrage d'un onboarding :

1. conservez le legalUnitId et l'éventuel onboardingRequestId ;
2. interrogez régulièrement la route /state ;
3. considérez la réponse serveur comme la source de vérité ;
4. ralentissez les appels lorsque l'état ne change pas ;
5. arrêtez le polling intensif lorsqu'un état terminal ou une action humaine est atteint ;
6. utilisez /history pour afficher ou diagnostiquer la chronologie, et non comme flux de notifications.

Les états ACTION_REQUIRED, IDENTITY_CHECK_ACTION_REQUIRED et BUSINESS_VERIFICATION_ACTION_REQUIRED nécessitent une intervention. Les états COMPLETED et CANCELLED mettent fin au suivi actif de la demande concernée.

➡️ État et historique de l'onboarding

Directory Service

Le Directory Service ne constitue pas un flux d'événements. Il est interrogé à la demande :

1. lors de la création ou de la mise à jour de la fiche client, vérifiez le SIREN/SIRET et l'adresse de facturation électronique ;
2. enregistrez dans le SI l'adresse validée et, si utile, la date de vérification ;
3. avant l'émission d'une facture, revalidez l'adressage lorsque cela est nécessaire ;
4. lorsqu'une recherche ciblée retourne plusieurs résultats, utilisez limit et ignore uniquement pour parcourir cette recherche jusqu'à obtenir le résultat métier attendu.

Pas de synchronisation exhaustive

Le Directory Service ne doit pas être utilisé pour parcourir ou recopier l'ensemble de l'annuaire. La pagination est limitée au résultat d'une recherche ciblée portant sur un destinataire ou une adresse connue.

Il n'est donc pas nécessaire d'effectuer un polling continu du Directory Service.

➡️ Guide Directory Service
➡️ Recherche et pagination Directory

Flow Service

Le Flow Service doit être interrogé régulièrement pour découvrir :

• les nouvelles factures entrantes ;
• les nouveaux statuts de cycle de vie CDAR reçus ;
• les nouveaux flux d'e-Reporting FRR à traiter ;
• les changements de ackStatus ou de métadonnées sur les flux déjà connus ;
• les autres flux entrants ou sortants utiles à l'intégration.

Fenêtre de recherche

Utilisez POST /v1/flows/search avec une fenêtre différentielle fondée sur updatedAfter et, lorsque le contrat de l'environnement le permet, updatedBefore.

Exemple de principe :

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

Cet exemple illustre le mécanisme. Les valeurs admises, la pagination et les champs disponibles doivent être vérifiés dans le Swagger/OpenAPI de l'environnement.

Algorithme recommandé

1. conservez un point de reprise durable en UTC ;
2. définissez une borne haute fixe au début du cycle de polling ;
3. recherchez les flux modifiés entre le point de reprise et cette borne haute ;
4. parcourez la totalité des résultats selon le mécanisme de pagination exposé ;
5. traitez chaque résultat de manière idempotente ;
6. récupérez avec GET /v1/flows/{flowId} la représentation nécessaire : docType=Metadata ou docType=Original pour tout flux ; pour une facture entrante, utilisez si besoin ReadableView, Converted ou Ubl ;
7. avancez le point de reprise uniquement après le traitement réussi de toute la fenêtre ;
8. en cas d'échec, rejouez la même fenêtre et ignorez les doublons déjà traités.

Conservez au minimum flowId, updatedAt, flowDirection, flowType, ackStatus et le trackingId éventuel. Un nouveau document possède son propre flowId, tandis qu'une évolution technique peut modifier un flux déjà connu. Une déduplication fondée uniquement sur flowId ferait donc perdre les mises à jour ultérieures de ce flux.

Pour réduire le risque lié aux événements ayant exactement le même horodatage que le point de reprise, rejouez un léger chevauchement entre deux fenêtres et dédupliquez les résultats.

Recherches à prévoir

Besoin	Filtres de principe
Nouvelles factures reçues	flowDirection = In et type de flux facture applicable
Nouveaux statuts reçus	flowDirection = In et type de flux cycle de vie/CDAR applicable
Nouveaux rapports e-Reporting	Direction et flowType FRR applicables selon le contrat publié
Suivi des dépôts émis	flowDirection = Out, trackingId si disponible, et évolution de ackStatus

Les valeurs exactes de flowType dépendent du contrat publié et du sens métier du document. Elles ne doivent pas être déduites uniquement de la syntaxe XML.

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

Fréquence, reprise et limites

Il n'existe pas une fréquence unique adaptée à tous les clients. Elle doit tenir compte du volume, du délai métier attendu et des limites de requêtes de l'environnement.

• appliquez une temporisation croissante lorsque rien ne change ;
• ralentissez après un 429, un timeout ou une indisponibilité temporaire ;
• ajoutez du jitter pour éviter que plusieurs traitements démarrent simultanément ;
• journalisez le début et la fin de chaque fenêtre, le nombre de résultats et le point de reprise validé ;
• ne rechargez pas tout l'historique à chaque cycle ;
• ne faites jamais avancer le point de reprise après un traitement partiel.

➡️ Résilience, observabilité et sécurité