Referencia de la API REST
Los endpoints de la API REST en la URL de tu empresa: el token Bearer, los límites de peticiones, el estado del servidor y los códigos de respuesta.
La API REST lee y escribe en Dinaup desde cualquier lenguaje. Cada empresa tiene su URL, https://<clave-de-conexion>.dinaup.io/api, con la clave de conexión en minúsculas. Play la muestra en Desarrollo → Inicio (Tu endpoint base), en Desarrollo → Conectar → Webhooks Entrantes (Endpoint Base) y en la tarjeta Cómo conectar de Administración → Claves API (Base URL).
Antes de empezar
- Una clave API con Compatible WebHook marcado, un empleado por defecto y las secciones que va a usar.
- La app Desarrollo con el interruptor Desarrollador en tu usuario, para copiar el token y probar. Ver Desarrollo.
Endpoints
Las rutas no distinguen mayúsculas y admiten una barra final. Una ruta bajo /api que no está en la tabla responde 404 sin cuerpo; otro método, 405.
| Método | Ruta | Para qué |
|---|---|---|
GET | /api/whoami | El usuario que hay detrás de la clave. |
POST | /api/reports | Ejecutar un informe de Flex. Informes y documentos |
POST | /api/dynamicdocuments | Renderizar un documento dinámico. |
POST | /api/writeoperations | Crear, editar y borrar registros. Escribir datos |
POST | /api/Register, /api/ActivateAccount, /api/RecoverPassword, /api/ChangePassword | Cuentas de tus usuarios finales. Usuarios finales |
POST | /api/Login, /api/Session, /api/Logout | Sesiones de tus usuarios finales. |
POST | /api/RequestLoginCode, /api/LoginWithCode | Inicio de sesión con un código de un solo uso. |
POST | /api/GetKV, /api/SetKV | Almacén clave-valor. |
GET | /ping, /version | Estado y versión del servidor. Fuera de /api y sin token. |
La especificación OpenAPI 3.1 de ping, version, whoami, reports, dynamicdocuments y writeoperations está en /openapi.yaml, para generar un cliente o dársela a un asistente de IA.
Los cuerpos van en JSON. Las respuestas también, en camelCase (currentPage, rowID, aError), salvo dynamicdocuments, /ping, /version y la mayoría de los errores, que llegan como texto.
El token Bearer
Toda petición a /api lleva Authorization: Bearer <token>. El token no es la clave API en crudo: se copia de Play.
- En Administración → Claves API, el botón de copiar de la tarjeta Cómo conectar copia la cabecera completa.
- En Desarrollo → Conectar → Webhooks Entrantes, elige la clave en Clave API y abre la pestaña Whoami: la vista previa curl lleva la cabecera. Ver Webhooks Entrantes.
El token valida si la clave tiene secreto, Compatible WebHook marcado y un empleado por defecto. Crear, cambiar o retirar una clave tarda hasta 120 segundos en aplicarse. Quien tiene el token lee y escribe con los permisos de la clave.
Sin token, con mal formato o sin clave que lo respalde, la respuesta es 401 con WWW-Authenticate: Bearer y un {"error": "..."} con uno de estos mensajes:
Bearer token was not provided.The provided token has an invalid format.The provided token is invalid.
reports y writeoperations comprueban los parámetros y el cuerpo antes que el token: un 400 suyo no confirma que el token valga.
| Endpoints | Actúan como |
|---|---|
whoami, reports, dynamicdocuments, writeoperations | El empleado por defecto de la clave, solo en las secciones de su lista blanca. |
| Cuentas y sesiones | El usuario final de tu aplicación. |
GetKV, SetKV | Nadie: leen y escriben los pares de tu empresa. |
Si la clave tiene activada su lista blanca de IPs, una petición desde otra IP recibe Firewall bloqueó la IP: <ip>.
Límites
Cada clave API tiene su propia cola. Una petición fuera de estos límites se rechaza sin ejecutarse:
| Límite | Valor | Al superarlo |
|---|---|---|
| Peticiones a la vez | Tantas como vCores tiene la clave (cabecera X-Dinaup-VCores de cada respuesta). Si tu licencia tiene un tope de vCores, todas las claves lo comparten. | Las demás esperan turno por orden de llegada. |
| Cola de la clave | 100 peticiones esperando turno. | 503, sin Retry-After. |
| Espera de turno | 30 segundos por defecto. Con la cabecera X-Dinaup-Timeout-Ms pides menos, 1000 como mínimo. | 503 con Retry-After: 2. |
| Ritmo | Solo si Dinaup fija un ritmo en tu licencia: peticiones por segundo y vCore, con 30 segundos de margen para ráfagas. La licencia entera puede tener su propio ritmo. | 429 con Retry-After (segundos, 1 como mínimo). |
| Tamaño del cuerpo | 1.232.896 bytes por defecto. | 413. |
Con 429 y 503, espera los segundos de Retry-After antes de repetir.
Cuánto usa cada clave y cómo va frente a sus límites: Uso de la API. La duración máxima y los registros por página de cada clave se ajustan en su ficha.
En vídeo: Protege tus integraciones: límite de ritmo y límite de tiempo por clave API.
Estado del servidor
/ping y /version cuelgan de la raíz de la URL, no de /api, y no piden token.
| Ruta | Respuesta |
|---|---|
GET /ping | 200 con pong. Mientras el servidor arranca, 503. |
GET /version | 200 con la versión del servidor en texto, también durante el arranque. |
curl "https://<clave-de-conexion>.dinaup.io/ping"GET /api/whoami: Usuario de la clave
Devuelve el empleado por defecto de la clave. Es la primera llamada de una integración: confirma que el token vale y con quién firmas.
curl "https://<clave-de-conexion>.dinaup.io/api/whoami" -H "Authorization: Bearer <token>"{ "user": "..." }Un 401 en los 120 segundos tras crear la clave es normal; después, revisa Compatible WebHook y el empleado por defecto. Si no llega respuesta, GET /ping dice si el servidor de tu empresa responde. Un rechazo del servidor llega con su 4xx y el motivo en texto; otro fallo, 500 sin cuerpo.
Leer y escribir
| Endpoint | Página |
|---|---|
POST /api/reports y POST /api/dynamicdocuments | Informes y documentos |
POST /api/writeoperations | Escribir datos |
Códigos de respuesta
| Código | Cuándo |
|---|---|
200 | Operación correcta. En un lote de writeoperations, revisa cada fila. |
400 | Parámetros o cuerpo inválidos. El cuerpo lleva el motivo. |
401 | Token ausente o inválido, con WWW-Authenticate: Bearer. |
404 | La ruta no existe bajo /api. Sin cuerpo. |
405 | Método incorrecto para la ruta. |
413 | El cuerpo pasa del tamaño máximo. |
415 | Falta Content-Type: application/json en writeoperations o en los endpoints de usuarios finales. |
429 | Ritmo agotado. Repite pasados los segundos de Retry-After. |
4xx del servidor | El servidor de tu empresa rechaza la petición con su mensaje: un campo o un valor que no valen, un informe o un documento que no existe, un permiso que falta. |
500 | Fallo al ejecutar, como un registro suelto que no se pudo guardar. El cuerpo lleva el motivo. |
503 | El servidor arranca, la base de datos no responde (Retry-After: 5), la cola de la clave está llena o el turno no llegó a tiempo (Retry-After: 2). |
Las llamadas que fallan al ejecutarse quedan en Errores API, con su función, su clave API, su IP y el motivo.