Guide développeur PMS

Intégration izyScribe pour logiciels PMS

Connectez votre logiciel de gestion à izyScribe pour initialiser une consultation, ouvrir la fiche cible dans l’interface, suivre le traitement puis récupérer le compte-rendu final.

Base URL de production

https://www.izyscribe.com

L’API échange uniquement en JSON. L’usage recommandé pour un PMS est une authentification par clé API transmise dans le header HTTP.

00Authentification

L’accès est sécurisé par une clé API liée au profil utilisateur izyScribe. Cette clé doit être transmise sur chaque requête.

Header recommandé

Authorization: Bearer <API_KEY>

Obtenir une clé

L’utilisateur peut récupérer ou régénérer sa clé depuis son profil izyScribe. Les endpoints internes /api/profile/api-key existent pour les intégrations web authentifiées.

01Créer une consultation

POST

/api/external/consultsInitialisation de la consultation

Créez une consultation en envoyant un JSON unique. `patientId` ou `patientName` doit être renseigné. Pour pré-remplir les données exploitées dans les templates et exports, utilisez l’objet `patientInfos`.

JSON recommandé

Le PMS peut envoyer un payload minimal ou un payload complet. Les clés inconnues dans `patientInfos` sont conservées, mais ne sont pas interprétées automatiquement par izyScribe. Les clés ci-dessous sont celles exploitées par l’UI, les templates et les exports.

Règle métier : au moins un de `patientId` ou `patientName` est requis.

Paramètre	Type	Description
patientId	Requis string	Identifiant patient dans le PMS. Requis si `patientName` est absent.
patientName	Requis string	Nom affiché du patient dans izyScribe et dans les exports. Requis si `patientId` est absent.
title	Optionnel string	Motif ou titre de consultation.
transcript	Optionnel string	Transcription initiale si déjà disponible côté PMS.
promptLabel	Optionnel string	Libellé de preset ou étiquette interne associée à la consultation.
aiPrompt	Optionnel string	Consignes spécifiques pour l’IA.
context	Optionnel string	Contexte clinique libre, résumé PMS, antécédents, motif détaillé, ou consignes de cadrage.
outputFormat	Optionnel text \| json	Format de sortie interne souhaité. Valeurs acceptées : `text` ou `json`. Défaut : `text`.
patientInfos	Optionnel object	Objet JSON structuré contenant les données propriétaire, patient, animal, structure et praticien.

Catalogue des champs `patientInfos`

Chaque bloc ci-dessous peut être renseigné partiellement. Les dates sont idéalement au format `YYYY-MM-DD`.

patientInfos.ownerCoordonnées du propriétaire ou titulaire de l’animal.

Paramètre	Type	Description
title	string	Civilité.
firstName	string	Prénom.
lastName	string	Nom.
address	string	Adresse postale.
postalCode	string	Code postal.
city	string	Ville.
phone	string	Téléphone.
email	string	Email.

patientInfos.patientInformations du patient humain si votre workflow en utilise.

Paramètre	Type	Description
title	string	Civilité.
firstName	string	Prénom.
lastName	string	Nom.
birthDate	string	Date de naissance, format recommandé : `YYYY-MM-DD`.
sex	string	Sexe.
address	string	Adresse postale.
postalCode	string	Code postal.
city	string	Ville.
phone	string	Téléphone.
email	string	Email.
weight	number	Poids.
height	number	Taille.

patientInfos.animalInformations vétérinaires principales affichées dans izyScribe.

Paramètre	Type	Description
name	string	Nom de l’animal.
species	string	Espèce.
breed	string	Race.
sex	string	Sexe.
birthDate	string	Date de naissance, format recommandé : `YYYY-MM-DD`.
weight	number	Poids.
height	number	Taille.
color	string	Couleur.
microchip	string	Numéro de puce ou identifiant équivalent.

patientInfos.structureCoordonnées de la clinique, du cabinet ou de la structure émettrice.

Paramètre	Type	Description
name	string	Nom de la structure.
address	string	Adresse postale.
postalCode	string	Code postal.
city	string	Ville.
phone	string	Téléphone.
email	string	Email.
vatNumber	string	Numéro de TVA.
siret	string	Numéro SIRET.

patientInfos.doctorInformations du praticien à afficher dans les exports.

Paramètre	Type	Description
title	string	Civilité.
firstName	string	Prénom.
lastName	string	Nom.
displayName	string	Nom affiché complet.
ordinalNumber	string	Numéro ordinal ou licence.
phone	string	Téléphone.
email	string	Email.

