Ligne de commande

ophelix accompagne une intégration en mode test, depuis le terminal. Il reçoit les webhooks sur votre poste sans tunnel ni port ouvert, déclenche les scénarios du simulateur et affiche vos requêtes à mesure qu’elles arrivent. Il ne travaille qu’en mode test : une clé de production est refusée.

L’outil est en préversion, comme les bibliothèques.

Installer

Un binaire autonome par système, ou le paquet npm pour Node 20.3 et plus :

npm install --global @ophelix/cli
ophelix --version

Je veux…

Se connecter

ophelix login

Le terminal affiche un code de huit caractères et ouvre le tableau de bord, en mode test. Vérifiez que le code est le même, puis autorisez. Il faut un rôle qui peut créer une clé : propriétaire, administrateur ou développeur.

Le terminal reçoit alors une clé restreinte de test, rk_test_…, nommée « Ligne de commande · » suivi du nom de la machine. Elle expire au bout de 90 jours, et se révoque comme les autres dans Développeurs › Clés API. Une demande que personne n’autorise expire au bout de dix minutes.

Sans navigateur sur la machine, ouvrez vous-même l’adresse affichée, ou passez une clé de test existante :

ophelix login --api-key sk_test_…

La connexion se garde dans ~/.config/ophelix/config.json, en droits 600, jamais dans un dépôt. XDG_CONFIG_HOME ou OPHELIX_CONFIG_DIR la déplacent. ophelix logout l’oublie, et révoque la clé si le terminal l’a reçue du tableau de bord. Une clé collée reste en vie : elle peut servir ailleurs.

Recevoir les webhooks

ophelix listen --forward-to localhost:3000/hooks

Prêt. Secret de signature du relais : whsec_…
14:02:11  --> claim.paid [evt_…]
14:02:11  <-- [200] POST http://localhost:3000/hooks [evt_…] 12 ms

L’outil relève les événements du mode test de votre organisation toutes les deux secondes, et les rejoue vers votre serveur : le corps exact d’une livraison, Content-Type: application/json et l’en-tête Ophelix-Signature. Votre serveur les vérifie comme une vraie livraison, avec le secret du relais : voir Vérifier la signature.

Le secret du relais n’est celui d’aucun point de terminaison. Il suit la clé du terminal : il reste le même d’une session à l’autre, et change si la clé change. Gardez-le à part dans la configuration locale de votre serveur, ophelix listen --print-secret le donne seul.

Le relais commence quand il s’ouvre : il ne rejoue pas les événements passés. Sans --forward-to, il affiche les événements sans les envoyer.

Déclencher un scénario

ophelix trigger claim.paid

Déclenchement de claim.paid…
  POST /v1/practitioners  prac_… (cps_doctor)
  POST /v1/coverages  cov_… (vitale_ok)
  POST /v1/claims  clm_… (draft)
  …
  POST /v1/test-helpers/claims/clm_…/returns  clm_… (payment → paid)

Un déclenchement passe par les routes publiques du mode test, comme votre intégration le ferait : il lit une CPS et une carte Vitale de test, ouvre une facture, la valide, la signe et simule les retours. Les objets créés restent dans le tableau de bord, et ophelix listen relaie chacun de leurs événements.

--vitale et --cps choisissent la carte de test, parmi celles de Cartes et scénarios de test :

ophelix trigger claim.ready --vitale vitale_exempted
ophelix trigger coverage.retrieved --vitale vitale_rights_closed

Un scénario que la validation refuse, comme vitale_rights_closed pour une facture, s’arrête à l’étape refusée et dit pourquoi, avec l’identifiant de la requête.

Suivre les requêtes

ophelix logs tail --status 4xx

14:05:42  400  POST /v1/claims parameter_missing  [req_…] 18 ms

Chaque requête du mode test de l’organisation s’affiche à son arrivée, celles de l’outil comme celles de votre intégration : heure, code, méthode, chemin, code d’erreur, identifiant et durée. Le corps ne s’affiche pas : GET /v1/requests/{id} le donne. --status prend un code (404) ou une famille (5xx), --method une méthode.

Le fil du mode test

listen et logs tail lisent GET /v1/test-helpers/feed. Votre propre outillage peut le lire aussi, avec une clé de test qui a events:read et requests:read :

curl "https://api.ophelix.fr/v1/test-helpers/feed?events_after=evt_…&requests_after=req_…" \
  -H "Authorization: Bearer sk_test_…"

Sans curseur, events et requests sont vides et les curseurs marquent l’instant présent. Ensuite, cent éléments au plus par famille, du plus ancien au plus récent. body est le corps exact d’une livraison, à signer tel quel avec signing_secret. poll_interval dit combien de secondes attendre avant la lecture suivante. Le fil ne s’inscrit pas lui-même dans les requêtes.

Options communes

Événements

L’outil n’émet aucun événement à lui : il relaie ceux de votre organisation, et ses déclenchements produisent ceux du catalogue.

Pièges

• --forward-to ne vise que ce poste : localhost, un nom en .localhost, 127.0.0.1 ou [::1]. Un serveur distant reçoit les webhooks par un point de terminaison.
• Le secret du relais n’est pas celui de vos points de terminaison. Un serveur qui vérifie avec le secret de production rejette les livraisons du relais, et c’est voulu.
• Les points de terminaison de test reçoivent aussi les événements. Le relais s’ajoute aux livraisons, il ne les remplace pas.
• Deux relais ouverts livrent deux fois. Chaque ophelix listen relève le fil pour lui-même : dédoublonnez sur l’id de l’événement, comme pour une vraie livraison.
• Une requête longue peut manquer au suivi en direct : elle s’inscrit à sa fin, et peut passer derrière une requête plus courte commencée après elle. Elle reste dans GET /v1/requests.
• Le relais ne rattrape pas une coupure longue au-delà de ce que le fil garde : les événements restent lisibles par GET /v1/events.
• Une clé expirée ou révoquée arrête l’outil : relancez ophelix login.
• Le code d’une demande de connexion ne sert qu’une fois : un code expiré, déjà autorisé ou refusé répond cli_login_code_invalid.