Changelog SGRDV — release 1.0.4

Date de publication : 8 mai 2026

Légende : 🔴 = rupture sur contrat de production (experimental = false) · 🟠 = rupture sur contrat en validation (experimental = true) · 🟢 = ajout rétrocompatible

1. Versionnement et statut

1.1 Bump 1.0.3 → 1.0.4 🟠

Cette release applique un bump PATCH portant deux blocs structurants :

1. La migration des notifications de cycle de vie d'un verrou de la surface api-source vers le pattern FHIR Messaging R4. Trois OperationDefinition distinctes ($lock, $extend-lock, $release-lock) côté source sont remplacées par une opération système unique $process-message, l'événement métier étant discriminé par MessageHeader.eventCoding.
2. La refonte du payload des opérations $extend-lock et $release-lock côté api-sgrdv. La ressource Appointment rématérialisée est remplacée par deux paramètres en logical references (appointmentReference 1..1 + slotReference 1..*), alignant le payload entrant sur le pattern MessageHeader.focus du canal Messaging et éliminant les attributs non consommés.

L'opération $lock côté api-sgrdv reste inchangée : elle continue de recevoir une liste ordonnée d'Appointment candidates avec leurs slots embarqués (besoin métier de SGRDV pour décider quel candidat verrouiller).

Cette release introduit également, en ajouts rétrocompatibles 🟢, deux nouveaux contrats publiés à l'état status = draft, experimental = true :

• une nouvelle opération $book (réservation de rendez-vous) sur les deux surfaces — voir §4 ;
• un nouveau endpoint de recherche GET [base]/Organization (liste des cliniques desservies par un DMÉ) sur la surface api-source — voir §8.

Tous les artefacts versionnés (config IG, OperationDefinition, CapabilityStatement) sont alignés sur la version 1.0.4. L'attribut experimental = true est conservé sur tous les artefacts.

Le bump est conforme à la politique de versionnement publiée en 1.0.2 : ruptures sur des artefacts experimental = true → bump PATCH.

2. Migration vers FHIR Messaging — surface api-source 🟠

S'applique uniquement à la surface api-source (SGRDV → DMÉ/SIP-C).

2.1 Opération système unique $process-message 🟠

2.2 Nouveaux artefacts FSH 🟢 (par rapport à l'absence d'équivalent en 1.0.3)

Trois instances d'exemple (une par événement) accompagnent le profil Bundle : SGRDVSourceProcessMessageExampleCreate, SGRDVSourceProcessMessageExampleExtend, SGRDVSourceProcessMessageExampleRelease.

2.3 Artefacts retirés 🟠

Les profils communs SGRDVBaseLockPayloadParameters et SGRDVBaseLockCandidateAppointment restent définis : ils continuent de typer le payload de l'opération $lock côté api-sgrdv. Les opérations $extend-lock et $release-lock côté api-sgrdv migrent quant à elles vers un nouveau parent neutre SGRDVBaseLockReferenceParameters (cf. §3 ci-dessous).

2.4 Ressources concernées portées en logical reference dans MessageHeader.focus 🟠

L'Appointment et le ou les Slot concernés par l'événement de verrou ne sont pas matérialisés dans le Bundle de notification — le DMÉ étant leur autorité d'origine, les rematérialiser serait redondant et créerait un risque de désynchronisation. Ils sont transmis en logical references dans MessageHeader.focus, discriminées par Reference.type :

Les codes de type d'identifiant (IdDispoDME, IdSlotDME) du CodeSystem sgrdv-identifier-type et les NamingSystems DMÉ existent depuis 1.0.0 — aucun nouvel artefact d'identification n'est introduit. Toutes les Reference interdisent Reference.reference (0..0) conformément au pattern logical reference déjà appliqué dans Provenance.agent, Appointment.slot, etc.

2.5 Contenu effectif du Bundle de notification 🟠

Bundle.type est fixé à #message, Bundle.timestamp est 1..1. manualSliceOrdering: true étant activé sur le projet, l'ordre de définition des slices est respecté par SUSHI — le MessageHeader est garanti en première position du Bundle.

2.6 Identification de l'émetteur, du destinataire et des canaux

Note FHIR R4 : MessageHeader ne possède pas de champ timestamp natif en R4 — le moment de l'événement est porté par Bundle.timestamp (1..1 sur le profil SGRDVSourceLockNotificationBundle).