Exemple cURL

curl -X POST "https://izyscribe.izyvet.com/api/external/consults" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Otite externe",
    "patientId": "12345",
    "patientName": "Rex",
    "context": "Otalgie gauche depuis 3 jours, antécédent d otites récidivantes.",
    "promptLabel": "Compte-rendu standard",
    "aiPrompt": "Rédiger un compte-rendu concis avec plan de suivi.",
    "outputFormat": "text",
    "patientInfos": {
      "owner": {
        "firstName": "Jean",
        "lastName": "Dupont",
        "phone": "0600000000",
        "email": "jean.dupont@example.com"
      },
      "animal": {
        "name": "Rex",
        "species": "Chien",
        "breed": "Labrador",
        "sex": "M",
        "birthDate": "2020-06-15",
        "weight": 28.4,
        "microchip": "250269123456789"
      },
      "structure": {
        "name": "Clinique Véto Centrale",
        "phone": "0102030405"
      },
      "doctor": {
        "displayName": "Dr Alice Martin",
        "ordinalNumber": "12345"
      }
    }
  }'

Réponse type

{
  "result": "success",
  "data": {
  "id": "63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "title": "Otite externe",
  "patientId": "12345",
  "patientName": "Rex",
  "createdAt": "2026-04-28T08:02:24.975Z",
  "status": "draft",
  "transcriptionStatus": "idle",
  "reportAvailable": false,
  "importStatus": "idle",
  "importRequestedAt": null,
  "importedAt": null,
  "openUrl": "https://izyscribe.izyvet.com/dashboard?consultId=63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "statusUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "reportUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report",
  "reportPdfUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report/pdf"
  }
}

Note d’implémentation

L’`openUrl` ouvre directement la consultation cible dans izyScribe. Si l’utilisateur n’est pas connecté, izyScribe demande l’authentification puis revient automatiquement sur cette consultation.

02Lister les consultations

GET

/api/external/consultsListe légère pour la file PMS

Cet endpoint renvoie par défaut un tableau léger dans `data`, pensé pour la file d’import PMS. Le détail complet reste disponible via `GET /api/external/consults/:id`.

Query params utiles

importStatus : `idle`, `to_retrieve`, `retrieved`.
reportAvailable : `true`, `false`, `1`, `0`.
view=full : retourne le payload détaillé dans la liste.

Lister les consultations

Utilisez `GET /api/external/consults` pour récupérer un tableau léger dans `data`. Le PMS peut ensuite lire le détail d’une consultation via son `id`, puis récupérer le compte-rendu via `/report` ou le PDF via `/report/pdf`. Vous pouvez filtrer avec `?importStatus=to_retrieve` pour ne sortir que les consultations à importer.

Optionnel : ajoutez `?view=full` si vous voulez retrouver le payload détaillé dans la liste.

curl "https://izyscribe.izyvet.com/api/external/consults?importStatus=to_retrieve" \
  -H "Authorization: Bearer <API_KEY>"

Réponse type

{
  "result": "success",
  "data": [
    {
      "id": "63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
      "title": "Otite externe",
      "patientId": "12345",
      "patientName": "Rex",
      "createdAt": "2026-04-28T08:02:24.975Z",
      "status": "processing",
      "importStatus": "to_retrieve",
      "importRequestedAt": "2026-04-28T08:15:00.000Z",
      "importedAt": null,
      "reportAvailable": false,
      "statusUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
      "reportUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report",
      "reportPdfUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report/pdf"
    }
  ]
}

03Vérifier le statut

GET

/api/external/consults/:idPolling de suivi

draft

Consultation créée, en attente d’action utilisateur.

processing

Upload audio, transcription ou traitement en cours.

completed

Le compte-rendu final est disponible.

failed

La transcription ou le traitement a échoué.

Réponse type

{
  "result": "success",
  "data": {
  "id": "63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "title": "Otite externe",
  "patientId": "12345",
  "patientName": "Rex",
  "createdAt": "2026-04-28T08:02:24.975Z",
  "status": "processing",
  "transcriptionStatus": "queued",
  "transcriptionStep": "En attente",
  "transcriptionProgress": 25,
  "transcriptionError": null,
  "reportAvailable": false,
  "importStatus": "to_retrieve",
  "importRequestedAt": "2026-04-28T08:15:00.000Z",
  "importedAt": null,
  "reportTextPreview": "",
  "openUrl": "https://izyscribe.izyvet.com/dashboard?consultId=63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "reportUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report",
  "reportPdfUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report/pdf"
  }
}

