Onboarding HIPAA: del BAA a la preparación para auditoría

La referencia de HIPAA controls explica qué hace cada control. Esta guía es el recorrido canónico de extremo a extremo que los pone en orden — la secuencia que lleva un espacio de trabajo de salud de “manejamos PHI” a “podemos mostrar una pista de auditoría” sin tropezar con el gate de envío 422 HIPAA_BAA_REQUIRED. El runbook de primera activación es el compañero en formato checklist que entrega la misma secuencia a operaciones sin repetir los ejemplos de aquí. El orden importa. El modo HIPAA no puede habilitarse antes de ejecutar el BAA, los envíos de PHI se rechazan hasta que lo esté, y la retención solo protege datos una vez configurada. Siga los pasos de arriba a abajo. Cada paso de abajo corre contra https://api.orbit.devotel.io/api/v1 con un encabezado X-API-Key sobre una clave owner o admin. Expórtela antes de empezar:

export ORBIT_KEY="dv_live_sk_…"   # live — or dv_test_sk_… against the sandbox

Dos convenciones valen para toda respuesta de esta página:

Prefijos de clave. Las claves de sandbox son dv_test_sk_…; las claves live son dv_live_sk_…. Toda llamada de abajo funciona en ambas — sandbox devuelve los mismos sobres sin tocar el estado de cumplimiento live.
Sobre compartido. Todo cuerpo de éxito es { "data": { … }, "meta": { "request_id", "timestamp" } }. Los errores son { "error": { code, message, status }, "meta": … }.

1. Ejecutar el BAA

Nada más se desbloquea hasta que el Business Associate Agreement (BAA) esté ejecutado. Dos gates leen el estado del BAA directamente:

Habilitar el modo HIPAA devuelve 403 Forbidden mientras el estado del BAA no sea executed.
Todo envío de PHI se rechaza con 422 HIPAA_BAA_REQUIRED.

Ejecútelo por el panel Compliance → BAA del tablero, o conduzca las mismas tres llamadas por la API. Use una clave owner para /execute (liga el acuerdo legal); una clave owner-or-admin basta para /require y GET /compliance/baa.

1a. Atestar que PHI está en el ámbito

Mueva la organización de not_required a pending, lo que abre el flujo de ejecución:

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/baa/require \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Clinic messaging will carry PHI" }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/compliance/baa/require",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ reason: "Clinic messaging will carry PHI" }),
  },
);
console.log((await res.json()).data.baa_status); // "pending"

{
  "data": {
    "baa_status": "pending",
    "baa_executed_at": null,
    "baa_template_version": null,
    "baa_signer_name": null,
    "baa_signer_email": null,
    "baa_pdf_gcs_url": null,
    "hipaa_required": true,
    "expires_at": null,
    "days_until_expiry": null
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

reason es texto libre opcional registrado en la fila de auditoría, nunca en una columna.

1b. Ejecutar con una firma electrónica de teclear-el-nombre

Registre la attestación. typed_attestation debe coincidir exactamente con signer_name — es la defensa contra una firma accidental o de formulario en blanco:

curl -X POST https://api.orbit.devotel.io/api/v1/compliance/baa/execute \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "Ada Lovelace",
    "signer_email": "ada@clinic.example",
    "typed_attestation": "Ada Lovelace"
  }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/compliance/baa/execute",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      signer_name: "Ada Lovelace",
      signer_email: "ada@clinic.example",
      typed_attestation: "Ada Lovelace",
    }),
  },
);
console.log((await res.json()).data.baa_status); // "executed"

