Vista general de la API REST de ClearPolicy

La API REST de ClearPolicy te da acceso programático a las personas, los grupos, 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

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:

Authorization: Bearer YOUR_ACCESS_TOKEN

Consulta Autenticación para conocer las instrucciones para crear un token.

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.

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, grupos, 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 — identificadores en forma de cadena ordenables lexicográficamente. Se representan como cadenas en minúsculas, por ejemplo:

01kg82xqfx6fvr046d15hnfmjv

Paginación

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

{
  "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:

{
  "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.

Vista general

Me

Personas

Documentos

Grupos

Solicitudes de acuse de recibo

Vista general de la API REST de ClearPolicy

URL base

Autenticación

Acceso por rol

Formato de respuesta

IDs

Paginación

Errores

Limitación de tasa

​URL base

​Autenticación

​Acceso por rol

​Formato de respuesta

​IDs

​Paginación

​Errores

​Limitación de tasa

URL base

Autenticación

Acceso por rol

Formato de respuesta

IDs

Paginación

Errores

Limitación de tasa