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

# Flujo del Business Associate Agreement (BAA)

> Ejecute su Business Associate Agreement de HIPAA con Devotel: acredite el ámbito de PHI, previsualice la plantilla, firme con una firma electrónica de escribir-el-nombre y descargue la copia ejecutada.

# Business Associate Agreement (BAA)

Las organizaciones que envían, almacenan o procesan Protected Health Information (PHI) a través de Devotel Orbit necesitan un Business Associate Agreement registrado. La plataforma hace cumplir que la ruta del BAA exista antes de que el modo HIPAA pueda habilitarse: cuando el PHI entra en el ámbito, la puerta en el momento del envío rechaza el tráfico con `HIPAA_BAA_REQUIRED` hasta que se registre un BAA ejecutado.

Esta guía cubre el ciclo de vida completo: los estados canónicos de `baa_status`, cómo encajan los seis endpoints `/api/v1/compliance/baa`, qué rol puede llamar a cada endpoint, qué cambia una vez que un BAA está ejecutado y cómo revertir un acuerdo ejecutado al valor predeterminado de la plataforma.

> Este es un **control HIPAA propiedad del inquilino**: usted decide si el PHI está en el ámbito, ejecuta el acuerdo de forma deliberada y lo vuelve a ejecutar antes de que venza el plazo anual. Devotel suministra la canalización de firma electrónica — la representación de la plantilla, la captura de la firma mecanografiada, el anclaje inmutable de la auditoría y el PDF ejecutado almacenado — pero la determinación legal de que el PHI está en el ámbito es suya.

***

## Estados de `baa_status`

Su organización siempre está en uno de cuatro estados, reportados por `GET /api/v1/compliance/baa`:

| Estado         | Significado                                                                                                                                                                               |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `not_required` | La organización ha acreditado (o tiene por defecto) que ningún PHI está en el ámbito. Este es el valor predeterminado de toda organización nueva.                                         |
| `pending`      | El PHI está en el ámbito (`hipaa_required = true`) y el BAA está pendiente de ejecución. El formulario de ejecución está disponible desde este estado.                                    |
| `executed`     | Un BAA ha sido firmado y está dentro de su plazo de un año. Este es el único estado que satisface las puertas de habilitación de HIPAA y de envío de PHI.                                 |
| `expired`      | Un BAA ejecutado ha superado su plazo de un año. Los envíos de PHI se bloquean de nuevo hasta que usted vuelva a ejecutar. La re-ejecución está disponible 60 días antes del vencimiento. |

La respuesta también lleva los datos del firmante y la cuenta atrás hasta el vencimiento:

```json theme={null}
{
  "baa_status": "executed",
  "baa_executed_at": "2026-08-10T14:22:31.410Z",
  "baa_template_version": "v1",
  "baa_signer_name": "Jane Roe",
  "baa_signer_email": "jane@example.com",
  "baa_pdf_gcs_url": "gs://…/baa/org_…/baa_….pdf",
  "hipaa_required": true,
  "expires_at": "2027-08-10T14:22:31.410Z",
  "days_until_expiry": 342
}
```

Cuando `hipaa_required` se activa mientras el estado sigue siendo `not_required`, el endpoint de lectura transiciona la organización a `pending` automáticamente, de modo que el paso de ejecución se abre sin una llamada aparte.

***

## Por qué el flujo comienza con una acreditación

El flujo del BAA existe porque HIPAA se aplica al *uso*, no a las cuentas. La plataforma no asume que cada espacio de trabajo maneja PHI: la organización primero acredita que el PHI está en el ámbito, lo que activa la bandera `hipaa_required` y mueve el estado a `pending`. Esa acreditación es lo que abre el paso de ejecución; la ejecución luego completa el acuerdo. Este orden cierra una dependencia circular: el modo HIPAA no puede habilitarse sin un BAA ejecutado, pero el panel también necesitaba una forma de *iniciar* el BAA antes de que existiera el modo HIPAA.

