Guide d’intégration pas à pas

Suivez ce parcours dans l’ordre : créez les accès, raccordez une entreprise, mappez vos données, testez en sandbox, puis contrôlez les preuves avant la production.

Avant de commencer

Un accès autorisé à D2F Compliant Solution avec le profil Intégration, Partenaire ou Opérateur.
Un exemple JSON représentatif produit par votre ERP, PMS, CRM ou GED.
Les informations légales de l’entreprise cliente à raccorder.
Un environnement sandbox : aucune transmission réglementaire réelle n’est effectuée pendant ces étapes.

Procédure complète

1OBLIGATOIRE

Créer une clé API

Dans Developer Portal, sélectionnez « D2F Compliant Solution ». Descendez jusqu’à « Connexions & clés API », donnez un nom à la connexion et cliquez sur « Générer la clé API ». Copiez immédiatement la clé : elle n’est affichée qu’une fois. Si votre clé a été créée avant la version 3.47.3, régénérez-la pour obtenir les droits CBM v2.

2OBLIGATOIRE

Raccorder l’entreprise cliente

Ouvrez « Integration Hub », puis l’onglet « Entreprises ». Ajoutez l’entreprise avec son pays et son identifiant légal. Conservez le Connection ID affiché : il identifie cette entreprise dans toutes les requêtes sans mélanger les tenants.

3OBLIGATOIRE

Identifier les champs CBM

Ouvrez l’Explorateur CBM. Recherchez chaque donnée de votre source et vérifiez sa responsabilité : SOURCE_REQUIRED doit être fourni par votre logiciel ; D2F_DERIVED, COUNTRY_PACK_DERIVED ou PROVIDER_RETURNED est résolu par la couche indiquée.

4OBLIGATOIRE

Construire le mapping

Dans Mapping Studio, collez un exemple JSON, reliez chaque chemin source au champ d2f.cbm.v2 correspondant et choisissez la transformation. Corrigez toutes les erreurs, contrôlez l’aperçu et la lignée, puis enregistrez une version DRAFT avec la clé API et le Connection ID.

5OBLIGATOIRE

Tester le routage en sandbox

Dans Sandbox, saisissez la clé API et le Connection ID. Choisissez un scénario domestique ou cross-border et lancez la simulation. D2F associe automatiquement provider.d2f.sandbox : aucune vraie Plateforme Agréée ni aucun identifiant opérateur n’est nécessaire. Vérifiez les pays, les jambes d’exécution, le Country Pack, le fournisseur ou réseau choisi et chaque phase de validation.

6OBLIGATOIRE

Tester le contrat API

Dans API Explorer, commencez par GET /capabilities. Testez ensuite GET /organizations et GET /mappings. Pour un flux complet, envoyez POST /transactions avec un externalId stable et un Idempotency-Key unique. La console affiche le statut, le request ID et le correlation ID.

7OBLIGATOIRE

Diagnostiquer et conserver les preuves

Copiez le transaction ID retourné et ouvrez Diagnostics. Saisissez la clé API, le Connection ID et le transaction ID. Contrôlez le plan d’exécution, la phase bloquante éventuelle, les versions utilisées et la chaîne de preuves SHA-256.

8OBLIGATOIRE

Passer en production

Ne passez le mapping à PRODUCTION qu’après validation de la sandbox, configuration du connecteur qualifié et revue des preuves. Conservez la version précédente pour le rollback et utilisez une clé dédiée à la production.

Les trois informations à ne pas confondre

CLÉ APIAuthentifie votre client technique. Elle est secrète et affichée une seule fois.

CONNECTION IDSélectionne l’entreprise cliente raccordée. Il est envoyé dans X-D2F-Connection-Id.

TRANSACTION IDIdentifie une transaction acceptée. Il sert au suivi, au diagnostic et aux preuves.

Checklist avant production

✓ Clé dédiée active avec les scopes nécessaires
✓ Connection ID de la bonne entreprise
✓ Mapping versionné sans champ CBM inconnu
✓ Simulation sandbox conforme
✓ Country Pack et connecteur qualifiés
✓ Idempotency-Key gérée par le système source
✓ Diagnostic sans blocage
✓ Preuves et rollback conservés

Parcours contributeur Country Pack

Un partenaire agréé utilise le contrat et la gouvernance existants. Il n’ajoute ni moteur national, ni étape de readiness, ni règle directement dans Business Suite.

Enregistrer la juridiction dans le registre de programme sans la qualifier.
Créer une version de manifeste dans l’espace Country Packs et déclarer capacités, applicabilité, sources officielles, règles, mappings et références de schémas.
Fournir l’adaptateur conforme au contrat Country Pack pour le mapping CBM et la normalisation des réponses, puis déclarer séparément tout connecteur optionnel.
Exécuter les tests positifs/négatifs, scénarios Sandbox et contrôles de qualification, puis joindre les preuves et la documentation.
Soumettre les revues réglementaire, technique et sécurité D2F. Le contributeur ne peut ni s’auto-qualifier ni publier automatiquement.
Publier les métadonnées Marketplace uniquement après réussite des contrôles; l’activation du tenant et la qualification du connecteur restent séparées.

Le parcours ne modifie pas deriveTransactionReadiness, le CBM, l’orchestration des étapes, le moteur réglementaire Business Suite ni l’orchestration Platform.

En cas d’échec

Ne recommencez pas au hasard. Relevez le statut HTTP, le request ID, le correlation ID et le transaction ID, puis ouvrez Diagnostics. Une erreur de scope nécessite une nouvelle clé ; une erreur de Connection ID concerne le raccordement de l’entreprise ; une validation CBM concerne le payload ou le mapping.