Résilience, observabilité et sécurité

Limites d’utilisation et rate limiting

L’utilisation des API est soumise à des limites de débit et de volume afin de préserver la disponibilité du service et d’assurer un usage équitable de la plateforme.

Ces limites sont transverses : elles peuvent s’appliquer aux différentes familles d’API, notamment au Flow Service, au Directory Service, aux API d’onboarding et aux Partner APIs. Elles ne constituent pas des codes d’erreur normatifs propres aux API AFNOR.

Les limites applicables peuvent dépendre :

• de l’environnement ;
• du partenaire ou du tenant ;
• du profil d’accès ou de la configuration associée aux credentials ;
• de la fenêtre considérée, par exemple à la minute ou à la journée.

Sur la SANDBOX, certains accès sont actuellement documentés avec les limites suivantes :

• 60 requêtes par minute ;
• 1 000 requêtes par jour.

Valeurs dépendantes de la configuration

Ces valeurs ne doivent pas être considérées comme des seuils universels pour tous les accès. Les limites applicables sont celles associées à l’environnement et au profil d’accès utilisés.

Dépassement d’une limite

Lorsqu’une limite d’utilisation est dépassée, l’API peut répondre :

HTTP/1.1 429 Too Many Requests

Le code 429 indique que l’appelant a dépassé une limite de requêtes applicable. Il ne signifie pas que les credentials sont invalides. Une erreur d’authentification reste signalée par les codes prévus à cet effet, notamment 401 Unauthorized.

Le 429 Too Many Requests est un comportement d’exploitation de la plateforme. Il ne doit pas être interprété comme un code d’erreur défini par le standard AFNOR pour le Flow Service ou le Directory Service.

Le client doit interrompre les nouvelles tentatives immédiates et reprendre ses appels après une temporisation adaptée. Si la réponse contient un en-tête Retry-After, sa valeur doit être respectée.

Rate limiting et protections de sécurité

Le rate limiting d’usage documenté ici est distinct des mécanismes de protection contre les abus, scans, attaques automatisées ou dénis de service. Ces mécanismes de sécurité peuvent appliquer d’autres règles de blocage et ne sont pas décrits dans la documentation d’intégration.

Retry

Utiliser un backoff exponentiel avec jitter pour les erreurs transitoires :

• 429 Too Many Requests ;
• 500 ;
• 503 ;
• timeouts réseau.

Ne pas retry automatiquement les erreurs métier explicites telles que 400, 403, 409 ou 422, sauf cas documenté par l'API.

Limiter le nombre de tentatives et journaliser chaque tentative avec son identifiant de corrélation.

Pour une opération qui modifie l’état du système, ne pas supposer qu’un retry est sans effet de bord : respecter les règles d’idempotence et de reprise propres à l’endpoint concerné.

Polling

Les webhooks ne sont actuellement pas exposés par la Tenant Public API myBCS. Le suivi repose donc sur des appels initiés par l'ERP ou le SI :

• polling différentiel de Flow Service pour les nouvelles factures, les nouveaux statuts et les évolutions techniques ;
• polling de /state pour suivre une opération d'onboarding ;
• recherches Directory déclenchées à la demande, sans polling continu.

Pour Flow Service, le suivi différentiel doit exploiter les mécanismes documentés par le contrat de l'environnement, notamment updatedAfter lorsque celui-ci s'applique.

➡️ Interroger les APIs et synchroniser

Observabilité

Les logs d'intégration doivent permettre le diagnostic technique et la réconciliation métier.

Identifiant	Usage
Request-Id	Corrélation technique d'un appel
tenantSlug	Référence du tenant
Organization-Id	Organisation ciblée
jobRunId	Dispatch du provisioning
legalUnitId	Unité légale
onboardingRequestId	Demande d'onboarding
apiAccessId / clientId	Traçabilité de l'accès API, sans journaliser le secret
flowId	Identifiant plateforme du flux
trackingId	Identifiant métier côté appelant

Les réponses 429 doivent être journalisées avec au minimum la date/heure, l'endpoint, le code HTTP et l'identifiant de corrélation disponible. Lorsque cela est utile au diagnostic, journaliser également le tenant ou l'organisation concernée, sans exposer les secrets ni les tokens.

Sécurité et secrets

• Stocker client_id et client_secret dans un coffre de secrets ou un service équivalent.
• Ne jamais exposer access tokens, secrets bootstrap ou clientSecret dans les logs.
• Séparer strictement les credentials par environnement.
• Appliquer le principe du moindre privilège sur les scopes et comptes techniques.
• Lorsque la signature HTTP RFC 9421 est activée pour un profil, respecter les composants imposés par la documentation de sécurité applicable.

Checklist intégrateur

• Les endpoints et payloads sont vérifiés dans l'OpenAPI de l'environnement.
• Les headers de sécurité et de contexte requis sont transmis.
• User-Agent: BCSolutions est utilisé lorsque requis.
• Les secrets sont hors code source et hors logs.
• Les retries sont limités, avec backoff et jitter.
• Les identifiants de corrélation sont propagés.
• Les erreurs HTTP sont distinguées des rejets métier asynchrones.
• Les environnements sont strictement séparés.
• Les limites de requêtes sont prises en compte.