Tanto `require` (PHI está en el ámbito) como `decline` (ningún PHI en el ámbito) escriben una fila de la cadena de auditoría `compliance.baa.*` que nombra al actor, de modo que la acreditación en sí es un evento legal registrado, no un simple cambio de configuración descartable.

***

## El flujo de endpoints

Todas las rutas viven bajo `/api/v1/compliance/baa` y requieren una sesión autenticada. Las seis operaciones siguientes son el ciclo de vida completo; la página **Settings → Compliance → BAA** del panel dirige exactamente estos endpoints.

### 1. Leer el estado actual

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa" \
  -H "Authorization: Bearer sk_live_..."
```

Cualquier `owner` o `admin` puede leer. Use esto primero: le indica si la organización necesita acreditar, ejecutar, re-ejecutar o descargar.

### 2. Previsualizar la plantilla

Antes de firmar, revise el texto del acuerdo finalizado. `GET /api/v1/compliance/baa/template` devuelve la plantilla representada con el nombre legal de su organización ya rellenado. Los campos del momento de ejecución (marcas de tiempo, referencia del documento) aparecen como marcadores legibles en lugar de placeholders en bruto, y los campos del firmante son espacios en blanco que el panel rellena en vivo mientras usted escribe.

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa/template?version=v1" \
  -H "Authorization: Bearer sk_live_..."
```

Respuesta:

```json theme={null}
{
  "version": "v1",
  "covered_entity_name": "Acme Health Ltd",
  "format": "markdown",
  "body": "# Business Associate Agreement\n\nThis Business Associate Agreement..."
}
```

### 3. Acreditar que el PHI está en el ámbito

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/require" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "We began sending patient appointment reminders that contain PHI." }'
```

Esto activa `hipaa_required = true` y mueve una organización `not_required` a `pending`. Abre el flujo de ejecución: **no** habilita el modo HIPAA. El `reason` opcional (hasta 500 caracteres) se registra en la fila de auditoría.

### 4. Ejecutar con una firma electrónica de escribir-el-nombre

La ejecución es **solo para owner**: una firma click-wrap vincula a la organización, por lo que no es una acción de nivel de desarrollador. El firmante vuelve a escribir su nombre legal en `typed_attestation`, y el servidor exige que coincida exactamente con `signer_name`; una discrepancia se rechaza con un `400`, lo que además bloquea los envíos automáticos de formularios en blanco.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/execute" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "signer_name": "Jane Roe",
    "signer_email": "jane@example.com",
    "typed_attestation": "Jane Roe"
  }'
```

| Campo               | Regla                                                                              |
| ------------------- | ---------------------------------------------------------------------------------- |
| `signer_name`       | El nombre legal del firmante (2–200 caracteres).                                   |
| `signer_email`      | Una dirección de correo electrónico válida.                                        |
| `typed_attestation` | Debe **coincidir exactamente** con `signer_name`. Una discrepancia devuelve `400`. |
| `template_version`  | Opcional. Por defecto usa la versión canónica actual.                              |

En caso de éxito, el servidor:

1. Representa la plantilla con los datos del firmante, las marcas de tiempo de ejecución y una referencia de documento generada
2. Almacena el documento representado como el PDF ejecutado canónico
3. Estampa la organización como `executed` con el firmante, la versión de la plantilla y la marca de tiempo de ejecución, y registra el vencimiento (ejecución más el plazo estándar de un año)
4. Escribe una entrada `compliance.baa.executed` en el registro de auditoría junto con el método de firma (`type_the_name`): la entrada de auditoría es la evidencia legal de la acreditación, y el PDF almacenado es el documento canónico

La respuesta devuelve el nuevo estado más la referencia del documento:

```json theme={null}
{
  "baa_status": "executed",
  "baa_executed_at": "2026-08-24T09:41:12.008Z",
  "baa_template_version": "v1",
  "baa_signer_name": "Jane Roe",
  "baa_signer_email": "jane@example.com",
  "baa_id": "baa_9f2k…",
  "expires_at": "2027-08-24T09:41:12.008Z",
  "days_until_expiry": 365,
  "hipaa_required": true
}
```

