API REST -- Referencia de Endpoints

La API REST de Dinaup permite interactuar con tus datos de forma programatica. Todos los endpoints se sirven desde https://webhook.dinaup.com.

Autenticacion

Todos los endpoints (excepto el ping) requieren una Clave API de usuario en el header HTTP:

Authorization: Bearer <clave-api>

Las claves API se generan desde dinaup.com > Claves API. Cada clave hereda los permisos del usuario al que pertenece, por lo que solo podra acceder a los datos que ese usuario tiene permiso de ver.

Seguridad

Nunca compartas tus claves API en codigo publico ni en el frontend de aplicaciones web. Usalas exclusivamente en el backend.

→ Generar claves API

`GET /` -- Ping

Verifica que el servidor de webhooks esta operativo. No requiere autenticacion.

Request:

curl -X GET "https://webhook.dinaup.com"

Response: 200 OK

"Hola :)"

`GET /api/whoami` -- Informacion del usuario

Devuelve los datos del usuario asociado a la clave API. Util para verificar que la autenticacion funciona correctamente.

Request:

curl -X GET "https://webhook.dinaup.com/api/whoami" \
  -H "Authorization: Bearer <clave-api>"

Response: 200 OK con los datos del usuario (nombre, email, permisos).

Limites de tasa (Rate Limiting)

Cada endpoint tiene un limite de peticiones por tenant (identificado por el Bearer Token):

Endpoint	Tokens	Reposicion	Periodo
WriteOperations	30	5 tokens	10 seg
Reports	30	5 tokens	10 seg
DynamicDocuments	30	5 tokens	10 seg
Whoami	60	10 tokens	10 seg
Herramientas (AEAT/VIES)	10	2 tokens	10 seg

Si excedes el limite, recibiras un error 429 Too Many Requests con un header Retry-After: 10.

`POST /api/reports` -- Consultar informes

Ejecuta un informe de Dinaup Flex y devuelve los resultados en formato JSON. Los informes se configuran previamente en Dinaup Flex con las columnas, filtros y agrupaciones deseadas.

Parametros (query string)

Parametro	Tipo	Obligatorio	Descripcion
`id`	UUID	Si	ID del informe a consultar
`page`	int	No	Numero de pagina (por defecto: 1)
`resultsPerPage`	int	No	Resultados por pagina (por defecto: 10)
`withFiles`	bool	No	Incluir URLs de archivos adjuntos (por defecto: false)
`safeColumnsName`	bool	No	Usar GUIDs como nombres de columna para estabilidad (por defecto: false)

Body (opcional)

JSON con variables de filtro si el informe tiene preguntas dinamicas:

{
  "variableFiltro1": "valor1",
  "variableFiltro2": "valor2"
}

Request

curl -X POST "https://webhook.dinaup.com/api/reports?id=5b3b317c-0513-4ab8-9724-903100edea76&page=1&resultsPerPage=100&withFiles=false&safeColumnsName=false" \
  -H "Authorization: Bearer <clave-api>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "data": [
    {"columna1": "valor1", "columna2": "valor2"},
    {"columna1": "valor3", "columna2": "valor4"}
  ],
  "currentPage": 1,
  "totalPages": 5,
  "totalResults": 42,
  "files": []
}

Recomendaciones para informes

Activa safeColumnsName=true en produccion para que los nombres de columna no cambien si se renombra un campo en Dinaup.
Si el informe tiene preguntas dinamicas, puedes pasar los valores como parametros adicionales en la URL para filtrar los resultados (por ejemplo, filtrar ventas por cliente o por rango de fechas).
Los resultados estan paginados. Usa page y resultsPerPage para iterar sobre conjuntos grandes de datos.

`POST /api/dynamicdocuments` -- Documentos dinamicos

Genera un documento dinamico y devuelve su contenido renderizado. Los documentos dinamicos son plantillas que combinan datos de diferentes secciones en formatos como HTML, JSON o texto plano.

Parametros (query string)

Parametro	Tipo	Obligatorio	Descripcion
`id`	UUID	Si	ID del documento dinamico

Body (opcional)

JSON con variables para sustituir en la plantilla:

{
  "nombreVariable1": "valor1",
  "nombreVariable2": "valor2"
}

Request

curl -X POST "https://webhook.dinaup.com/api/dynamicdocuments?id=3db0df5f-af7f-4183-af9d-f561976fb61a" \
  -H "Authorization: Bearer <clave-api>" \
  -H "Content-Type: application/json" \
  -d '{"clienteId": "abc-123"}'

Response

{
  "document": "Contenido renderizado del documento...",
  "data": {
    "clienteId": "abc-123"
  }
}

`POST /api/writeoperations` -- Escribir datos

Crea, edita o elimina registros en cualquier seccion de Dinaup. Este es el endpoint mas critico de la API.

Parametros (query string)

Parametro	Tipo	Obligatorio	Descripcion
`sectionId`	UUID	Si	ID de la seccion donde escribir
`FieldPrimary`	string	Si	Nombre del campo clave para identificar registros
`scripts`	bool	No	Ejecutar scripts del servidor asociados a la seccion (por defecto: false)

Headers

Authorization: Bearer <clave-api>
Content-Type: application/json

Crear, editar y eliminar

Regla critica: el valor de id determina la operacion

Valor de `id`	Operacion	Descripcion
`""` (cadena vacia)	Crear	Se crea un nuevo registro. Dinaup genera el ID automaticamente
UUID existente	Editar	Se actualizan los campos enviados del registro con ese ID
UUID inexistente	Error	Devuelve error. No se puede editar un registro que no existe