2.7 Corrélation : X-Correlation-Id HTTP et MessageHeader.id FHIR — complémentaires

Règle générale du projet : le X-Correlation-Id est un mécanisme de transport HTTP et n'est jamais représenté dans le payload FHIR. Cette règle reste en vigueur et n'est pas relâchée.

Le MessageHeader.id requis sur ce flux n'est pas une copie du X-Correlation-Id, mais un identifiant FHIR-natif distinct désignant un message particulier :

La documentation d'accueil du IG est ajustée en conséquence pour expliciter cette distinction.

3. Refonte du payload $extend-lock et $release-lock — surface api-sgrdv 🟠

S'applique uniquement à la surface api-sgrdv (Portail → SGRDV).

3.1 Logical references à la place de la ressource Appointment 🟠

Le payload entrant de $extend-lock et $release-lock ne ré-embarque plus la ressource Appointment complète : il transmet désormais la disponibilité concernée et ses slots en logical references séparées (Reference.identifier peuplé, Reference.reference interdit), conformément au pattern déjà appliqué dans MessageHeader.focus (cf. §2) et dans tous les autres Reference SGRDV.

$lock (api-sgrdv) n'est pas modifié : il continue de recevoir une liste ordonnée de candidates avec leurs slots embarqués — SGRDV doit, à ce moment-là, connaître l'association appointment ↔ slots pour décider quel candidat verrouiller.

3.2 Nouveau profil parent neutre SGRDVBaseLockReferenceParameters 🟢

Les profils enfants SGRDVExtendLockRequestParameters et SGRDVReleaseLockRequestParameters sont refactorés pour hériter de ce nouveau parent (au lieu de SGRDVBaseLockPayloadParameters).

3.3 Justification SGRDV stateless

SGRDV n'a pas conservé l'association lock ↔ appointment ↔ slots posée lors du $lock initial. Le portail doit donc re-fournir ces identifiants à chaque appel $extend-lock / $release-lock afin que SGRDV puisse propager l'événement au DMÉ aval via la notification FHIR Messaging (cf. §2). Les attributs status, participants, etc. de la ressource Appointment rématérialisée n'étaient pas consommés — leur retrait simplifie le payload sans perte fonctionnelle.

4. Nouvelle opération $book (draft, expérimental) — surfaces api-sgrdv et api-source 🟢

S'applique aux deux surfaces (Portail → SGRDV et SGRDV → DMÉ/SIP-C). Opération introduite à l'état status = draft, experimental = true et déclarée dans les CapabilityStatement des deux surfaces (cf. §5.1) afin de la rendre visible aux partenaires pour anticipation et retour.

Conforme à la Spécification API — Réserver RV v0.1 (2026-05-05). L'opération réserve un rendez-vous sur une disponibilité préalablement verrouillée via $lock. Création uniquement — pas de modification ni d'annulation.

4.1 Diagramme d'enchaînement

Si SGRDV ne retrouve pas le verrou attaché au lockIdentifier (verrou expiré ou inconnu), la demande est refusée et n'est pas transmise au DMÉ — le Bundle de réponse contient alors un OperationOutcome seul.

4.2 Nouveaux artefacts FSH 🟢

Artefacts communs aux deux surfaces

Artefacts de la surface api-sgrdv (Portail → SGRDV)

Artefacts de la surface api-source (SGRDV → DMÉ/SIP-C)

4.3 Paramètres d'entrée

4.4 Modèle de Provenance multi-agents

SGRDVBaseBookRequestProvenance hérite directement de Provenance (pas de SGRDVBaseRequestProvenance) car la cardinalité de agent passe de 1..1 à 1..*. Le slicing de agent est discriminé par who.type :

