Intégration API

L’API CCFN v1 utilise des chemins singuliers : /object et /space. Son préfixe est /api/ccfn/v1. Les requêtes de création et de modification utilisent JSON ; les réponses peuvent être JSON, un fichier binaire ou un ZIP selon l’endpoint.

Choisir l’environnement

La spécification source mentionne https://my.datasure.net et https://pp-my.datasure.net. Utilisez uniquement l’environnement dont l’accès CCFN et les comptes vous ont été confirmés. Dans les exemples, CCFN_BASE_URL représente cette origine HTTPS, sans le préfixe d’API.

L’API décrite utilise HTTP Basic. Authentification et droits détaille les comptes à préparer.

Enveloppe JSON

Les réponses applicatives JSON utilisent success, message et, selon le cas, data ou errors. Les listes ajoutent pagination. Les erreurs et les réponses des intermédiaires HTTP ne sont pas toutes garanties sous forme de la même enveloppe ; le refus d’authentification Basic peut notamment être du texte.

{
  "success": true,
  "message": "Resource fetched successfully",
  "data": {"count": 12}
}

Ne parsez pas un téléchargement binaire comme du JSON. À l’inverse, inspectez le statut et le type de contenu avant de conserver la réponse comme un fichier.

Identifiants et dates

Les UUID d’objets et d’espaces doivent être conservés tels quels. La société cible résulte du compte authentifié ; le dépôt ne comporte pas de sélection libre de company_id.

Les dates exposées par le CCFN sont au format ISO 8601 avec un décalage explicite et six chiffres de fraction de seconde, par exemple 2026-11-02T15:04:05.123456+01:00. Comparez-les comme des instants, après interprétation du fuseau, et non comme des chaînes locales.

En-têtes de suivi

En-tête	Usage
`X-Request-ID`	Identifiant de corrélation transmis ou généré pour la requête
`X-CCFN-ID`	Identifiant du composant
`X-CCFN-User-ID`	Identifiant technique de l’utilisateur lorsque l’authentification est connue
`X-CCFN-Completed-At`	Fin de production de la réponse applicative
`Retry-After`	Délai avant une nouvelle consultation pour un dépôt en cours
`X-Content-Digest`	Empreinte d’une restitution binaire ou du ZIP
`X-Content-Digest-Algorithm`	Algorithme de cette empreinte

Les erreurs rejetées par un proxy avant l’application peuvent ne pas contenir les en-têtes CCFN. Préparez un identifiant de requête ne contenant aucune donnée personnelle.

Modèle d’intégration conseillé

Enregistrez pour chaque opération logique sa référence métier, sa clé d’idempotence, l’empreinte du fichier, l’espace visé et les paramètres exacts. Après succès, ajoutez l’UUID et l’échéance retournés. Les reprises doivent relire cet état durable.

Fixez le modèle de métadonnées, la durée de rétention, les critères de validation de signature et les besoins de réversibilité avant les premiers dépôts de production. Un même paramètre ne doit pas changer entre deux reprises d’une même clé.

Parcours technique : Référence des endpoints → Erreurs et supervision → Exemples.