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

# Onboarding HIPAA: del BAA a estar listo para auditoría

> Secuencia para llevar a un workspace de salud desde la firma del BAA hasta estar listo para la auditoría PHI: activar el modo HIPAA, restringir roles y scopes de API, configurar la retención, leer el registro de acceso PHI y exportar el binder de evidencia.

# Onboarding HIPAA: del BAA a estar listo para auditoría

La referencia de [controles HIPAA](/compliance/hipaa) explica qué hace cada control. Esta guía los pone en orden — la secuencia que lleva a un workspace de salud de "manejamos PHI" a "podemos mostrar un audit trail" sin tropezar con el send gate `422 HIPAA_BAA_REQUIRED` — uno de los [send gates](/compliance/send-gates) que verifican la compliance del remitente antes de que se despache un mensaje o una llamada.

El orden importa. El modo HIPAA no puede activarse antes de que el BAA se ejecute, los envíos de PHI son rechazados hasta que lo sea, y la retención solo protege datos una vez configurada. Siga los pasos de arriba abajo.

Cada paso a continuación se ejecuta contra `https://api.orbit.devotel.io/api/v1` con un encabezado `X-API-Key` en una clave de **propietario o administrador**. Expórtela antes de empezar:

```bash theme={null}
export ORBIT_KEY="dv_live_sk_…"   # live — o dv_test_sk_… contra el sandbox
```

Dos convenciones valen para cada respuesta en esta página:

* **Prefijos de clave.** Las claves de sandbox son `dv_test_sk_…`; las claves live son `dv_live_sk_…`. Cada llamada a continuación funciona en cualquiera — sandbox devuelve los mismos envelopes sin tocar el estado de compliance en vivo.
* **Envelope compartido.** Cada body 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 la Business Associate Agreement (BAA) esté ejecutada. Dos gates leen el estado del BAA directamente:

* **Activar el modo HIPAA** devuelve `403 Forbidden` mientras el estado del BAA no sea `executed`.
* **Cualquier envío de PHI** es rechazado con `422 HIPAA_BAA_REQUIRED`.

Ejecútela a través del panel **Compliance → BAA** en el dashboard, o impulse las mismas tres llamadas a través de la API. Use una clave de propietario para `/execute` (vincula el acuerdo legal); una clave de propietario-o-administrador es suficiente 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:

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```typescript Node.js theme={null}
  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"
  ```
</CodeGroup>