Provenance.location (0..1) porte la région socio-sanitaire du Québec en logical reference (Reference.type = "Location", identifier.system = $ns-region-admin, identifier.type.coding.code = #regionAdmin, identifier.value = code de région 01 à 18 ∈ SGRDVRegionAdministrativeCS). Règle métier : la région DOIT être fournie lorsque Device.property[tuilePortail].valueCode vaut 811, 911 ou MAGROSSESSE ; elle reste optionnelle pour les autres tuiles.

4.5 Bundle de réponse — disponibilité réservée en logical reference

Bundle.type = #collection, slicing entry par type de ressource :

En cas de refus (verrou expiré ou refus du DMÉ), le Bundle ne contient que des entry[outcome].

L'Appointment réservé n'est PAS rématérialisé dans le Bundle de réponse, et les ressources contextuelles (Practitioner, PractitionerRole, Location, Organization, Encounter, Patient enrichi) ne sont pas non plus retournées — le portail dispose déjà de l'ensemble de cette information matérialisée lors de l'appel $find initial. Seule la confirmation de la réservation (identifiant logique de la disponibilité, statut implicite #booked documenté par le profil cible SGRDVBaseBookResponseAppointment) circule dans la réponse. Pattern aligné sur la réponse $lock (SGRDVLockResultParameters.parameter[lockedAppointment]).

4.6 Notes de conception

• Réponse en logical reference, pas de rematérialisation — l'Appointment réservé et les ressources contextuelles (Practitioner, Location, Encounter, Patient enrichi) ne sont pas rematérialisés dans le Bundle de réponse. Le portail dispose déjà de cette information matérialisée via l'appel $find initial — la rematérialiser introduirait redondance et risque de désynchronisation entre le DMÉ (autorité d'origine) et la réponse SGRDV. Seule la confirmation de la réservation (identifiant logique de la disponibilité) circule dans la réponse. Pattern symétrique de $lock (SGRDVLockResultParameters.parameter[lockedAppointment]).
• Device.property est valide en FHIR R4 (cardinalité 0..*, type BackboneElement avec type + valueCode/valueQuantity). Le code tuile REO est porté par Device.property[tuilePortail].valueCode ; aucune extension n'est introduite.
• Le lieu Clinique d'origine est porté par Device.owner (logical reference Organization) — pattern aligné sur l'usage SGRDV existant (le Device n'est jamais matérialisé pour les agents de SGRDVBaseRequestProvenance, mais il l'est ici en contained car il porte du contexte applicatif additionnel).
• professionnelREO typé RelatedPerson (pas Practitioner) : la spec décrit un agent administratif de réorientation, pas un soignant ; RelatedPerson reste le type FHIR R4 le moins inapproprié dans la liste autorisée pour Provenance.agent.who. Le patient requis est porté en logical reference NAM.
• Le lockIdentifier demeure un secret connu du seul portail appelant — strictement absent côté api-source (0..0).
• orientationId est typé integer ; il est relayé tel quel par SGRDV au DMÉ pour la traçabilité Vitrai.

4.7 Exemples publiés

Plusieurs instances d'exemple accompagnent les profils :

• api-sgrdv : SGRDVBookExamplePatient, SGRDVBookExampleRequestProvenance, SGRDVBookExampleRequest, SGRDVBookExampleResultParametersSuccess, SGRDVBookExampleResponseSuccess (Bundle contenant la logical reference de l'Appointment réservé), SGRDVBookExampleResponseLockExpired
• api-source : symétriques avec préfixe SGRDVSourceBook* (incluant un Bundle de refus DMÉ SGRDVSourceBookExampleResponseRefused)

5. CapabilityStatement — refactorisation surface source + ajout $book sur les deux surfaces 🟠

5.1 Restructuration SGRDVCapabilityStatementSource

Le CapabilityStatement SGRDVCapabilityStatementSource est restructuré pour refléter le nouveau modèle de surface :

5.2 Ajout de $book à SGRDVCapabilityStatement (api-sgrdv)

Le CapabilityStatement SGRDVCapabilityStatement est étendu pour déclarer la nouvelle opération $book :

La documentation rest[0] mentionne explicitement que le contrat $book est actuellement en status = draft et susceptible d'évoluer avant stabilisation.

5.3 Bump de version sur tous les artefacts versionnés

6. Documentation publiée enrichie 🟢

La page d'accueil du guide d'implémentation inclut désormais une section « Notifications de verrou — canal FHIR Messaging (api-source) » décrivant le flux et ses contraintes. La note d'introduction sur le X-Correlation-Id est nuancée pour expliciter sa distinction avec MessageHeader.id (cf. §2.7).

7. Recommandations de migration pour les partenaires

7.1 Si vous êtes un portail (api-sgrdv)

Action requise sur $extend-lock et $release-lock (cf. §3). L'opération $lock reste inchangée.

À l'appel $extend-lock ou $release-lock, fournir désormais :

1. parameter[appointmentReference] (1..1) — Reference.identifier portant l'identifiant local DMÉ de la disponibilité (type.coding.code = #IdDispoDME, system = NamingSystem du DMÉ via alias $ns-<x>, value = identifiant local). Reference.type fixé à "Appointment". Ne PAS peupler Reference.reference.
2. parameter[slotReference] (1..*) — un Reference par slot, mêmes contraintes (type = "Slot", identifier.type.coding.code = #IdSlotDME).
3. parameter[lockIdentifier] — inchangé (le secret reçu lors du $lock initial).
4. parameter[lockRequestedDuration] (extend uniquement) — inchangé.
5. parameter[provenance] — inchangé.

Ne plus envoyer de ressource Appointment rématérialisée dans parameter[appointment] (slice supprimée). Les valeurs des identifiants (disponibilité + slots) sont les mêmes que celles reçues dans le Bundle de réponse $lock initial — il suffit de les mémoriser côté portail entre $lock et l'appel $extend-lock / $release-lock.

Mettre à jour la référence de version du IG à 1.0.4 lors de votre prochaine intégration.

7.2 Si vous êtes un DMÉ/SIP-C (api-source)

Côté serveur, vous devez :

1. Exposer un nouvel endpoint POST [base]/$process-message (niveau système, pas rattaché à Appointment). Conserver l'authentification existante.

2. Décommissionner les 3 endpoints précédents :

   • POST [base]/Appointment/$lock
   • POST [base]/Appointment/$extend-lock
   • POST [base]/Appointment/$release-lock

3. Implémenter la dispatch sur MessageHeader.eventCoding :

   • system = http://sante.quebec/fhir/CodeSystem/sgrdv-lock-events, code parmi lock-create / lock-extend / lock-release.
   • Tout autre code doit retourner HTTP 400 + OperationOutcome.

4. Résoudre les ressources concernées localement : l'Appointment et les Slot ne sont plus poussés dans le payload. Ils sont transmis en logical reference dans MessageHeader.focus[appointment].identifier.value (avec system = votre NamingSystem DMÉ) et MessageHeader.focus[slot][].identifier.value (idem). Vous devez les retrouver dans votre propre référentiel.

5. Lire l'heure de fin du verrou depuis MessageHeader.extension[lock-end-time].valueDateTime (et non plus depuis un Parameters.parameter[lock-endTime]).

6. Lire la Provenance depuis la deuxième entry du Bundle (profil SGRDVBaseRequestProvenance inchangé depuis 1.0.3).

7. Conserver les comportements existants :

   • HTTP 204 en cas de succès, HTTP 4xx/5xx + OperationOutcome en cas d'erreur.
   • Retry avec backoff exponentiel sur 5xx (à la charge de SGRDV) — pas de retry sur 4xx.
   • Journalisation du X-Correlation-Id HTTP — comportement strictement identique à 1.0.3.
   • Journalisation supplémentaire recommandée du MessageHeader.id pour faciliter le rapprochement des messages individuels.

7.3 Si vous validez vos instances avec un validateur FHIR

Les exemples publiés pour le canal $process-message (3 messages, un par événement lock-create / lock-extend / lock-release) sont conformes aux profils. Aucun warning de validation attendu au-delà de ceux déjà documentés en 1.0.3 (notamment ident-1 sur agent.who.identifier sans value).

7.4 Si vous voulez anticiper $book

Aucune action n'est requise en 1.0.4 — les nouveaux artefacts $book sont publiés en status = draft, experimental = true. La stabilisation de l'opération est attendue dans une release ultérieure ; le contrat peut évoluer d'ici là. Les partenaires intéressés peuvent consulter les CapabilityStatement (SGRDVCapabilityStatement côté portail, SGRDVCapabilityStatementSource côté DMÉ), étudier les profils publiés (§4) et formuler des retours.

7.5 Si vous voulez anticiper GET /Organization (DMÉ)

Aucune action n'est requise en 1.0.4 — le contrat est publié en status = draft, experimental = true. Les DMÉ peuvent consulter SGRDVCapabilityStatementSource (déclaration de l'interaction search-type sur la ressource Organization), étudier les profils publiés (§8) et formuler des retours d'ici la stabilisation.

7.6 Toutes intégrations confondues

1. Mettre à jour les références internes (validation, documentation, dépendances de paquet) à la version 1.0.4 des artefacts. L'attribut experimental = true est conservé sur tous les artefacts ; le statut des artefacts existants (#active) ne change pas par rapport à 1.0.3. Les nouveaux artefacts $book (§4) et GET /Organization (§8) sont introduits en #draft.
2. Conserver la politique de versionnement et de stabilité publiée en 1.0.2 : tant qu'un artefact est experimental = true, ses ruptures n'entraînent qu'un bump PATCH du paquet — c'est ce qui s'applique à cette release.

8. Nouveau endpoint GET [base]/Organization (draft, expérimental) — surface api-source 🟢

S'applique uniquement à la surface api-source (SGRDV → DMÉ/SIP-C). Endpoint introduit à l'état status = draft, experimental = true et déclaré dans SGRDVCapabilityStatementSource (cf. §5) afin de le rendre visible aux partenaires pour anticipation et retour.

Conforme à la Spécification API — Obtenir Cliniques v0.1 (2026-05-05). Le service permet à SGRDV d'obtenir, à fréquence régulière (typiquement nocturne quotidienne), la liste à jour des cliniques publiques de 1ère ligne présentement desservies par chaque DMÉ et susceptibles d'être impliquées dans le processus de prise de RV via les portails VotreSanté et REO. Les cliniques privées sont exclues.

8.1 Interaction FHIR

L'endpoint est modélisé comme une recherche FHIR type-level, pas comme une opération $xxx — aucun OperationDefinition n'est introduit. Le détail du contrat (verbe HTTP, filtrage serveur, structure de réponse, sémantique de indRvPublies, fréquence d'invocation, X-Correlation-Id) est porté par rest[0].resource[Organization].interaction[search-type].documentation du SGRDVCapabilityStatementSource.

8.2 Nouveaux artefacts FSH 🟢

Artefacts communs

Artefacts de la surface api-source

8.3 Structure du Bundle de réponse

Bundle.type est fixé à #searchset, Bundle.total est 1..1 (compte les entries match).

8.4 Profil Organization retourné

Hérite de SGRDVBaseFindOrganization — donc :

• identifier 1..1 : system pointant vers le NamingSystem RAMQ ($ns-ramq), type.coding.code = #CodeEtablissement, value = code d'établissement RAMQ tel que retourné par GRL.
• name 0..1 : nom de la clinique, optionnel — utilisé uniquement pour faciliter la lecture des données de référence.
• type 0..* : libre — non figé par le profil.

Et ajoute :

• extension[indRvPublies] 0..1 : valueBoolean. Si false, le DMÉ signale que la clinique ne publiera jamais de disponibilités pour les portails — SGRDV n'interrogera plus le DMÉ pour cette clinique lors des recherches de disponibilités. Si l'extension est absente, SGRDV applique la valeur par défaut TRUE.

8.5 X-Correlation-Id

Mécanisme HTTP inchangé — règle générale api-source (cf. §2.7) : X-Correlation-Id requis sur tous les appels, journalisé par le DMÉ et retourné en écho, jamais représenté dans le payload FHIR.

8.6 Exemples publiés

Quatre instances d'exemple accompagnent les profils côté api-source :

• SGRDVSourceListClinicsExampleOrganization1 — clinique avec nom et indRvPublies = true
• SGRDVSourceListClinicsExampleOrganization2 — clinique minimale (identifiant RAMQ seul, sans nom, sans extension)
• SGRDVSourceListClinicsExampleOrganization3 — clinique avec indRvPublies = false
• SGRDVSourceListClinicsExampleOutcomeInformation — OperationOutcome informationnel horodatant la liste
• SGRDVSourceListClinicsExampleResponseSuccess — Bundle complet agrégeant les exemples ci-dessus

8.7 Notes de conception

• Recherche FHIR vs opération $xxx — le contrat décrit un GET sans paramètre retournant un Bundle. Une recherche type-level est l'idiome FHIR R4 adapté ; introduire une OperationDefinition aurait été plus lourd sans bénéfice fonctionnel.
• Pas d'enfant SGRDVSourceListClinicsOrganization — le profil Organization retourné ne diffère pas selon la surface ; on réutilise directement SGRDVBaseListClinicsOrganization côté api-source (même pattern que SGRDVBaseFindOrganization, qui n'a pas d'enfant Source).
• Pas de parent Base pour le Bundle de réponse — le contrat n'existe que sur la surface api-source ; introduire un parent commun aurait été spéculatif.
• Filtrage côté serveur (cliniques publiques de 1ère ligne, non privées, présentement desservies) — non exprimé dans le profil FHIR. C'est une règle métier du DMÉ documentée dans la Description du profil et la documentation REST du CapabilityStatement.