Activer un service pour une organisation

Objectif

Rendre une organisation capable d'émettre ou de recevoir un flux métier (consultation de droits, adjudication, transmission de factures). On enchaîne credential → service → mapping → vérification.

Durée estimée : 10 à 15 minutes • Rôle requis : platform-governor (ou organization-manager)

Avant de commencer

Assurez-vous d'avoir :

• Une organisation déjà inscrite et au statut Actif (voir Inscrire une organisation).
• Les éléments techniques fournis par l'organisation ou par l'équipe d'intégration :
  • l'URL de l'endpoint distant (pour un service sortant) ;
  • les clés d'authentification (API key, client OAuth2, ou clé publique SFTP) ;
  • éventuellement, la règle de mapping si le format diffère du pivot ASACI.

Vue d'ensemble

Voici la chaîne de dépendances à configurer, dans l'ordre :

┌─────────────┐     ┌─────────┐     ┌──────────┐     ┌──────────┐
│ Credential  │ ──▶ │ Service │ ──▶ │ Mapping  │ ──▶ │   Test   │
└─────────────┘     └─────────┘     └──────────┘     └──────────┘
   clés d'accès      URL + timeout   transformation   transmission
                     + circuit br.   des données      de bout en bout

On commence par le credential parce que le service en a besoin. Le mapping est configuré en dernier car il dépend du module activé.

Étape 1 — Ouvrir la fiche de l'organisation

Menu Paramétrages ▸ Organisations, puis cliquez sur la ligne de l'organisation concernée.

Étape 2 — Créer le credential

Onglet Credentials de la fiche.

L'onglet affiche les credentials existants sous forme de cartes, avec trois filtres rapides : Tous, REST, SFTP.

Cliquez sur « Ajouter » (bouton orange, en haut à droite du bloc).

Renseigner le credential

Le formulaire « Configurer credential REST » (ou SFTP) s'adapte au type choisi.

Champ	Commentaire
Label	Nom fonctionnel (ex. AGREGATEUR to CNAM, Clef OAuth MOH, SFTP).
Mode de provisionnement	SELF_PROVIDED : l'organisation fournit ses clés. SYSTEM_PROVIDED : la plateforme génère (usage : REST entrant, SFTP).
Type d'authentification	API_KEY, HTTP_SIGNATURE, OAUTH2_CLIENT_CREDENTIALS, OAUTH2_PLUS_HTTP_SIGNATURE, ou SSH_KEY pour SFTP.

