Skip to Content

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étodoRutaPara qué
GET/api/whoamiEl usuario que hay detrás de la clave.
POST/api/reportsEjecutar un informe de Flex. Informes y documentos
POST/api/dynamicdocumentsRenderizar un documento dinámico.
POST/api/writeoperationsCrear, editar y borrar registros. Escribir datos
POST/api/Register, /api/ActivateAccount, /api/RecoverPassword, /api/ChangePasswordCuentas de tus usuarios finales. Usuarios finales
POST/api/Login, /api/Session, /api/LogoutSesiones de tus usuarios finales.
POST/api/RequestLoginCode, /api/LoginWithCodeInicio de sesión con un código de un solo uso.
POST/api/GetKV, /api/SetKVAlmacén clave-valor.
GET/ping, /versionEstado 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.

EndpointsActúan como
whoami, reports, dynamicdocuments, writeoperationsEl empleado por defecto de la clave, solo en las secciones de su lista blanca.
Cuentas y sesionesEl usuario final de tu aplicación.
GetKV, SetKVNadie: 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ímiteValorAl superarlo
Peticiones a la vezTantas 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 clave100 peticiones esperando turno.503, sin Retry-After.
Espera de turno30 segundos por defecto. Con la cabecera X-Dinaup-Timeout-Ms pides menos, 1000 como mínimo.503 con Retry-After: 2.
RitmoSolo 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 cuerpo1.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.

RutaRespuesta
GET /ping200 con pong. Mientras el servidor arranca, 503.
GET /version200 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

EndpointPágina
POST /api/reports y POST /api/dynamicdocumentsInformes y documentos
POST /api/writeoperationsEscribir datos

Códigos de respuesta

CódigoCuándo
200Operación correcta. En un lote de writeoperations, revisa cada fila.
400Parámetros o cuerpo inválidos. El cuerpo lleva el motivo.
401Token ausente o inválido, con WWW-Authenticate: Bearer.
404La ruta no existe bajo /api. Sin cuerpo.
405Método incorrecto para la ruta.
413El cuerpo pasa del tamaño máximo.
415Falta Content-Type: application/json en writeoperations o en los endpoints de usuarios finales.
429Ritmo agotado. Repite pasados los segundos de Retry-After.
4xx del servidorEl 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.
500Fallo al ejecutar, como un registro suelto que no se pudo guardar. El cuerpo lleva el motivo.
503El 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.

En esta página