# Destinatarios

> Objeto destinatario, roles, autenticación y orden de firma.

Un destinatario (`recipient`) representa a una persona involucrada en un envelope — quien firma, aprueba, o solo recibe una copia. La [Guía de Integración](/guides/integration-guide/#1-crear-el-envelope-y-los-firmantes) muestra cómo crear destinatarios al crear el envelope; este recurso profundiza en el objeto y las operaciones sobre destinatarios ya creados.

## Roles

| Rol | Comportamiento |
|---|---|
| `SIGNER` | Debe firmar. Sus campos requeridos deben completarse. |
| `APPROVER` | Debe aprobar antes de que los `SIGNER` con `signingOrder` mayor puedan firmar. |
| `VIEWER` | Puede ver el documento, no realiza ninguna acción. |
| `CC` | Recibe una copia del documento completado, no participa del proceso. |
| `ASSISTANT` | Puede completar campos en nombre de otro destinatario. |

## Crear destinatarios

```http
POST /envelope/recipient/create-many
```

Cada destinatario acepta `email`, `name`, `role`, y opcionalmente `signingOrder`, `accessAuth` y `actionAuth`.

Ver la especificación completa en la [Referencia de la API](/api/operations/envelope-recipient-createmany/).

### Orden de firma

Con firma secuencial, los destinatarios con `signingOrder` más bajo firman primero; los que comparten el mismo valor pueden firmar en simultáneo. Para habilitar firma secuencial, define `signingOrder: "SEQUENTIAL"` en el `meta` del envelope — ver [Crear el envelope](/guides/integration-guide/#1-crear-el-envelope-y-los-firmantes).

### Autenticación de destinatarios

Para reforzar la seguridad de un destinatario en particular, más allá de la autenticación general de la API:

| `accessAuth` (para ver el documento) | Descripción |
|---|---|
| `ACCOUNT` | El destinatario debe tener sesión iniciada. |
| `TWO_FACTOR_AUTH` | El destinatario debe verificar con 2FA. |

| `actionAuth` (para firmar) | Descripción |
|---|---|
| `ACCOUNT` | El destinatario debe tener sesión iniciada. |
| `PASSKEY` | Requiere autenticación con passkey. |
| `TWO_FACTOR_AUTH` | Requiere código 2FA. |
| `PASSWORD` | Requiere verificación con contraseña. |
| `EXPLICIT_NONE` | Desactiva explícitamente la autenticación de acción. |
| `CLAVE_UNICA` | Requiere verificar la identidad del destinatario con ClaveÚnica. |
| `FAO_HASH` | Verificación asociada a Firma Electrónica Avanzada — ver [Firma Electrónica Avanzada](/guides/fea-orquestacion/). |

<Aside type="note" title="RUT y Firma Electrónica Avanzada">
	Para destinatarios en un envelope con FEA, se agrega la propiedad `rut` (identidad a verificar contra la entidad certificadora) y el orden de firma pasa a ser obligatoriamente secuencial. Ver el capítulo de [Firma Electrónica Avanzada](/guides/fea-orquestacion/#2-crear-el-envelope-y-los-firmantes).
</Aside>

## Actualizar destinatarios

```http
POST /envelope/recipient/update-many
```

Solo disponible mientras el envelope no está `COMPLETED`. Acepta los mismos campos que la creación, todos opcionales salvo el `id` del destinatario a modificar.

Ver la especificación completa en la [Referencia de la API](/api/operations/envelope-recipient-updatemany/).

## Eliminar un destinatario

```http
POST /envelope/recipient/delete
```

Ver la especificación completa en la [Referencia de la API](/api/operations/envelope-recipient-delete/).

## Rechazar en nombre de un destinatario

```http
POST /envelope/recipient/{recipientId}/reject
```

Marca a un destinatario como `REJECTED` sin pasar por el flujo normal de firma — por ejemplo, si te informan el rechazo por un canal fuera de Legaldoc y necesitas reflejarlo en el envelope.

Ver la especificación completa en la [Referencia de la API](/api/operations/envelope-recipient-rejectonbehalfof/).

## Consultar un destinatario

```http
GET /envelope/recipient/{recipientId}
```

Devuelve el objeto completo, incluyendo `signingStatus` (`NOT_SIGNED`, `SIGNED`, `REJECTED`), `readStatus` (`NOT_OPENED`, `OPENED`) y `sendStatus` (`NOT_SENT`, `SENT`).

Ver la especificación completa en la [Referencia de la API](/api/operations/envelope-recipient-get/).

---

## Ver también

- [Campos](/resources/fields/) — asignar campos a cada destinatario
- [Guía de Integración](/guides/integration-guide/) — flujo completo de creación y firma
- [Firma Electrónica Avanzada](/guides/fea-orquestacion/) — RUT, orden secuencial y validación de identidad