> ## 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. # Registrar audiencias adyacentes a PHI > Walkthrough del registro de audiencias adyacentes a PHI: cuándo designar una lista o segmento, cómo funciona el PUT de reemplazo total atómico, cómo reacciona el precheck de lanzamiento de campaña y cómo leer el audit trail. # Registrar audiencias adyacentes a PHI El registro de audiencias adyacentes a PHI es la lista de su organización de listas de contacto y segmentos cuyos miembros llevan PHI — por ejemplo, pacientes optados a divulgación de tratamiento. La referencia de [controles HIPAA](/compliance/hipaa#phi-adjacent-audience-registry) documenta los dos endpoints; esta guía lo lleva por ejecutarlos en producción: qué designar, cómo funcionan las semánticas de escritura, qué pasa al lanzamiento de campaña y cómo leer el audit trail. El registro es **propiedad del tenant**. Devotel nunca designa audiencias en su nombre y nunca scopeo PHI por usted — las designaciones son su atestación, son controles bloqueados por BAA que usted opera, y solo surten efecto una vez que HIPAA está en el ámbito de su organización. Si no ha ejecutado aún el BAA y activado el modo HIPAA, ejecute primero la secuencia de [Onboarding HIPAA](/guides/hipaa-onboarding). ## 1. Cuándo marcar una audiencia como adyacente a PHI La designación sigue la **proveniencia**: marque las audiencias cuyos datos de origen contienen PHI, independientemente de lo que cualquier campaña individual les envíe. Una audiencia es adyacente a PHI por de dónde vinieron sus miembros — una importación de recordatorios de cita de pacientes, una lista opt-in de divulgación de tratamiento — no por el copy que escribe esta semana. Por eso la designación vive en la audiencia misma y no en una campaña: cualquier campaña que la recoja, la designación viaja con ella. Marque una audiencia como adyacente a PHI cuando: * Sus miembros fueron importados de un sistema que retiene PHI (una exportación EHR, una sincronización opt-in de portal de pacientes). * La lista o segmento está filtrado o ensamblado sobre criterios que llevan PHI (tags adyacentes a diagnóstico, cohortes de tratamiento). * El mapa de datos de su oficial de compliance registra la audiencia como PHI en el ámbito. No designe una audiencia "por si acaso". Una designación adjunta el [gate de lanzamiento BAA](#4-cómo-el-precheck-de-lanzamiento-usa-el-registro) a cada campaña que usa la audiencia — designar audiencias que no llevan PHI bloquea lanzamientos sin razón de compliance. **Quién puede atestar:** ambos endpoints requieren el rol `owner` o `admin` — el mismo gate que los [endpoints BAA](/compliance/baa). Un `developer` o `viewer` recibe `403`. Mantenga la decisión de designación con su oficial de compliance HIPAA; la plataforma registra *quién* cambió el registro en cada escritura (vea [Audit trail](#5-audit-trail)). ## 2. Elegir ids de lista vs segmento El registro retiene ids de audiencia — cada entrada es o un **id de lista de contacto** o un **id de segmento**, pasado como string plano. El precheck de lanzamiento de campaña solo resuelve audiencias tipo `list` y `segment` contra el registro; las audiencias ensambladas por contacto (todos los contactos, carga CSV, entrada manual) son evaluadas destinatario por destinatario al momento del envío, así que no tienen id de registro que designar. Para rederivar el id para una designación: ```bash theme={null} # Listas de contacto GET /api/v1/contacts/lists # Segmentos GET /api/v1/contacts/segments ``` Copie el campo `id` de la lista o segmento que está designando. Los ids son 1–128 caracteres tras el trim; cualquier cosa más larga o vacía es rechazada con `422` al escribir. El registro retiene como máximo **500** ids por organización — un `PUT` que lleva más devuelve `422`. > Designe el id de **origen**, no una copia downstream. Si una lista que lleva PHI alimenta un segmento derivado, decida si el segmento derivado también contiene PHI y designe explícitamente — el precheck verifica el id que la campaña realmente referencia, nada más. ## 3. El swap PUT atómico El registro tiene **una** operación de escritura: un `PUT` de reemplazo total. No hay `PATCH`, no hay `DELETE` por id — cada escritura reemplaza el conjunto designado entero en una sola instrucción atómica, así que un `GET` concurrente nunca ve una actualización parcialmente aplicada. ```bash theme={null} PUT /api/v1/compliance/hipaa/phi-audiences { "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"] } ``` La respuesta repite el conjunto almacenado: ```json theme={null} { "data": { "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"], "replaced": true } } ``` El body es **idempotente**: enviar el mismo conjunto total dos veces produce el mismo registro almacenado y dos filas de auditoría distintas. Un array vacío limpia toda designación: ```bash theme={null} PUT /api/v1/compliance/hipaa/phi-audiences { "audience_ids": [] } ``` Porque la escritura es un swap, cada cliente debe seguir **read-modify-write**: `GET` el registro actual, agregue o quite su id en el resultado, y `PUT` el conjunto entero de vuelta. Nunca construya el body desde estado local solo — silenciosamente quitaría designaciones que otro operador agregó. Para levantar una designación, `PUT` el registro sin ese id. Para re-designar, `PUT` con el id agregado de vuelta. Ids individuales que sobreviven un swap quedan sin cambios; solo importa la membresía en el conjunto. ## 4. Cómo el precheck de lanzamiento usa el registro Dos gates protegen PHI en puntos diferentes, y el registro alimenta el primero: 1. **Precheck de lanzamiento (nivel campaña, gate duro).** Antes de que una campaña salga de borrador/programada, el precheck resuelve su id de audiencia contra el registro. Un id designado más un BAA que no está `executed` y en período rechaza el lanzamiento con `422 HIPAA_BAA_REQUIRED` — antes de que un solo destinatario se inscriba. Si el estado de compliance no puede leerse, el precheck falla cerrado con `500 HIPAA_BAA_GATE_DB_FAIL` en lugar de admitir silenciosamente la audiencia. 2. **Gate de envío por destinatario (tiempo de mensaje, sin cambios).** El gate de envío existente sigue aplicando a cada envío individual y no consulta el registro — los envíos legacy de uno a uno son gobernados solo por él. Un lanzamiento bloqueado aflora con la negación de abajo. El `details.reason` le dice exactamente qué estado de BAA lo desbloquea: ```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` | Qué significa | Cómo desbloquear | | ------------ | ----------------------------------------------------------- | --------------------------------------------------------------------- | | `not_signed` | PHI está atestado en el ámbito pero nunca se ejecutó un BAA | Ejecutar el BAA — [flujo BAA](/compliance/baa) | | `pending` | La ejecución del BAA empezó pero no se completó | Terminar el paso de ejecución (`POST /api/v1/compliance/baa/execute`) | | `expired` | El BAA ejecutado pasó su período de un año | Re-ejecutar el BAA | Hay **dos** formas de desbloquear, y son decisiones de compliance, no de plataforma: * **Resolver el BAA** — ejecutarlo o re-ejecutarlo para que el gate pase. Este es el camino correcto cuando la audiencia genuinamente lleva PHI. * **Quitar la designación** — `PUT` el registro sin el id de audiencia. Este es el camino correcto *solo* cuando la audiencia se designó por error. Levantar una designación para rodear el gate es visible en su propio log de auditoría. En el asistente de campaña del dashboard, elegir una audiencia designada muestra una advertencia asesora en el paso de audiencia. La advertencia no bloquea el botón **Siguiente** — la designación puede levantarse o el BAA ejecutarse antes del lanzamiento — pero el gate duro al lanzamiento siempre aplica. ## 5. Audit trail Dos clases de registros aterrizan en el log de auditoría de su organización: * **`hipaa.phi_audiences.set`** — una fila por `PUT`, que registra el usuario actuante, la organización y el conjunto de ids post-escritura completo. Es su historia de versionamiento: el registro no tiene un recurso de revisión separado — la secuencia de filas de auditoría *es* el historial de versiones. Para reconstruir qué se designó en un punto en el tiempo, recorra las filas `set` hacia atrás; para revertir, `PUT` el conjunto de ids de una fila anterior. * **Negaciones de lanzamiento `HIPAA_BAA_REQUIRED`** — cada lanzamiento bloqueado se loggea con la razón que lo negó y la audiencia en evaluación. Estas filas hacen doble partida como su cola de incidentes: una negación significa que o hay trabajo de compliance pendiente (BAA no ejecutado) o una designación y una campaña están en desacuerdo. Revise ambas clases a un ritmo que coincida con su programa de compliance — semanal es un default trabajable para un workspace healthcare activo. Exporte el log de auditoría junto con su log de acceso PHI al ensamblar evidencia para una auditoría externa; el pack HIPAA del [binder de evidencia](/compliance/evidence-binder) enrolla la postura BAA y el registro de acceso PHI en una descargar firmado. **Runbook de incidentes para una negación inesperada:** 1. Lea el `details.reason` y `details.audience.id` de la negación. 2. Verifique `GET /api/v1/compliance/baa/` — si el BAA es `pending`/`expired`/no ejecutado, resuélvalo a través del [flujo BAA](/compliance/baa). 3. Si el BAA está sano, verifique si la audiencia debería estar designada en absoluto: `GET /api/v1/compliance/hipaa/phi-audiences` y compare contra su mapa de datos. Levante una designación errónea con un swap (`PUT` sin el id). 4. Registre el resultado en su propio registro de incidentes — las filas de auditoría arriba son la evidencia que cita. ## 6. Troubleshooting de conflictos de sobreescritura concurrente El `PUT` del registro nunca devuelve `409` — el swap atómico de una sola instrucción significa que una escritura siempre commitea, y el último escritor gana. El riesgo de conflicto son **actualizaciones perdidas entre operadores**, no escrituras rechazadas: * Operador A y operador B ambos `GET` el registro. * A agrega `list_aaa` y `PUT`. B — trabajando desde el snapshot pre-A — agrega `list_bbb` y `PUT`. * El swap de B silenciosamente quita `list_aaa`. Mitigaciones: * **Leer inmediatamente antes de escribir.** Mantenga la ventana read-modify-write corta; no lleve un registro fetechado a través de una sesión de edición — re-`GET` cuando esté listo para `PUT`. * **Verificar después de escribir.** `GET` una vez más y confirme que su id está presente y que ninguna designación no relacionada se perdió. Si algo desapareció, las filas `hipaa.phi_audiences.set` del log de auditoría muestran cuya escritura lo sobreescribió y qué conjunto restaurar. * **Serializar ediciones del registro organizacionalmente.** Porque la designación es una atestación de compliance, enrute las ediciones a través de un rol (el oficial de compliance) en lugar de esparcirlas entre operadores — un fix procedimental que elimina la carrera por completo. Si ve `422` en lugar de éxito, la causa es validación, no conflicto: más de **500** ids, un id vacío tras el trim, o un id de más de 128 caracteres. Trime y reintente con el conjunto completo. ## Ver también * [Designaciones de audiencias adyacentes a PHI](/compliance/phi-audiences) — la referencia de endpoint para el contrato del registro (tope, semántica replace, acción de auditoría) * [Controles de compliance HIPAA](/compliance/hipaa) — la referencia completa de controles que el registro alimenta * [BAA — Business Associate Agreement](/compliance/baa) — el ciclo de vida que el precheck de lanzamiento hace cumplir * [Onboarding HIPAA: del BAA a auditoría](/guides/hipaa-onboarding) — la secuencia que lleva un workspace healthcare a audit-ready antes de designar audiencias * [Send gates](/compliance/send-gates) — el gate por destinatario que complementa el precheck de lanzamiento