Para eliminar un registro, envia una operacion de edicion con el campo eliminado establecido a 1:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "eliminado": "1"
}

Eliminacion logica

No existe un endpoint DELETE separado. La eliminacion es logica (soft delete) y se realiza mediante WriteOperations.

Nombres de campo (`pr_*`)

Los campos se identifican por su columna PostgreSQL, que tiene formato pr_XXXXXXXXX. Puedes consultar los nombres de campo de cada seccion desde:

Play Dinaup > modulo Desarrollo > Esquema
Dinaup Desktop (app Windows) > configuracion de la seccion
doc-flex.dinaup.com > referencia completa de todas las secciones
SDK .NET (MyDinaup) > todos los campos estan tipados con nombres legibles

Formato 1: Objeto simple

Envia un solo registro como diccionario de campos:

{
  "id": "",
  "pr_60040105651": "id-del-cliente",
  "pr_500401055323": "100.00"
}

"id": "" crea un nuevo registro. Para editar, usa el UUID del registro existente.

Formato 2: Objeto con lista (padre + hijos)

Para secciones que tienen una seccion lista asociada (ej: Factura + Lineas de factura):

{
  "Main": {
    "id": "",
    "pr_60040105651": "id-del-cliente"
  },
  "List": [
    {"pr_item": "producto-1", "pr_cantidad": "10"},
    {"pr_item": "producto-2", "pr_cantidad": "20"}
  ]
}

Formato 3: Lote de objetos

Envia multiples registros en una sola peticion:

[
  {"id": "", "pr_campo1": "valor1"},
  {"id": "", "pr_campo1": "valor2"}
]

Formato 4: Lote de objetos con listas

Multiples registros padre-hijo en una sola peticion:

[
  {
    "Main": {"id": "", "pr_campo": "valor1"},
    "List": [{"pr_item": "val1"}]
  },
  {
    "Main": {"id": "", "pr_campo": "valor2"},
    "List": [{"pr_item": "val2"}]
  }
]

Ejemplo completo (crear un registro)

curl -X POST "https://webhook.dinaup.com/api/writeoperations?sectionId=0ce4c6ac-54aa-488d-b8b8-e3a20d79f7a4&FieldPrimary=id&scripts=true" \
  -H "Authorization: Bearer <clave-api>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "",
    "pr_60040105651": "id-del-cliente",
    "pr_500401055323": "100.00"
  }'

Permisos

Las operaciones de escritura respetan los permisos del usuario asociado a la clave API. Si el usuario no tiene permiso de escritura en una seccion, la operacion fallara.

Herramientas auxiliares

`GET /api/tools/aeat` -- Validacion NIF/CIF

Valida un NIF o CIF contra el censo de la Agencia Estatal de Administracion Tributaria (AEAT). Util para verificar que un numero de identificacion fiscal es valido antes de registrar un cliente.

`GET /api/tools/vies` -- Validacion VIES

Valida un numero de identificacion fiscal intracomunitario contra el sistema VIES de la Union Europea. Util para verificar que un cliente es operador intracomunitario antes de emitir una factura con IVA al 0%.

Codigos de respuesta

Codigo	Significado
`200`	Operacion exitosa
`401`	Clave API invalida o ausente
`403`	El usuario no tiene permisos para esta operacion
`404`	Recurso no encontrado (informe, documento, seccion)
`422`	Datos de entrada invalidos (campos obligatorios, formato incorrecto)
`429`	Limite de tasa excedido (espera el tiempo indicado en `Retry-After`)
`500`	Error interno del servidor

Playground

Prueba todos los endpoints directamente desde Dinaup sin configurar herramientas externas:

Abrir Playground de Webhooks

Autenticacion​

GET / -- Ping​

GET /api/whoami -- Informacion del usuario​

Limites de tasa (Rate Limiting)​

POST /api/reports -- Consultar informes​

Parametros (query string)​

Body (opcional)​

Request​

Response​

POST /api/dynamicdocuments -- Documentos dinamicos​

Parametros (query string)​

Body (opcional)​

Request​

Response​

POST /api/writeoperations -- Escribir datos​

Parametros (query string)​

Headers​

Crear, editar y eliminar​

Nombres de campo (pr_*)​

Formato 1: Objeto simple​

Formato 2: Objeto con lista (padre + hijos)​

Formato 3: Lote de objetos​

Formato 4: Lote de objetos con listas​

Ejemplo completo (crear un registro)​

Herramientas auxiliares​

GET /api/tools/aeat -- Validacion NIF/CIF​

GET /api/tools/vies -- Validacion VIES​

Codigos de respuesta​

Playground​

Autenticacion

`GET /` -- Ping

`GET /api/whoami` -- Informacion del usuario

Limites de tasa (Rate Limiting)

`POST /api/reports` -- Consultar informes

Parametros (query string)

Body (opcional)

Request

Response

`POST /api/dynamicdocuments` -- Documentos dinamicos

Parametros (query string)

Body (opcional)

Request

Response

`POST /api/writeoperations` -- Escribir datos

Parametros (query string)

Headers

Crear, editar y eliminar

Nombres de campo (`pr_*`)

Formato 1: Objeto simple

Formato 2: Objeto con lista (padre + hijos)

Formato 3: Lote de objetos

Formato 4: Lote de objetos con listas

Ejemplo completo (crear un registro)

Herramientas auxiliares

`GET /api/tools/aeat` -- Validacion NIF/CIF

`GET /api/tools/vies` -- Validacion VIES

Codigos de respuesta

Playground