Desarrolladores

API: conceptos básicos

La API de VentionDesk es la misma que usa la interfaz. Para automatizaciones — Claude, tus propios scripts, CI — inicias sesión con una clave de API. Todas las URL empiezan por https://api.ventiondesk.com; todos los cuerpos y respuestas son JSON en UTF-8.

Iniciar sesión con una clave de API

El propietario crea una clave en Ajustes › Claves de API › «Nueva clave». Aparece en texto claro una sola vez.

Cada solicitud la lleva como token bearer:

curl https://api.ventiondesk.com/v1/tasks?status=todo \
  -H "Authorization: Bearer vd_live_…"

No hay un endpoint aparte para canjearla: VentionDesk reconoce la clave por su prefijo, la comprueba en cada solicitud (¿revocada? ¿caducada?) y después trabaja con una sesión para la cuenta de esa clave. A la clave se le aplican, por tanto, las mismas reglas de la base de datos que a una persona: solo ve lo que permite su alcance.

Prefijo	Tipo	Para qué
`vd_live_`	agente	tomar tareas e informar de ellas, leer proyectos, escribir notas, MCP
`vd_intake_`	entrada	solo enviar tickets (`POST /v1/intake/tickets`), consulta Entrada de tickets
`vd_pub_`	clave pública del proyecto	no es una clave de inicio de sesión: está en formularios y apps web y solo puede enviar avisos a un proyecto

En lugar de una clave, también puede llegar como token bearer el inicio de sesión de una app de IA conectada mediante OAuth. Cuenta como una clave de agente con los permisos y proyectos que la persona eligió al dar su consentimiento — nunca con los permisos propios de la persona — y termina en cuanto se desconecta.

Una clave de agente es una cuenta propia con el rol Agente. Está pensada para los endpoints que muestran un scope en la referencia de la API, además de GET /v1/me y las ejecuciones del agente. Los endpoints que exigen «propietario» o «propietario y miembros del equipo» los usa la interfaz web con la sesión de una persona que ha iniciado sesión; a una clave de API le responden con 403.

Scopes

Lo que puede hacer una clave de agente lo determinan sus scopes:

Scope	Significado	Disponible para
`projects:read`	Leer proyectos	claves de agente
`tasks:read`	Leer tareas	claves de agente
`tasks:write`	Crear tareas e informar del resultado	claves de agente
`tickets:read`	Leer tickets	claves de agente, solo si el espacio de trabajo lo activa expresamente
`tickets:write`	Crear tickets, escribir notas internas y borradores	claves de agente, solo si el espacio de trabajo lo activa expresamente
`tickets:reply`	Responder a clientes por correo en los tickets	claves de agente, solo si el espacio de trabajo lo activa expresamente
`notes:write`	Escribir notas	claves de agente
`deployments:read`	Leer commits, pull requests y despliegues	claves de agente
`agent:run`	Iniciar y cerrar ejecuciones	claves de agente
`intake:write`	Enviar tickets a través de la entrada	solo claves de entrada
`invoices:write`	Crear borradores de factura y modificar partidas	claves de agente, solo si el espacio de trabajo lo activa expresamente
`errors:read`	Leer los errores de los proyectos	claves de agente, solo si el espacio de trabajo lo activa expresamente
`errors:write`	Marcar errores como resueltos	claves de agente, solo si el espacio de trabajo lo activa expresamente
`time:read`	Leer las entradas de tiempo de los proyectos (sin tarifas ni importes)	claves de agente, solo si el espacio de trabajo lo activa expresamente
`stats:read`	Leer los indicadores de los proyectos para informes (sin dinero)	claves de agente, solo si el espacio de trabajo lo activa expresamente
`quotes:write`	Crear y modificar borradores de presupuesto	claves de agente, solo si el espacio de trabajo lo activa expresamente
`roadmap:write`	Crear, modificar y ordenar fases de la hoja de ruta	claves de agente, solo si el espacio de trabajo lo activa expresamente
`ideas:write`	Crear ideas	claves de agente, solo si el espacio de trabajo lo activa expresamente

Un scope aparece exactamente en los endpoints que lo aplican; la referencia de la API lo indica en cada endpoint. deployments:read no aparece en ningún endpoint: actúa a través de las reglas de la base de datos de los commits, pull requests y despliegues reflejados.

Vinculación a proyectos

Una clave vale para todos los proyectos o para una selección. Una clave vinculada solo ve datos de sus proyectos — y, a propósito, nada sin proyecto, como los tickets que aún no están asignados a ningún proyecto. A una fila fuera de sus proyectos, la API responde con 404 o 403. Una clave de entrada está siempre vinculada a exactamente un proyecto.

Cambiar el alcance significa una clave nueva. Los scopes y proyectos de una clave no se pueden cambiar después: crea una nueva y revoca la antigua. Una clave revocada o caducada se rechaza en su siguiente solicitud.

Errores

Toda respuesta de error tiene la misma forma:

{ "ok": false, "error": "Diese Aufgabe gibt es nicht.", "code": "not_found" }

error es una frase para personas — en alemán, salvo que la solicitud pida otro idioma con Accept-Language —, code es un valor estable en inglés para programas. Respuestas habituales:

Estado	`code`	Significado
400	`validation_error`	parámetros de consulta o de ruta no válidos
401	`unauthorized`	sin clave o con una clave no válida
403	`forbidden`	el rol, el scope o el proyecto no bastan
404	`not_found`	no existe — o no para esta clave
409	`conflict`	el estado no encaja, por ejemplo una tarea ya tomada
413	`payload_too_large`	cuerpo de más de 1 MB
422	`validation_error`	cuerpo no válido; `error` nombra el primer campo objetado como `campo: mensaje`
423	`betrieb_gesperrt`	el espacio de trabajo está suspendido, por ejemplo porque no hay ninguna suscripción de pago
429	`rate_limited`	demasiadas solicitudes, espera un momento
500	`internal_error`	error en VentionDesk

Cada respuesta lleva un ID en la cabecera x-request-id. Si envías uno tú mismo (hasta 128 caracteres), se usa ese. Indícalo al soporte cuando algo falle.

Límites de solicitudes

Se cuentan por minuto, por clave o por dirección IP:

Ámbito	Solicitudes por minuto
todos los endpoints `/v1` juntos	300
`POST /mcp`	60
entrada de tickets (formulario, navegador, servidor)	10 por IP
enlaces de pago `/pay/…`	20 por IP

Por encima del límite, la API responde con 429 y rate_limited; las cabeceras RateLimit y RateLimit-Policy indican el recuento actual y el límite.

Listas y filtros

Los endpoints de listas filtran mediante parámetros de consulta y limitan con limit; no hay páginas con cursor ni offset. Ejemplos:

GET /v1/tasks?projectSlug=shop&status=todo&claimable=true&limit=20 — tareas que se pueden tomar ahora mismo.
GET /v1/projects?status=active — proyectos activos.

Qué parámetros conoce un endpoint y qué campos devuelve figura en la referencia de la API, leído del mismo contrato con el que VentionDesk comprueba la solicitud.

La ronda típica de un agente

GET /v1/tasks?claimable=true — ¿qué hay pendiente?
POST /v1/tasks/:id/claim — toma la tarea de forma atómica. Dos ejecuciones nunca reciben la misma.
Trabaja; entretanto, POST /v1/tasks/:id/result con "state": "arbeitet" como señal de vida.
POST /v1/tasks/:id/result con kontrolle, frage, master, blockiert o erledigt — con kontrolle y erledigt, con pruebas en evidence.

Si no quieres construirlo tú, usa Claude y MCP.