La ejecución tiene un límite de velocidad de un puñado de solicitudes por minuto; es un acto legal deliberado, no un bucle programado. (Para la base legal del click-wrap, vea [Voice signatures](/compliance/voice-signatures).)

### 5. Descargar la copia ejecutada

Una vez que un BAA está registrado, cualquier `owner` o `admin` puede obtenerlo para sus registros, una auditoría de un cliente o un regulador:

```bash theme={null}
curl "https://api.orbit.devotel.io/api/v1/compliance/baa/download" \
  -H "Authorization: Bearer sk_live_..."
```

La respuesta lleva una URL de descarga válida por **24 horas**:

```json theme={null}
{
  "url": "https://storage.googleapis.com/…/baa/org_…/baa_….pdf?X-Goog-Signature=…",
  "expires_in_seconds": 86400
}
```

Comparta la URL dentro de esa ventana o descargue el archivo usted mismo y archívelo. Si todavía no se ha ejecutado ningún BAA, el endpoint devuelve `404`.

### 6. Revertir al valor predeterminado de la plataforma

Revertir elimina el acuerdo registrado y devuelve la organización a `not_required`. Es **solo para owner** y solo se puede llamar sobre un BAA ejecutado o vencido, y solo después de que el modo HIPAA haya sido deshabilitado, de modo que un espacio de trabajo HIPAA activo no pueda deshacer su propia evidencia silenciosamente.

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/compliance/baa/revert" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Organization no longer processes PHI; returning to default posture." }'
```

El historial de auditoría del BAA ejecutado y el PDF almacenado se **conservan**: revertir elimina el estado activo, no borra la evidencia. Use esto cuando el PHI genuinamente salga del ámbito, o para restablecer un espacio de trabajo a una base limpia; use [decline](#decline-no-phi-in-scope) en su lugar cuando cambie la acreditación de "sin PHI".

### Decline: acreditar que ningún PHI está en el ámbito

`POST /api/v1/compliance/baa/decline` (owner o admin, `reason` opcional) registra que el PHI no está en el ámbito y levanta la puerta en el momento del envío una vez que una organización se haya dado de alta. Se niega a tocar un BAA registrado: un decline no puede desmantelar un acuerdo ejecutado; para eso está `revert`. Como `require` y `decline` son conmutadores de acreditación simétricos, un administrador que declina puede restaurar el requisito más adelante si el PHI vuelve a entrar en el ámbito.

***

## Roles y la cadena de auditoría

Los endpoints de lectura, previsualización, descarga y acreditación aceptan `owner` o `admin`. Los dos actos que vinculan o deshacen un acuerdo legal — `execute` y `revert` — son **solo para owner**.

| Acción                                                               | `owner` | `admin` | `developer` / `viewer` / `billing` |
| -------------------------------------------------------------------- | :-----: | :-----: | :--------------------------------: |
| Leer el estado del BAA                                               |    Sí   |    Sí   |                 No                 |
| Previsualizar la plantilla                                           |    Sí   |    Sí   |                 No                 |
| Descargar la copia ejecutada                                         |    Sí   |    Sí   |                 No                 |
| Acreditar PHI en el ámbito (`require`) / no en el ámbito (`decline`) |    Sí   |    Sí   |                 No                 |
| Ejecutar el BAA                                                      |    Sí   |    No   |                 No                 |
| Revertir al predeterminado                                           |    Sí   |    No   |                 No                 |

Cada escritura agrega una entrada `compliance.baa.*` al registro de auditoría de la organización — `compliance.baa.hipaa_required` en require, `compliance.baa.declined` en decline, `compliance.baa.executed` en execute, `compliance.baa.reverted` en revert — que lleva el actor, el motivo y (en la ejecución) la versión de la plantilla y el método de firma. Esa cadena de solo agregación, no el campo de estado actual, es la evidencia legal de la acreditación. Puede inspeccionarla desde el panel en [Settings → Audit log](/guides/audit-log).

***

## Qué cambia una vez que un BAA está ejecutado

Ejecutar el BAA hace dos cosas:

1. **Levanta la puerta de envío de PHI.** Mientras `hipaa_required` sea verdadero y no haya un BAA en plazo registrado, los envíos salientes que tocan PHI se rechazan con `422 HIPAA_BAA_REQUIRED`. Un BAA ejecutado elimina ese rechazo. (La resolución de la puerta y su comportamiento fail-closed están documentados en [Send gates](/compliance/send-gates#baa-the-hipaa-send-gate).)
2. **Desbloquea el modo HIPAA.** Habilitar el modo HIPAA requiere `baa_status = "executed"`; intentarlo antes de la ejecución devuelve `403`. Una vez que el modo HIPAA está activado, los controles descritos en [HIPAA compliance controls](/compliance/hipaa) — el registro de acceso a PHI, la retención de datos y el resto — se aplican al espacio de trabajo.

Lo que **no** cambia: ejecutar un BAA no habilita por sí solo el modo HIPAA, no determina si su procesamiento es lícito y no reemplaza su propio programa de HIPAA. El acuerdo registra las obligaciones de la plataforma hacia usted como business associate; decidir que el PHI está en el ámbito, designar audiencias adyacentes a PHI y configurar la retención siguen siendo propiedad del inquilino. Para cómo encajan las piezas, vea [HIPAA onboarding](/guides/hipaa-onboarding) y [HIPAA compliance controls](/compliance/hipaa).

***

## Flujo del panel

El mismo ciclo de vida está disponible sin tocar la API en **Settings → Compliance → BAA**:

1. **Tarjeta de estado** — muestra el `baa_status` actual, la fecha de ejecución, el firmante y un banner de re-ejecución cuando el plazo está dentro de los 60 días previos al vencimiento
2. **Previsualización de la plantilla** — el acuerdo representado con el nombre de su organización ya rellenado
3. **Formulario de acreditación** — el nombre y el correo electrónico del firmante más el campo de firma de escribir-el-nombre, mostrado a los owners cuando el estado es `pending`
4. **Descarga** — un enlace a la copia ejecutada una vez ejecutada, con una URL fresca de 24 horas en cada solicitud

Si el PHI aún no se ha acreditado, la página presenta una llamada a la acción "Start handling PHI" que envía la acreditación `require` e inmediatamente abre el panel de ejecución, reflejando el flujo de la API anterior.

***

## Preguntas frecuentes

**¿Cuánto dura un BAA ejecutado?**
Un año desde la ejecución. La respuesta de estado lleva `expires_at` y `days_until_expiry`; dentro de los 60 días previos al vencimiento, el panel muestra un banner de re-ejecución. Pasado el vencimiento, el estado pasa a `expired` y la puerta de envío de PHI se cierra de nuevo hasta que usted re-ejecute con el mismo flujo.

**¿Puede un admin ejecutar el BAA para desbloquear los envíos?**
No: la ejecución (y la reversión) es solo para owner porque vincula a la organización. Un admin *sí puede* marcar el PHI como requerido o declinado, leer el estado, previsualizar la plantilla y descargar la copia ejecutada.

**¿Cuál es la diferencia entre `decline` y `revert`?**
`decline` registra que ningún PHI está en el ámbito y levanta la puerta de envío; se niega a tocar un BAA ejecutado. `revert` elimina por completo un acuerdo ejecutado o vencido, devolviendo la organización a `not_required` mientras conserva su historial de auditoría y el PDF almacenado. Ambos dejan entradas en la cadena de auditoría.

**¿Aceptan los endpoints un espejo de estado JSONB heredado?**
El flujo de `/api/v1/compliance/baa` es la ruta canónica. El espejo anterior `PUT /api/v1/settings/hipaa/baa` (documentado en [HIPAA compliance controls](/compliance/hipaa)) es un respaldo solo para inquilinos pre-migración; una vez que una organización tiene un valor de `baa_status`, las puertas leen la columna canónica e ignoran el espejo.

***

*Última actualización: septiembre de 2026*
*Para preguntas sobre el BAA, contacte: [compliance@devotel.io](mailto:compliance@devotel.io)*