Dinaup DocsAPI REST: cómo funciona
Qué hay detrás de una llamada a la API REST: la URL de tu empresa, cómo se compone el token Bearer, el camino de una petición, con qué permisos se ejecuta y qué límites tiene.
La API REST lee y escribe en Dinaup desde cualquier lenguaje o plataforma. Tu sistema llama a la URL de tu empresa con un token, y el servidor de tu empresa ejecuta la operación y responde. El detalle de cada endpoint está en Referencia de la API REST y en Usuarios finales.
Antes de empezar
- Una clave API creada por un administrador en Administración → Claves API, con Compatible WebHook marcado, un empleado por defecto y las secciones que va a usar.
- La app Desarrollo de Play con el interruptor Desarrollador en tu usuario, para copiar la URL y el token. Ver Desarrollo.
La URL de tu empresa
La API responde en https://<clave-de-conexion>.dinaup.io/api, con la clave de conexión de tu empresa en minúsculas. La sirve el servidor de tu empresa: cada empresa llama a la suya. Play la muestra en Desarrollo → Inicio, en Tu endpoint base, y en Desarrollo → Conectar → Webhooks Entrantes, en Endpoint Base.
El token Bearer
El token no es la clave API en crudo: se copia de Play. En Administración → Claves API, la tarjeta Cómo conectar muestra la cabecera Authorization: Bearer <token> y su botón de copiar la pone completa en el portapapeles. Ver Claves API. También la muestra Desarrollo → Conectar → Webhooks Entrantes: elige la clave en Clave API y abre la pestaña Whoami, cuya vista previa curl lleva la cabecera completa. Ver Webhooks Entrantes.
Para que el token valide, la clave tiene que cumplir tres condiciones: tener secreto, tener Compatible WebHook marcado y tener un empleado por defecto. Un cambio en la clave (crearla, cambiar sus permisos, retirarla) tarda hasta 120 segundos en aplicarse.
El token vive en tu servidor
Quien tiene el token lee y escribe con los permisos de la clave. Guárdalo en la configuración de tu backend o en un gestor de secretos, nunca en el JavaScript de una web ni en un repositorio. Si delante hay un navegador, pon un Cloudflare Worker o tu propio backend en medio.
El camino de una petición
| Paso | Qué ocurre |
|---|---|
| 1 | La petición llega al servidor de tu empresa. El servidor reconoce la clave por el token y aplica sus límites: con la cola de la clave llena, 503; con el ritmo de la clave agotado, 429. |
| 2 | La petición espera turno en la cola de su clave. La clave atiende a la vez tantas peticiones como vCores tiene. |
| 3 | El servidor comprueba los parámetros y el token. Un token que no corresponde a ninguna clave activa recibe 401. |
| 4 | Ejecuta la operación. Los endpoints de datos firman como el empleado por defecto de la clave; los de cuentas y sesiones actúan como el usuario final. |
| 5 | Responde en JSON, salvo dynamicdocuments y la mayoría de los errores, que responden en texto. |
Con qué permisos se ejecuta
- Las lecturas y escrituras de datos (
whoami,reports,dynamicdocuments,writeoperations) van a nombre del empleado por defecto de la clave. Solo alcanzan las secciones de su lista blanca, que se acota en la ficha de la clave. - Las cuentas y las sesiones actúan como el usuario final de tu aplicación, con su propia identidad, no como el empleado.
- El clave-valor no depende de ningún usuario: lee y escribe los pares de tu empresa.
- Si la clave tiene activada su lista blanca de IPs, una petición desde otra IP recibe el rechazo
Firewall bloqueó la IP: <ip>.
Las familias de endpoints
| Familia | Endpoints | Página |
|---|---|---|
| Datos | GET /api/whoami, POST /api/reports, POST /api/dynamicdocuments, POST /api/writeoperations | Referencia de la API REST |
| Usuarios finales | POST /api/Register, ActivateAccount, RecoverPassword, ChangePassword, Login, Session, Logout, RequestLoginCode, LoginWithCode, GetKV, SetKV | Usuarios finales |
| Estado | GET /ping y GET /version, fuera de /api y sin token | Estado del servidor |
Límites y errores
Cada clave tiene su cola: atiende a la vez tantas peticiones como vCores tiene y deja esperando turno hasta 100. Con la cola llena, o sin turno a tiempo (30 segundos por defecto), la respuesta es 503. Si Dinaup fija un ritmo en tu licencia, la clave que lo agota recibe 429 con Retry-After.
| Código | Qué ha pasado |
|---|---|
401 | El token falta, tiene mal formato o no coincide con ninguna clave. |
404 | La ruta no existe bajo /api. |
4xx del servidor | El servidor de tu empresa rechazó la petición: permisos, informe o documento inexistente, un campo o un valor que no valen, sesión caducada. |
429 | Ritmo de la clave agotado. |
500 | Fallo al ejecutar la operación. |
503 | El servidor arranca, la cola de la clave está llena o el turno no llegó a tiempo. |
Las cifras y los mensajes exactos están en Referencia de la API REST.
Probar la conexión
La primera llamada es whoami: confirma que el token vale y con qué empleado firmas.
curl "https://<clave-de-conexion>.dinaup.io/api/whoami" -H "Authorization: Bearer <token>"Un 200 con { "user": "..." } es la conexión hecha. Un 401 recién creada la clave es normal durante 120 segundos; después, revisa Compatible WebHook y el empleado por defecto en la ficha de la clave. Si no llega ninguna respuesta, GET /ping sin token dice si el servidor de tu empresa responde.
Para no usar la terminal, el playground de Play lanza las mismas llamadas desde el navegador: Webhooks Entrantes. Las llamadas que fallan al ejecutarse quedan en Errores API, con su función, su clave API, su IP y el motivo.
Relacionado
- Conectar tu primera integración: de la clave al primer flujo.
- Webhooks salientes: la dirección contraria, Dinaup avisa a tu servidor.
- SDK .NET: el cliente .NET con clases tipadas, con su propia conexión.