{
  "data": {
    "baa_status": "executed",
    "baa_executed_at": "2026-09-23T14:02:11.482Z",
    "baa_template_version": "v1",
    "baa_signer_name": "Ada Lovelace",
    "baa_signer_email": "ada@clinic.example",
    "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
    "hipaa_required": true,
    "expires_at": "2027-09-23T14:02:11.482Z",
    "days_until_expiry": 365,
    "baa_id": "baa_…"
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

1c. Confirmar que el BAA está ejecutado

Relea el ciclo de vida y anote days_until_expiry — un BAA ejecutado expira tras su plazo de un año y debe re-ejecutarse:

curl https://api.orbit.devotel.io/api/v1/compliance/baa \
  -H "X-API-Key: $ORBIT_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/compliance/baa",
  { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
);
console.log((await res.json()).data.days_until_expiry); // e.g. 365

{
  "data": {
    "baa_status": "executed",
    "baa_executed_at": "2026-09-23T14:02:11.482Z",
    "baa_template_version": "v1",
    "baa_signer_name": "Ada Lovelace",
    "baa_signer_email": "ada@clinic.example",
    "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
    "hipaa_required": true,
    "expires_at": "2027-09-23T14:02:11.482Z",
    "days_until_expiry": 365
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

El ciclo de vida del BAA, la salvedad del espejo heredado y las formas completas de petición están documentados en BAA. Para el recorrido por consola de la ejecución, la re-ejecución anual y los controles de declinar/revertir — más las consolas hermanas de DPA y consentimiento de grabación — vea Execute the DPA and BAA, then manage per-call recording consent.

2. Habilitar el modo HIPAA

Con el BAA ejecutado, encienda la bandera HIPAA por organización. El modo HIPAA es una bandera de función por organización que activa cinco controles de una vez — cifrado en reposo, controles de acceso, registro de auditoría de PHI, retención forzada y seguimiento del BAA. Esta es una llamada solo de owner.

Tablero: Settings → Compliance → HIPAA Mode Toggle.
API:

curl -X PUT https://api.orbit.devotel.io/api/v1/settings/hipaa \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa",
  {
    method: "PUT",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true }),
  },
);
console.log((await res.json()).data.enabled); // true

{
  "data": {
    "enabled": true,
    "enabled_at": "2026-09-23T14:05:40.118Z",
    "last_enabled_at": "2026-09-23T14:05:40.118Z",
    "disabled_at": null,
    "enable_history": [
      { "enabledAt": "2026-09-23T14:05:40.118Z" }
    ],
    "baa_status": "executed",
    "hipaa_required": true,
    "baa": {
      "signed": true,
      "signedAt": "2026-09-23T14:02:11.482Z",
      "documentPresent": true,
      "history": []
    },
    "data_retention": { "enabled": true, "days": 365 },
    "encryption_algorithm": "AES-256-GCM",
    "phi_access_log_count": 0
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Habilitar es una sola llamada — endurece la postura del espacio de trabajo, así que no se requiere desafío de re-autenticación. Deshabilitar es destructivo y sí lo requiere; ese flujo está documentado en Disabling HIPAA Mode. Si el estado del BAA no es executed, la llamada devuelve 403 Forbidden.

3. Restringir roles y scopes de API al mínimo necesario

El estándar de mínimo necesario de HIPAA es responsabilidad suya — se sitúa del lado del cliente de la tabla de responsabilidad compartida. Los controles de Orbit hoy son gruesos, así que aprovisiónelo con honestidad:

Use el rol billing para el personal que solo necesita superficies financieras. Los miembros billing quedan confinados a facturación, precios y uso — reciben 403 en endpoints de contenido de mensajes.
Tenga presente la necesidad de lectura de los demás: owner, admin, developer y viewer pueden leer contenido de mensajes hoy, y cada lectura aterriza en el registro de acceso a PHI.
Imprima claves API solo con los scopes que la integración necesita, y conceda messages:read únicamente a servicios que realmente leen contenido de mensajes con PHI.

Limitación conocida: Orbit actualmente no restringe las lecturas de contenido de mensajes a un conjunto más estrecho de roles más allá del confinamiento billing, y los endpoints de lectura de mensajes (GET /messages, GET /messages/{id}) no exigen un código de razón provisto por el operador. Cumpla el estándar de mínimo necesario aprovisionando la membresía del espacio de trabajo y los scopes de claves API de modo que solo el personal que necesita PHI pueda alcanzar esos endpoints. Si su programa exige restricción de lectura por rol sobre contenido de mensajes, contacte a support@orbit.devotel.io antes de apoyarse en ello.

4. Configurar la retención de datos

Fije la ventana de retención antes de que PHI se acumule más allá de ella. data_retention_days acepta 30 a 3.650; el default es 365.

Tablero: Settings → Compliance → HIPAA → Data Retention.
API (solo owner, el mismo endpoint que el toggle):

curl -X PUT https://api.orbit.devotel.io/api/v1/settings/hipaa \
  -H "X-API-Key: $ORBIT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "data_retention_days": 90 }'

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa",
  {
    method: "PUT",
    headers: {
      "X-API-Key": process.env.ORBIT_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true, data_retention_days: 90 }),
  },
);
console.log((await res.json()).data.data_retention.days); // 90

La respuesta devuelve en eco el objeto de estado completo (misma forma que la llamada de habilitación de arriba); compruebe data.data_retention.days. Un trabajo en segundo plano busca contenido de mensajes, grabaciones de llamadas y archivos multimedia expirados y los elimina. Los registros de auditoría y los registros de acceso a PHI se conservan independientemente de esta política — el reloj de borrado no borra su pista de evidencia. Si graba llamadas, fije la región de voz para cumplir sus obligaciones de residencia al mismo tiempo — vea Voice Data Residency & Retention por el mando de residencia que mantiene grabaciones, correo de voz y medios en vivo en una sola región.

5. Verificar la configuración

Confirme que la bandera y la retención aterrizaron como usted pretendía (owner o admin):

curl https://api.orbit.devotel.io/api/v1/settings/hipaa \
  -H "X-API-Key: $ORBIT_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa",
  { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
);
const { data } = await res.json();
console.log(data.enabled, data.data_retention.days);

{
  "data": {
    "enabled": true,
    "enabled_at": "2026-09-23T14:05:40.118Z",
    "last_enabled_at": "2026-09-23T14:05:40.118Z",
    "disabled_at": null,
    "enable_history": [ { "enabledAt": "2026-09-23T14:05:40.118Z" } ],
    "baa_status": "executed",
    "hipaa_required": true,
    "baa": { "signed": true, "signedAt": "2026-09-23T14:02:11.482Z", "documentPresent": true, "history": [] },
    "data_retention": { "enabled": true, "days": 90 },
    "encryption_algorithm": "AES-256-GCM",
    "phi_access_log_count": 12
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

Compruebe enabled y data_retention.days en la respuesta.

La respuesta también lleva un campo encryption_algorithm. Es solo informativo: refleja el estándar de cifrado en reposo de la plataforma (AES-256 gestionado por Google en Cloud SQL), no un cifrado de capa de aplicación por organización. Devotel actualmente no realiza cifrado de capa de aplicación de cuerpos de mensajes por organización, así que no cite este campo ante un auditor como evidencia de que los cuerpos de mensajes están cifrados individualmente en la capa de aplicación.

6. Leer el registro de acceso a PHI

Una vez encendido el modo HIPAA, cada acceso a datos que contienen PHI se escribe en un registro de auditoría de solo adición. Cada entrada registra el usuario, el recurso, la razón (read se registra automáticamente en lecturas de mensajes) y el timestamp. Pagine con ?limit= y ?cursor= — pase el id de la última entrada vista como el siguiente cursor (owner o admin):

curl "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50" \
  -H "X-API-Key: $ORBIT_KEY"

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50",
  { headers: { "X-API-Key": process.env.ORBIT_KEY! } },
);
const { data } = await res.json();
console.log(data.entries[0]?.resource, data.has_more);

{
  "data": {
    "entries": [
      {
        "id": "phi_…",
        "userId": "user_…",
        "resource": "message:msg_…",
        "reason": "read",
        "accessedAt": "2026-09-23T14:12:07.901Z"
      },
      {
        "id": "phi_…",
        "userId": "user_…",
        "resource": "contact:con_…",
        "reason": "treatment",
        "accessedAt": "2026-09-23T13:58:44.210Z"
      }
    ],
    "has_more": true,
    "total": 12
  },
  "meta": { "request_id": "…", "timestamp": "…" }
}

El registro conserva hasta 10.000 entradas por organización rotando fuera las más antiguas, es accesible a los roles owner y admin vía tablero o API, y puede exportarse para auditorías externas. Revíselo según un calendario desde temprano — así demuestra que el acceso sigue las decisiones de rol y scope que tomó en el paso 3. Cuando has_more es true, envíe el id de la última entrada como ?cursor= para obtener la página siguiente.

7. Exportar el archivador de evidencia HIPAA

Cuando necesite mostrar su postura a un auditor o al equipo de compras de un comprador, genere el pack HIPAA del archivador de evidencia desde Settings → Compliance → Binder. El framework HIPAA ensambla el registro de acceso a PHI, la postura del BAA y su retención configurada en un pack firmado y listo para descargar; cada generación queda registrada en su registro de auditoría, y el enlace de descarga expira tras 24 horas.

Bundle de activación healthcare

El mercado de plugins de cumplimiento entrega un bundle de activación HIPAA healthcare que aprovisiona en una llamada un perfil de cumplimiento en borrador, campañas en borrador, un agente IA afinado al sector y una configuración de flujo de opt-in. Es un andamio de partida, no un sustituto de esta secuencia: activar el bundle nunca ejecuta el BAA, nunca habilita el modo HIPAA y nunca coloca un envío. Ejecute primero los pasos 1 a 6 de arriba, luego active el bundle y lleve su checklist de puesta en producción del borrador a producción.

Checklist de orden de operaciones

BAA ejecutado y baa_status confirmado como executed — rol owner
Modo HIPAA habilitado vía el toggle o PUT /settings/hipaa — rol owner
Membresía recortada al mínimo necesario; messages:read con scope solo a claves que lo necesitan — administrator
data_retention_days fijado a la ventana de su política — administrator
Región de voz fijada si sus obligaciones de residencia restringen dónde puede vivir el audio grabado — administrator
GET /settings/hipaa verificado, con encryption_algorithm tratado como solo informativo — compliance officer
Registro de acceso a PHI revisado según calendario — compliance officer
Archivador de evidencia HIPAA generado y entregado por el enlace de 24 horas — compliance officer

​Onboarding HIPAA: del BAA a la preparación para auditoría

​1. Ejecutar el BAA

​1a. Atestar que PHI está en el ámbito

​1b. Ejecutar con una firma electrónica de teclear-el-nombre

​1c. Confirmar que el BAA está ejecutado

​2. Habilitar el modo HIPAA

​3. Restringir roles y scopes de API al mínimo necesario

​4. Configurar la retención de datos

​5. Verificar la configuración

​6. Leer el registro de acceso a PHI

​7. Exportar el archivador de evidencia HIPAA

​Bundle de activación healthcare

​Checklist de orden de operaciones