Bibliothèques PHP et Node

Deux bibliothèques officielles appellent l’API pour vous : chaque ressource a son service, chaque objet son type, chaque erreur sa classe. Elles tirent une clé d’idempotence pour chaque écriture, reprennent un 429 ou un 5xx, parcourent les listes page après page et vérifient la signature des webhooks.

Installer

composer require ophelix/ophelix-php

npm install @ophelix/node

Premier appel

Le client prend votre clé. Une clé sk_test_ travaille sur le simulateur, une clé sk_live_ en production : le client le sait par livemode. Gardez la clé côté serveur, dans une variable d’environnement.

use Ophelix\OphelixClient;
 
$ophelix = new OphelixClient('sk_test_…');
 
$practitioner = $ophelix->practitioners->create(['card' => 'cps_doctor']);
echo $practitioner->id, ' ', $practitioner->status, PHP_EOL;

import { Ophelix } from '@ophelix/node'
 
const ophelix = new Ophelix('sk_test_…')
 
const practitioner = await ophelix.practitioners.create({ card: 'cps_doctor' })
console.log(practitioner.id, practitioner.status)

Chaque ressource de la référence a son service, nommé comme elle : claims, coverages, webhookEndpoints… Ses méthodes suivent ses routes : create, retrieve, update, delete, all en PHP et list en Node, puis les actions comme finalize ou secure. Les routes imbriquées suivent leur chemin : claims.lines.create, testHelpers.claims.simulateReturn.

Le guide de démarrage mène une facture jusqu’au paiement avec chaque bibliothèque.

Réglages

Chaque méthode prend en dernier argument des options d’appel : la clé d’idempotence, la version, le nombre de reprises.

Objets

Un objet se lit par ses champs, tels que l’API les nomme. Un champ lié rend un identifiant, ou l’objet avec expand. Un objet passé en paramètre part par son identifiant, déplié ou non.

$claim = $ophelix->claims->retrieve('clm_…', ['expand' => ['patient']]);
 
echo $claim->patient->quality, PHP_EOL;
echo $claim->getLastResponse()?->requestId, PHP_EOL;

const claim = await ophelix.claims.retrieve('clm_…', { expand: ['patient'] })
 
if (typeof claim.patient === 'object') console.log(claim.patient.quality)
console.log(claim.lastResponse.requestId)

requestId est le Request-Id de la réponse : retrouvez l’appel dans Développeurs › Requêtes.

Listes

Une liste rend sa première page. Parcourue, elle demande la suivante quand la précédente est lue, en gardant vos filtres.

$page = $ophelix->events->all(['object' => 'clm_…', 'limit' => 2]);
echo count($page->data), $page->has_more ? ' et plus' : '', PHP_EOL;
 
foreach ($ophelix->events->all(['object' => 'clm_…', 'limit' => 2]) as $event) {
    echo $event->type, PHP_EOL;
}

const page = await ophelix.events.list({ object: 'clm_…', limit: 2 })
console.log(page.data.length, page.has_more ? 'et plus' : '')
 
for await (const event of ophelix.events.list({ object: 'clm_…', limit: 2 })) {
  console.log(event.type)
}

Idempotence et reprises

Chaque écriture part avec une clé Idempotency-Key tirée pour elle, gardée d’une reprise à l’autre. Une réponse 429, 5xx ou idempotency_key_in_progress, ou une coupure du réseau, se rejoue après un délai qui double, ou après Retry-After quand l’API le donne. L’écriture ne se double jamais. Passez votre propre clé pour rejouer un appel d’un processus à l’autre.

Erreurs

Une erreur de l’API lève, ou rejette, la classe de son type. Elle porte le code, le paramètre fautif, le lien vers sa documentation et l’identifiant de la requête.

use Ophelix\Exception\InvalidRequestException;
 
try {
    $ophelix->claims->retrieve('clm_inconnu');
} catch (InvalidRequestException $exception) {
    echo $exception->getErrorCode(), ' ', $exception->getRequestId(), PHP_EOL;
}

import { OphelixInvalidRequestError } from '@ophelix/node'
 
try {
  await ophelix.claims.retrieve('clm_inconnu')
} catch (error) {
  if (!(error instanceof OphelixInvalidRequestError)) throw error
  console.log(error.code, error.requestId)
}

Webhooks

Webhook::constructEvent() en PHP et Ophelix.webhooks.constructEvent() en Node vérifient la signature Ophelix-Signature sur le corps brut, refusent une livraison de plus de cinq minutes et rendent l’événement. Voir Webhooks.

Versions

Les bibliothèques suivent le versionnage sémantique. Chacune envoie la version datée de l’API avec laquelle elle est publiée : une réponse n’y perd ni ne renomme jamais un champ. Une version plus récente de l’API se choisit par le réglage de version, appel par appel ou pour tout le client.