Puis, selon le type, des champs spécifiques apparaissent (Client ID / Client Secret / URL du token endpoint pour OAuth2, apiKey + headerName pour API Key, publicKey + keyId pour HTTP Signature, nom d'utilisateur + clé publique SSH pour SFTP).

Cliquez sur « Configurer ». Le credential apparaît immédiatement comme une nouvelle carte.

Nommez vos credentials proprement

Le libellé est le seul moyen de les reconnaître dans la liste déroulante lors de l'ajout d'un service. Préférez MOH — OAuth sortant plutôt que Clef 1.

Étape 3 — Créer le service

Onglet Services de la fiche.

Cliquez sur le bouton d'ajout dans l'en-tête du tableau Services configurés.

Renseigner le service

Champ	Commentaire
Module	Module d'intégration à activer. Ex. Module Adjudication (mi-adjudication), Module Consultation Droits (mi-consultation-droits), Module Transmission de Données (mi-transmission).
Direction	Entrant (l'organisation reçoit) ou Sortant (l'organisation émet).
Resource Code	Code de la ressource échangée. Ex. claim — Demande adjudication (feuille de soins RO + RC). Liste dépendante du module.
Connecteur	Mode d'échange technique : REST_SYNC, REST_ASYNC, SFTP_OUTBOUND… Les connecteurs disponibles dépendent du module sélectionné.
URL du endpoint	URL cible pour un flux sortant, ou URL d'entrée pour un flux entrant.
Méthode HTTP	POST par défaut (valeurs : GET, POST, PUT, PATCH).
Timeout (ms)	Délai d'attente maximal. Valeur entre 3 000 et 120 000 ms, défaut 30 000.
Retry max	Nombre de ré-essais automatiques en cas d'échec technique. Valeurs 0 à 5, défaut 3.
Activer le Circuit Breaker	Protection automatique en cas de défaillance du service cible. Coché par défaut, à laisser activé.

Options supplémentaires pour un flux sortant

Option	Usage
Activer fallback interne ASACI	En cas d'échec, redirige vers un service de secours interne.
URL fallback	URL du service de secours (requis si l'option est activée).

Associer le credential

La dernière partie du formulaire (au-dessus du bouton Ajouter) propose la liste des credentials créés à l'étape 2. Choisissez celui qui correspond au sens (entrant/sortant) et au type d'authentification exigé par le partenaire.

Cliquez sur « Ajouter ». Le service apparaît immédiatement dans le tableau Services configurés.

Étape 4 — Configurer le mapping

Onglet Mappings de la fiche.

Les mappings sont regroupés par service. Pour le service que vous venez de créer, un bloc vide apparaît. Cliquez sur « Modifier » à droite du service.

Structure de l'éditeur

L'éditeur affiche deux onglets :

• Mapping requête — transformation appliquée à la donnée envoyée au partenaire.
• Mapping réponse — transformation appliquée à la donnée reçue du partenaire.

Chaque mapping est une règle ordonnée composée de :

Champ	Commentaire
Source	Chemin du champ source (ex. numeroCMU).
Cible	Chemin du champ cible (ex. beneficiaryNumber).
Transformation	Règle à appliquer : TRIM, UPPER, LOWER, TRIM_UPPER, DATE_FR_TO_ISO, DATE_ISO_TO_FR, DECIMAL_2, DECIMAL_4, MAP_STATUS_CODE, DEFAULT, REPLACE, JSONATA.
Ressource	Code de la ressource concernée (ex. POPULATION, CDO, INVOICE).
Ordre	Ordre d'exécution (les valeurs inférieures sont appliquées en premier).

Pour les cas simples (renommage, majuscules, format de date), une règle suffit. Pour les cas complexes, utilisez JSONATA avec une expression unique.

Exemple JSONATA — pivot ASACI vers format CNAM

{
  "beneficiaryNumber": numeroCMU,
  "surname": $uppercase(nom),
  "name": $uppercase(prenom),
  "dateOfBirth": dateNaissance,
  "sexDescription": sexe = "M" ? "HOMME" : "FEMME",
  "coverageRate": (coverageTarifAmount / 100) & "%"
}

Cliquez sur « Enregistrer ». Le mapping est immédiatement actif sur les prochaines transmissions.

Étape 5 — Vérifier sur une transmission réelle

1. Demandez à l'organisation émettrice (ou à votre équipe de test) d'envoyer une requête de test.
2. Menu Suivi des activités ▸ Transmissions.
3. Filtrez sur la période Aujourd'hui et cherchez la dernière transmission de type correspondant.
4. Vérifiez :
   • Le statut est SUCCESS (vert).
   • La latence est raisonnable (< 2 000 ms pour un sync).
   • Ouvrez le détail (icône 👁️) pour consulter le Payload request et le Response.

Ne déclenchez pas de requête de test vous-même

Pour les environnements de production, ne lancez jamais de transmission de test sans validation explicite de l'organisation et de l'équipe métier. Une requête parasite peut fausser la facturation ou déclencher des alertes inutiles.

Checklist de fin de parcours

• [ ] Un credential visible dans l'onglet Credentials avec le bon type et mode.
• [ ] Un service visible dans l'onglet Services avec Circuit Breaker activé.
• [ ] Un mapping requête et réponse enregistré (si les formats divergent).
• [ ] Une transmission de test s'affiche avec le statut SUCCESS.

Points d'attention

• L'ordre compte : le service ne peut pas être créé sans un credential compatible (REST ou SFTP), et le mapping suppose le service déjà créé.
• Un credential par usage, pas par organisation : si l'organisation a deux flux (OAuth pour adjudication, API Key pour consultation), créez deux credentials distincts avec des libellés clairs.
• Ajustez les timeouts avec parcimonie : le défaut de 30 s couvre 99 % des cas. Au-delà, préférez un connecteur asynchrone.
• Le mapping est versionné implicitement : chaque modification est enregistrée dans la piste d'audit (partner.mappings_updated).

Et ensuite ?

• Pour changer une clé plus tard sans interruption : Rotation d'un credential.
• Pour diagnostiquer un échec de flux : Diagnostiquer un échec de transmission.