REST API

La API REST está disponible en /api/v1 y es adecuada para scripts, servicios internos, CI, exportaciones y otra automatización de servidor.

Para los endpoints protegidos se necesita un token de API personal. La solicitud se ejecuta en nombre del usuario que emitió el token y pasa las mismas comprobaciones de roles y permisos.

Autorización

Envía el token en el encabezado HTTP:

Authorization: Bearer <token>

Cómo emitir, almacenar y revocar los tokens se describe en el artículo Tokens de API.

Ejemplo de solicitud

curl -sS "$PLATFORM_BASE_URL/api/v1/{org}/surveys" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $PLATFORM_API_TOKEN"

Reemplaza {org} por el ID de la organización. Consulta los parámetros del endpoint concreto, el formato de la respuesta y los códigos de error en la especificación completa.

Límites de solicitudes

La API está protegida contra sobrecarga mediante una limitación de frecuencia:

• API autorizada de la aplicación: 300 solicitudes por minuto por usuario o IP.
• Webhook del proveedor de pagos: 600 solicitudes por minuto.
• Endpoints públicos (/status, tarjetas de la base de conocimientos): 300 solicitudes por minuto por IP.

Al superar el límite, el servidor devuelve HTTP 429 Too Many Requests con el encabezado Retry-After (número de segundos hasta reintentar) y el cuerpo del error:

{
  "status": 429,
  "message": "Demasiadas solicitudes. Inténtalo de nuevo en 30 segundos.",
  "errors": {}
}

Documentación completa

• Referencia de OpenAPI: documentación interactiva sobre endpoints, parámetros y esquemas de respuestas.
• OpenAPI JSON: esquema legible por máquina para generadores de clientes, Postman, Insomnia y verificaciones de contratos.