> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpolicy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Vista general de la API REST de ClearPolicy

> La API REST de ClearPolicy se comunica por HTTPS y devuelve JSON. Conoce la URL base, el versionado, el formato de paginación, el formato de los IDs y las respuestas de error.

La API REST de ClearPolicy te da acceso programático a las personas, los documentos y las solicitudes de acuse de recibo de tu organización. Todos los endpoints se comunican por HTTPS y devuelven JSON.

## URL base

```text theme={null}
https://api.clearpolicy.app/api/v1
```

El prefijo de ruta de la API (`/api/v1`) se incluye en cada URL de solicitud. La versión actual y única es `v1`.

## Autenticación

Todos los endpoints requieren un token portador de API válido. Pasa el token en el encabezado `Authorization`:

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

Consulta [Autenticación](/api/authentication) para conocer las instrucciones para crear un token.

<Note>
  Tu organización debe tener una suscripción activa o estar dentro de su periodo de prueba. Si tu prueba ha caducado o tu suscripción está inactiva, todas las solicitudes de la API devuelven una respuesta `402 Payment Required`.
</Note>

## Acceso por rol

El acceso a la API sigue tu rol en ClearPolicy. Los propietarios y administradores de la organización pueden crear tokens de API y utilizar los endpoints de personas, documentos y solicitudes de acuse de recibo. Los tokens vinculados a gestores de grupo pueden utilizar `GET /me` para confirmar el token y la organización, pero los demás endpoints de la API REST devuelven `403 Forbidden`.

## Formato de respuesta

Todas las respuestas son JSON. Las respuestas correctas devuelven el recurso o la colección solicitados directamente en el cuerpo de la respuesta.

## IDs

Todos los IDs de recursos son [ULIDs](https://github.com/ulid/spec) — identificadores en forma de cadena ordenables lexicográficamente. Se representan como cadenas en minúsculas, por ejemplo:

```text theme={null}
01kg82xqfx6fvr046d15hnfmjv
```

## Paginación

Los endpoints de listas devuelven resultados paginados. La respuesta incluye un array `data` junto con los objetos `links` y `meta`:

```json theme={null}
{
  "data": [...],
  "links": {
    "first": "https://api.clearpolicy.app/api/v1/people?page=1",
    "last": "https://api.clearpolicy.app/api/v1/people?page=5",
    "prev": null,
    "next": "https://api.clearpolicy.app/api/v1/people?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}
```

Usa los parámetros de consulta `page` y `per_page` para navegar por los resultados. `per_page` acepta valores entre 1 y 100, y el valor predeterminado es 25.

## Errores

Los errores devuelven JSON con un campo `error` que describe el problema:

```json theme={null}
{
  "error": "Person not found."
}
```

Códigos de estado HTTP comunes:

| Estado                     | Significado                                                                                                                 |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`                   | Solicitud correcta.                                                                                                         |
| `201 Created`              | Recurso creado correctamente.                                                                                               |
| `400 Bad Request`          | La solicitud no era válida (p. ej., documento no publicado).                                                                |
| `401 Unauthorized`         | Falta el token de acceso o no es válido.                                                                                    |
| `402 Payment Required`     | La prueba de tu organización ha caducado o la suscripción no está activa. Visita tu página de facturación para suscribirte. |
| `403 Forbidden`            | El token no tiene los permisos requeridos.                                                                                  |
| `404 Not Found`            | El recurso solicitado no existe en tu organización.                                                                         |
| `422 Unprocessable Entity` | La validación falló — comprueba los parámetros de la solicitud.                                                             |
| `429 Too Many Requests`    | Se superó el límite de tasa — espera y vuelve a intentarlo.                                                                 |

## Limitación de tasa

Cada token de API está limitado a **60 solicitudes por minuto**. Los límites se aplican por token, no por organización, así que varios tokens tienen cada uno su propia cuota.

Si superas el límite, la API devuelve `429 Too Many Requests`. Las respuestas incluyen las cabeceras `Retry-After` y `X-RateLimit-*` para que sepas cuándo reintentar. Usa retroceso exponencial al reintentar.