Suivi d’import PMS

importStatus vaut `idle`, `to_retrieve` ou `retrieved`.
`to_retrieve` signifie qu’izyScribe attend l’import automatique par le PMS.
`retrieved` signifie que le PMS a confirmé la récupération.
importRequestedAt et importedAt donnent les horodatages associés.

04Récupérer le rapport

GET

/api/external/consults/:id/reportRécupération du compte-rendu final

Champs principaux

reportAvailable indique si le rapport est prêt.
reportText contient le texte intégral du compte-rendu.
outputFormat reflète le format de sortie choisi.
reportPdfUrl pointe vers la version PDF.
`/report/pdf?encoding=base64` renvoie une enveloppe JSON avec `pdfBase64`.

État transitoire normal

Si le rapport n’est pas encore prêt, l’endpoint retourne 409 avec `reportAvailable: false`.

Succès

{
  "result": "success",
  "data": {
  "id": "63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "title": "Otite externe",
  "patientId": "12345",
  "patientName": "Rex",
  "status": "completed",
  "reportAvailable": true,
  "reportText": "L animal présente une gêne à l oreille gauche depuis 3 jours...",
  "outputFormat": "text",
  "reportPdfUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report/pdf"
  }
}

Encore en attente

{
  "result": "error",
  "error": {
    "code": "conflict",
    "message": "Report not available yet",
    "details": {
      "id": "63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
      "status": "draft",
      "reportAvailable": false,
      "reportText": null
    }
  }
}

05Confirmer l’import PMS

PATCH

/api/external/consults/:idMise à jour du statut d’import

Le bouton UI 'Valider pour le logiciel externe' positionne `importStatus = to_retrieve`. Une fois l’import réalisé côté PMS, appelez cet endpoint avec `importStatus = retrieved` pour confirmer la récupération automatique.

Corps JSON accepté

importStatus : `idle`, `to_retrieve` ou `retrieved`.
La valeur recommandée côté PMS pour la confirmation est `retrieved`.

Exemple de requête

curl -X PATCH "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "importStatus": "retrieved"
  }'

Réponse type

{
  "result": "success",
  "data": {
  "id": "63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "title": "Otite externe",
  "patientId": "12345",
  "patientName": "Rex",
  "createdAt": "2026-04-28T08:02:24.975Z",
  "status": "completed",
  "transcriptionStatus": "completed",
  "transcriptionStep": "Terminé",
  "transcriptionProgress": 100,
  "transcriptionError": null,
  "reportAvailable": true,
  "importStatus": "retrieved",
  "importRequestedAt": "2026-04-28T08:15:00.000Z",
  "importedAt": "2026-04-28T08:16:42.000Z",
  "reportTextPreview": "L animal présente une gêne à l oreille gauche depuis 3 jours...",
  "openUrl": "https://izyscribe.izyvet.com/dashboard?consultId=63a9a8ca-70a5-4b08-a859-5a0dc1d7f131",
  "reportUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report",
  "reportPdfUrl": "https://izyscribe.izyvet.com/api/external/consults/63a9a8ca-70a5-4b08-a859-5a0dc1d7f131/report/pdf"
  }
}

Codes d’erreur

401 Unauthorized

Clé API absente, invalide ou utilisateur non autorisé.

404 Not found

Identifiant de consultation inconnu pour cet utilisateur.

409 Conflict

Rapport encore indisponible sur l’endpoint /report.

Logique d’intégration recommandée

Initialisation backend-to-backend

Le PMS crée la consultation dès l’ouverture du dossier patient et stocke l’identifiant izyScribe ainsi que openUrl, statusUrl, reportUrl et reportPdfUrl.

Action utilisateur

Le PMS ouvre openUrl. L’utilisateur peut alors enregistrer, importer l’audio ou saisir manuellement, sans ressaisir les informations patient / titre déjà initialisées.

Suivi et récupération

Le PMS peut lister `GET /api/external/consults?importStatus=to_retrieve`, puis lire le détail via `statusUrl` et appeler `reportUrl` ou `reportPdfUrl`. En cas de 409, attendre quelques secondes avant de retenter.

Handshake d’import

Quand l’utilisateur clique sur 'Valider pour le logiciel externe', importStatus passe à `to_retrieve` dans statusUrl. Le PMS importe alors le compte-rendu puis confirme avec PATCH /api/external/consults/:id et `importStatus: retrieved`.