```json theme={null}
{
  "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 escribir-el-nombre

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

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```typescript Node.js theme={null}
  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"
  ```
</CodeGroup>

```json theme={null}
{
  "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 período de un año y debe re-ejecutarse:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.orbit.devotel.io/api/v1/compliance/baa \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  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); // por ejemplo 365
  ```
</CodeGroup>

```json theme={null}
{
  "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 legacy y las formas completas de solicitud están documentados bajo [BAA](/compliance/hipaa#5-business-associate-agreement-baa). Para la consola de ejecución, re-ejecución anual y controles de rechazo/reversión — más las consolas hermanas DPA y consentimiento de grabación — vea [Ejecutar el DPA y el BAA, luego gestionar el consentimiento de grabación por llamada](/guides/compliance-dpa-baa-recording-consent).

## 2. Activar el modo HIPAA

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

* **Dashboard:** **Configuración → Compliance → HIPAA Mode Toggle**.
* **API:**

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

  ```typescript Node.js theme={null}
  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
  ```
</CodeGroup>

```json theme={null}
{
  "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": "…" }
}
```

Activar es una sola llamada — endurece la postura del workspace, así que no se requiere reto de re-autenticación. Desactivar es destructivo y sí requiere uno; ese flujo está documentado bajo [Desactivar el modo HIPAA](/compliance/hipaa#6-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 *minimum necessary* de HIPAA es **su** responsabilidad — está del lado del cliente de la [tabla de responsabilidad compartida](/compliance/hipaa#shared-responsibility). Los controles de Orbit hoy son gruesos, así que aprovisione para ello honestamente:

* Use el **rol `billing`** para personal que solo necesita superficies financieras. Los miembros de billing están confinados a facturación, precios y uso — reciben `403` en endpoints de contenido de mensajes.
* Tenga en mente el need-to-read de todos los demás: `owner`, `admin`, `developer` y `viewer` pueden leer contenido de mensajes hoy, y cada lectura aterriza en el registro de acceso PHI.
* Emita claves de API solo con los scopes que la integración necesita, y otorgue `messages:read` solo a servicios que genuinamente leen contenido de mensajes que lleva PHI.

> **Limitación conocida:** Orbit actualmente no restringe las lecturas de contenido de mensajes a un conjunto de roles más estrecho más allá del confinamiento de billing, y los endpoints de lectura de mensajes (`GET /messages`, `GET /messages/{id}`) no requieren un código de razón suministrado por el operador. Cumpla el estándar minimum-necessary aprovisionando la membresía del workspace y los scopes de claves API para que solo el personal que necesita PHI pueda alcanzar esos endpoints. Si su programa requiere restricción de lectura por rol sobre contenido de mensajes, contacte a [compliance@devotel.io](mailto:compliance@devotel.io) antes de confiar en ello.

## 4. Configurar la retención de datos

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

* **Dashboard:** **Configuración → Compliance → HIPAA → Retención de datos**.
* **API** (solo propietario, mismo endpoint que el toggle):

<CodeGroup>
  ```bash cURL theme={null}
  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 }'
  ```

  ```typescript Node.js theme={null}
  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
  ```
</CodeGroup>

La respuesta repite el objeto de estado completo (misma forma que la llamada de activación arriba); verifique `data.data_retention.days`.

Un job en segundo plano escanea contenido de mensajes, grabaciones de llamadas y adjuntos de medios caducados y los elimina. Los logs de auditoría y los logs de acceso PHI se retienen independientemente de esta política — el reloj de eliminación no borra su pista de evidencia.

Si graba llamadas, fije la región de voz para que coincida con sus obligaciones de residencia al mismo tiempo — vea [Residencia y retención de datos de voz](/compliance/voice-data-residency) para el control de residencia que mantiene grabaciones, buzón de voz y medios en vivo en una región.

## 5. Verificar la configuración

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

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.orbit.devotel.io/api/v1/settings/hipaa \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  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);
  ```
</CodeGroup>

```json theme={null}
{
  "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": "…" }
}
```

Verifique `enabled` y `data_retention.days` en la respuesta.

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

## 6. Leer el registro de acceso PHI

Una vez que el modo HIPAA está activado, cada acceso a datos que contienen PHI es escrito en un log de auditoría append-only. Cada entrada registra el usuario, el recurso, la razón (`read` se registra automáticamente en lecturas de mensajes) y el timestamp. Página con `?limit=` y `?cursor=` — pase el `id` de la última entrada que vio como el siguiente `cursor` (propietario o administrador):

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.orbit.devotel.io/api/v1/settings/hipaa/phi-access-log?limit=50" \
    -H "X-API-Key: $ORBIT_KEY"
  ```

  ```typescript Node.js theme={null}
  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);
  ```
</CodeGroup>

```json theme={null}
{
  "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 log retiene hasta 10.000 entradas por organización con las más antiguas rotadas fuera, es accesible a los roles `owner` y `admin` vía el dashboard o la API, y puede exportarse para auditorías externas. Revíselo en un calendario temprano — es como 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 la siguiente página.

## 7. Exportar el binder de evidencia HIPAA

Cuando necesite mostrar postura a un auditor o al equipo de procurement de un comprador, genere el pack HIPAA del [binder de evidencia](/compliance/evidence-binder) desde **Configuración → Compliance → Binder**. El framework HIPAA ensambla el registro de acceso PHI, la postura BAA y su retención configurada en un pack firmado y listo para descargar; cada generación se registra en su log de auditoría, y el enlace de descarga expira tras 24 horas.

## Bundle de activación healthcare

El [marketplace de plugins de compliance](/compliance/plugin-marketplace) envía un bundle de activación **HIPAA healthcare** que aprovisiona un perfil de compliance en borrador, campañas en borrador, un agente AI ajustado a la vertical y una configuración de flujo opt-in en una llamada. Es un andamiaje inicial, no un sustituto de esta secuencia: activar el bundle nunca ejecuta el BAA, nunca activa el modo HIPAA y nunca coloca un envío. Ejecute los pasos 1–6 arriba primero, luego active el bundle y trabaje su checklist go-live de borrador a producción.

## Checklist de orden de operaciones

* [ ] BAA ejecutado y `baa_status` confirmado como `executed` — *rol propietario*
* [ ] Modo HIPAA activado vía el toggle o `PUT /settings/hipaa` — *rol propietario*
* [ ] Membresía recortada al mínimo necesario; `messages:read` con scope solo a claves que lo necesitan — *administrador*
* [ ] `data_retention_days` fijado a su ventana de política — *administrador*
* [ ] Región de voz fijada si sus obligaciones de residencia restringen dónde pueden vivir el audio grabado — *administrador*
* [ ] `GET /settings/hipaa` verificado, con `encryption_algorithm` tratado como solo-informe — *oficial de compliance*
* [ ] Registro de acceso PHI revisado en calendario — *oficial de compliance*
* [ ] Binder de evidencia HIPAA generado y entregado a través del enlace de 24 horas — *oficial de compliance*