Conectar tu primera integración

De la clave API a un flujo en marcha: copiar la URL y el token, comprobar la conexión con whoami, leer un informe, escribir un registro y recibir el primer aviso.

Al terminar, tu sistema lee y escribe en Dinaup por la API REST, y Dinaup avisa a tu sistema con un webhook saliente. Los ejemplos van con curl; valen para cualquier lenguaje y para el módulo HTTP de Zapier, Make o n8n.

Antes de empezar

Un Administrador de la empresa para crear la clave API. Ver Claves API.
La app Desarrollo en la licencia y el interruptor Desarrollador en tu usuario para copiar la URL y el token y para probar. Ver Desarrollo.
Decidido qué secciones va a tocar la integración.

Las tres formas de conectar

Quieres	Usa	Dirección
Leer informes o escribir registros desde tu código	API REST, o el SDK .NET si programas en .NET	Tú a Dinaup
Enterarte en el momento de que algo cambia	Webhooks salientes	Dinaup a ti
Conectar con otras apps sin programar	Zapier, Make y n8n sobre las dos anteriores	Las dos

El mapa completo de canales está en Integraciones.

El recorrido

Crea una clave API acotada

En Play, en Administración → Claves API, pulsa el botón + de la lista. Ponle el nombre de la integración, elige el empleado que firma sus escrituras, acota las secciones que va a usar y marca Compatible WebHook. Una clave por integración: si una se filtra, la retiras sin tocar las demás.

Los cambios en una clave tardan hasta 120 segundos en aplicarse.

Copia la URL y el token Bearer

En Desarrollo → Conectar → Webhooks Entrantes, la tarjeta Referencia de endpoints muestra el Endpoint Base: la URL de tu empresa, https://<clave-de-conexion>.dinaup.io/api. Elige la clave en Clave API y abre la pestaña Whoami: la vista previa curl muestra la cabecera Authorization: Bearer <token> completa. Guarda la URL y el token en la configuración de tu servidor o en un gestor de secretos.

Comprueba la conexión

curl "https://<clave-de-conexion>.dinaup.io/api/whoami" -H "Authorization: Bearer <token>"

Un 200 con { "user": "..." } confirma el token y el empleado. Un 401 durante los primeros 120 segundos es normal; después, revisa Compatible WebHook y el empleado por defecto en la ficha de la clave. Si no llega ninguna respuesta, prueba https://<clave-de-conexion>.dinaup.io/ping, sin token: responde pong si el servidor de tu empresa está en marcha.

Lee un informe

Prepara el informe en FlexHub → Informes con sus columnas y filtros. Copia su identificador de Desarrollo → Esquema, pestaña Informes, columna ID. Después ejecútalo:

curl -X POST "https://<clave-de-conexion>.dinaup.io/api/reports?id=<id-del-informe>&page=1&resultsPerPage=100&safeColumnsName=true" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{}"

Las filas llegan en data. Para recorrer el informe, pide páginas hasta que llegue una con menos filas que resultsPerPage: totalResults llega siempre a 0. Con safeColumnsName=true las columnas se nombran por su GUID y renombrar un campo no rompe tu código.

Escribe un registro

Copia el identificador de la sección y los nombres pr_... de sus campos en Desarrollo → Esquema. Un id vacío crea el registro:

curl -X POST "https://<clave-de-conexion>.dinaup.io/api/writeoperations?sectionId=<id-de-la-seccion>&FieldPrimary=id&scripts=true" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d "{\"id\": \"\", \"pr_campo\": \"valor\"}"

Comprueba confirmed y aError en la respuesta. Para probar sin tocar datos reales, la sección Zona de pruebas tiene campos de todos los tipos.

Recibe el primer aviso

En Desarrollo → Conectar → Webhooks Salientes, pulsa Nuevo: elige la sección, marca Disparar nuevos, pega la URL de tu servidor y rellena Bearer Token con un secreto que tu servidor compruebe. Con el simulador de la misma pantalla envía un registro de prueba y confirma que llega el POST con previousData y newData.

Buenas prácticas

Práctica	Por qué
Una clave por integración, acotada a sus secciones	Retiras o limitas una sin afectar al resto, y una filtración alcanza solo lo que esa clave ve.
El token solo en el servidor	Nunca en el JavaScript de una web ni en un repositorio. Si hace falta llamar desde el navegador, un Cloudflare Worker en medio.
Pagina con `calculatePages=false` y activa `safeColumnsName`	Sin recuento, cada página responde antes; los nombres por GUID no se rompen al renombrar campos.
Espera antes de repetir un `429` o un `503`	La clave atiende a la vez tantas peticiones como vCores tiene; repetir sin esperar alarga la cola. Cuando viene, `Retry-After` dice cuántos segundos esperar.
Responde `2xx` a los webhooks en menos de 30 segundos	Pasado ese tiempo Dinaup cuenta el aviso como fallido y lo intenta hasta 3 veces en total.
Comprueba el Bearer Token de cada aviso	Descartas lo que no viene de Dinaup.
Revisa Errores API	Las llamadas que fallan al ejecutarse quedan anotadas con su función, su clave API, su IP y el motivo.

Relacionado

API REST: cómo funciona: la URL, el token y el camino de una petición.
Referencia de la API REST: cada endpoint con sus parámetros.
Webhooks salientes: condiciones de disparo, cuerpo y reintentos.

En esta página