> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt > Use this file to discover all available pages before exploring further. # Enregistrer les audiences adjacentes au PHI > Walkthrough du registre d'audiences adjacentes au PHI : quand désigner une liste ou un segment, comment fonctionne le PUT de remplacement total atomique, comment le precheck de lancement de campagne réagit et comment lire l'audit trail. # Enregistrer les audiences adjacentes au PHI Le registre d'audiences adjacentes au PHI est la liste de votre organisation des listes de contacts et segments dont les membres portent du PHI — par exemple, des patients optés à la diffusion de traitement. La référence [contrôles HIPAA](/compliance/hipaa#phi-adjacent-audience-registry) documente les deux endpoints ; ce guide vous mène pour les exécuter en production : quoi désigner, comment fonctionnent les sémantiques d'écriture, ce qui se passe au lancement de campagne et comment lire l'audit trail. Le registre est **propriété du tenant**. Devotel ne désigne jamais d'audiences en votre nom et ne scope jamais le PHI pour vous — les désignations sont votre attestation, ce sont des contrôles bloqués par BAA que vous opérez, et ils ne prennent effet qu'une fois que HIPAA est dans le périmètre de votre organisation. Si vous n'avez pas encore exécuté le BAA et activé le mode HIPAA, exécutez d'abord la séquence [Onboarding HIPAA](/guides/hipaa-onboarding). ## 1. Quand marquer une audience comme adjacente au PHI La désignation suit la **provenance** : marquez les audiences dont les données sources contiennent du PHI, indépendamment de ce qu'une campagne individuelle envoie. Une audience est adjacente au PHI du fait de là où viennent ses membres — une importation de rappels de rendez-vous de patients, une liste opt-in de diffusion de traitement — pas du fait du copy que vous écrivez cette semaine. C'est pourquoi la désignation vit sur l'audience elle-même et pas sur une campagne : quelle que soit la campagne qui la prend, la désignation voyage avec. Marquez une audience comme adjacente au PHI quand : * Ses membres ont été importés d'un système qui retient du PHI (une exportation EHR, une synchronisation opt-in de portail patient). * La liste ou le segment est filtré ou assemblé sur des critères porteurs de PHI (tags adjacents au diagnostic, cohortes de traitement). * La carte de données de votre officier de compliance enregistre l'audience comme PHI dans le périmètre. Ne désignez pas une audience « au cas où ». Une désignation attache le [gate de lancement BAA](#4-comment-le-precheck-de-lancement-utilise-le-registre) à chaque campagne qui utilise l'audience — désigner des audiences qui ne portent pas de PHI bloque des lancements pour aucune raison de compliance. **Qui peut attester :** les deux endpoints requièrent le rôle `owner` ou `admin` — le même gate que les [endpoints BAA](/compliance/baa). Un `developer` ou `viewer` reçoit `403`. Gardez la décision de désignation avec votre officier de compliance HIPAA ; la plateforme enregistre *qui* a changé le registre à chaque écriture (voir [Audit trail](#5-audit-trail)). ## 2. Choisir des ids de liste vs segment Le registre retient des ids d'audience — chaque entrée est soit un **id de liste de contact** soit un **id de segment**, passé comme string brut. Le precheck de lancement de campagne ne résout que les audiences de type `list` et `segment` contre le registre ; les audiences assemblées par contact (tous les contacts, upload CSV, entrée manuelle) sont évaluées destinataire par destinataire à l'heure d'envoi, donc elles n'ont pas d'id de registre à désigner. Pour redériver l'id pour une désignation : ```bash theme={null} # Listes de contact GET /api/v1/contacts/lists # Segments GET /api/v1/contacts/segments ``` Copiez le champ `id` de la liste ou du segment que vous désignez. Les ids font 1–128 caractères après trim ; tout ce qui est plus long ou vide est rejeté avec `422` à l'écriture. Le registre retient au maximum **500** ids par organisation — un `PUT` en portant plus renvoie `422`. > Désignez l'id de **source**, pas une copie en aval. Si une liste porteure de PHI alimente un segment dérivé, décidez si le segment dérivé contient aussi du PHI et désignez-le explicitement — le precheck vérifie l'id que la campagne référence réellement, rien d'autre. ## 3. Le swap PUT atomique Le registre a **une** opération d'écriture : un `PUT` de remplacement total. Il n'y a pas de `PATCH`, pas de `DELETE` par id — chaque écriture remplace l'ensemble désigné entier en une seule instruction atomique, donc un `GET` concurrent ne voit jamais une mise à jour partiellement appliquée. ```bash theme={null} PUT /api/v1/compliance/hipaa/phi-audiences { "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"] } ``` La réponse renvoie l'ensemble stocké : ```json theme={null} { "data": { "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"], "replaced": true } } ``` Le body est **idempotent** : envoyer le même ensemble complet deux fois produit le même registre stocké et deux lignes d'audit distinctes. Un tableau vide nettoie toute désignation : ```bash theme={null} PUT /api/v1/compliance/hipaa/phi-audiences { "audience_ids": [] } ``` Parce que l'écriture est un swap, chaque client doit suivre **read-modify-write** : `GET` le registre actuel, ajoutez ou enlevez votre id dans le résultat, et `PUT` l'ensemble entier en retour. Ne construisez jamais le body depuis l'état local seul — vous supprimeriez silencieusement des désignations qu'un autre opérateur a ajoutées. Pour lever une désignation, `PUT` le registre sans cet id. Pour re-désigner, `PUT` avec l'id ajouté en retour. Les ids individuels qui survivent à un swap sont inchangés ; seule la participation à l'ensemble compte. ## 4. Comment le precheck de lancement utilise le registre Deux gates protègent le PHI à des points différents, et le registre alimente le premier : 1. **Precheck de lancement (niveau campagne, gate dur).** Avant qu'une campagne ne quitte brouillon/programmée, le precheck résout son id d'audience contre le registre. Un id désigné plus un BAA qui n'est pas `executed` et en terme refuse le lancement avec `422 HIPAA_BAA_REQUIRED` — avant qu'un seul destinataire ne soit inscrit. Si l'état de compliance ne peut être lu, le precheck échoue fermé avec `500 HIPAA_BAA_GATE_DB_FAIL` plutôt que d'admettre silencieusement l'audience. 2. **Gate d'envoi par destinataire (heure de message, inchangé).** Le gate d'envoi existant s'applique toujours à chaque envoi individuel et ne consulte pas le registre — les envois legacy one-off sont gouvernés par lui seul. Un lancement bloqué affleure avec le refus ci-dessous. Le `details.reason` vous dit exactement quel état BAA le dé-bloque : ```json theme={null} { "error": { "code": "HIPAA_BAA_REQUIRED", "status": 422, "message": "The designated PHI-adjacent audience for this campaign requires an executed Business Associate Agreement (BAA) before outbound sends are permitted.", "details": { "reason": "pending", "audience": { "type": "list", "id": "list_9f2c1a" } } } } ``` | `reason` | Ce que cela signifie | Comment dé-bloquer | | ------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------- | | `not_signed` | PHI est attesté dans le périmètre mais aucun BAA n'a jamais été exécuté | Exécuter le BAA — [flux BAA](/compliance/baa) | | `pending` | L'exécution du BAA a commencé mais n'a pas été complétée | Finir l'étape d'exécution (`POST /api/v1/compliance/baa/execute`) | | `expired` | Le BAA exécuté a dépassé son terme d'un an | Ré-exécuter le BAA | Il y a **deux** façons de dé-bloquer, et ce sont des décisions de compliance, pas des décisions de plateforme : * **Résoudre le BAA** — l'exécuter ou le ré-exécuter pour que le gate passe. C'est le bon chemin quand l'audience porte vraiment du PHI. * **Lever la désignation** — `PUT` le registre sans l'id d'audience. C'est le bon chemin *seulement* quand l'audience a été désignée par erreur. Lever une désignation pour contourner le gate est visible dans votre propre journal d'audit. Dans le wizard de campagne du dashboard, choisir une audience désignée montre un avertissement consultatif à l'étape d'audience. L'avertissement ne bloque pas le bouton **Suivant** — la désignation peut être levée ou le BAA exécuté avant le lancement — mais le gate dur au lancement s'applique toujours. ## 5. Audit trail Deux classes de registres atterrissent dans le journal d'audit de votre organisation : * **`hipaa.phi_audiences.set`** — une ligne par `PUT`, enregistrant l'utilisateur agissant, l'organisation et l'ensemble d'ids post-écriture complet. C'est votre histoire de versionnement : le registre n'a pas de ressource de révision séparée — la séquence de lignes d'audit *est* l'historique de versions. Pour reconstruire ce qui a été désigné à un point dans le temps, parcourez les lignes `set` en arrière ; pour revenir, `PUT` l'ensemble d'ids d'une ligne précédente. * **Refus de lancement `HIPAA_BAA_REQUIRED`** — chaque lancement bloqué est loggé avec la raison du refus et l'audience en évaluation. Ces lignes font double emploi comme votre file d'incidents : un refus signifie soit que du travail de compliance est en attente (BAA non exécuté) soit qu'une désignation et une campagne sont en désaccord. Passez les deux classes en revue à un rythme qui correspond à votre programme de compliance — hebdomadaire est un défaut workable pour un workspace de santé actif. Exportez le journal d'audit à côté de votre journal d'accès PHI lors de l'assemblage de preuves pour un audit externe ; le pack HIPAA du [binder de preuves](/compliance/evidence-binder) roule la posture BAA et la journalisation d'accès PHI en un téléchargement signé. **Runbook d'incident pour un refus inattendu :** 1. Lisez le `details.reason` et `details.audience.id` du refus. 2. Vérifiez `GET /api/v1/compliance/baa/` — si le BAA est `pending`/`expired`/non exécuté, résolvez-le via le [flux BAA](/compliance/baa). 3. Si le BAA est sain, vérifiez si l'audience devrait être désignée en premier lieu : `GET /api/v1/compliance/hipaa/phi-audiences` et comparez avec votre carte de données. Levez une désignation erronée avec un swap (`PUT` sans l'id). 4. Enregistrez le résultat dans votre propre registre d'incidents — les lignes d'audit ci-dessus sont la preuve que vous citez. ## 6. Troubleshooting des conflits d'écrasement concurrent Le `PUT` du registre ne renvoie jamais `409` — le swap atomique en une seule instruction signifie qu'une écriture commite toujours, et le dernier écrivain gagne. Le risque de conflit est **les mises à jour perdues entre opérateurs**, pas des écritures rejetées : * Opérateur A et opérateur B font tous les deux `GET` le registre. * A ajoute `list_aaa` et `PUT`. B — travaillant depuis le snapshot pré-A — ajoute `list_bbb` et `PUT`. * Le swap de B supprime silencieusement `list_aaa`. Mitigations : * **Lire immédiatement avant d'écrire.** Gardez la fenêtre read-modify-write courte ; ne portez pas un registre récupéré à travers une session d'édition — re-`GET` quand vous êtes prêt pour `PUT`. * **Vérifier après l'écriture.** `GET` une fois de plus et confirmez que votre id est présent et qu'aucune désignation non connectée n'a été perdue. Si quelque chose a disparu, les lignes `hipaa.phi_audiences.set` du journal d'audit montrent quel écrivain l'a écrasée et quel ensemble restaurer. * **Sérialiser les éditions du registre organisationnellement.** Parce que la désignation est une attestation de compliance, routez les éditions par un rôle (l'officier de compliance) plutôt que de les répandre entre opérateurs — un fix procédural qui élimine la course entièrement. Si vous voyez `422` au lieu du succès, la cause est la validation, pas le conflit : plus de **500** ids, un id vide après trim, ou un id de plus de 128 caractères. Trimez et réessayez avec l'ensemble complet. ## Voir aussi * [Désignations d'audiences adjacentes au PHI](/compliance/phi-audiences) — la référence endpoint pour le contrat du registre (plafond, sémantique de remplacement, action d'audit) * [Contrôles de compliance HIPAA](/compliance/hipaa) — la référence de contrôle complète que le registre alimente * [BAA — Business Associate Agreement](/compliance/baa) — le cycle de vie que le precheck de lancement fait respecter * [Onboarding HIPAA : du BAA à audit-ready](/guides/hipaa-onboarding) — la séquence qui amène un workspace santé à audit-ready avant que vous ne désigniez des audiences * [Send gates](/compliance/send-gates) — le gate par destinataire qui complète le precheck de lancement