​

Registrar audiencias adyacentes a PHI

​

1. Cuándo marcar una audiencia como adyacente a PHI

• 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.

​

2. Elegir ids de lista vs segmento

# Listas de contacto
GET /api/v1/contacts/lists

# Segmentos
GET /api/v1/contacts/segments

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

PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"]
}

{
  "data": {
    "audience_ids": ["list_9f2c1a", "seg_4b7e20", "list_31dc88"],
    "replaced": true
  }
}

PUT /api/v1/compliance/hipaa/phi-audiences
{
  "audience_ids": []
}

​

4. Cómo el precheck de lanzamiento usa el registro

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.

{
  "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" }
    }
  }
}

• 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.

​

5. Audit trail

• 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.

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.
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

• 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.

• 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.

​

Ver también

• Designaciones de audiencias adyacentes a PHI — la referencia de endpoint para el contrato del registro (tope, semántica replace, acción de auditoría)
• Controles de compliance HIPAA — la referencia completa de controles que el registro alimenta
• BAA — Business Associate Agreement — el ciclo de vida que el precheck de lanzamiento hace cumplir
• Onboarding HIPAA: del BAA a auditoría — la secuencia que lleva un workspace healthcare a audit-ready antes de designar audiencias
• Send gates — el gate por destinatario que complementa el precheck de lanzamiento