Desarrolladores

Referencia de la API

Todos los endpoints públicos de la API de VentionDesk. La lista se genera a partir de las rutas registradas del servidor; la regla de acceso de cada endpoint sale de las comprobaciones de la ruta, y las tablas de los contratos Zod con los que VentionDesk comprueba las solicitudes y da forma a las respuestas. Así, lo que pone aquí es lo que el servidor hace de verdad.

Las URL empiezan por https://api.ventiondesk.com. El inicio de sesión, los scopes, el formato de error y los límites de solicitudes se explican en Fundamentos de la API. Los campos obligatorios están marcados con *; un endpoint sin tabla comprueba su cuerpo con un contrato que no está publicado, o no tiene ninguno.

Acceso se lee así: «propietario» y «propietario y miembros del equipo» significan una persona que ha iniciado sesión en la interfaz web; con una clave de API, esos endpoints responden con 403. Los endpoints con scope también son accesibles para claves de agente que lleven ese scope.

Tareas

GET`/v1/tasks`

Leer tareas, filtradas por proyecto, estado, responsable o texto de búsqueda.

Acceso propietario, miembros del equipo o claves de agente con scope tasks:read

Parámetros de consulta

Campo	Tipo	Nota
project	UUID
projectSlug	Texto
status	"hold" \| "todo" \| "in_progress" \| "question" \| "review" \| "done"
assignee	"owner" \| "staff" \| "claude" \| "external"
claimable	"true" \| "false"
maxAttempts	Entero	≥ 1 \| ≤ 20 \| Predeterminado: 3
limit	Entero	≥ 1 \| ≤ 100 \| Predeterminado: 20
q	Texto	al menos 1 caracteres

Respuesta

Campo	Tipo	Nota
tasks	Lista de Objeto

POST`/v1/tasks`

Crear una tarea; las tareas abiertas muy parecidas se reconocen como duplicados.

Acceso propietario, miembros del equipo o claves de agente con scope tasks:write

Cuerpo (JSON)

Campo	Tipo	Nota
projectId	UUID
projectSlug	Texto
title *	Texto	al menos 25 caracteres
descriptionMd	Texto	al menos 1 caracteres
area	"frontend" \| "backend" \| "design" \| "infra" \| "support"
dueDate	Fecha (AAAA-MM-DD)
estimateMinutes	Entero	> 0
triggerCondition	Texto	al menos 1 caracteres
evidence	Texto	al menos 1 caracteres

GET`/v1/tasks/:id`

Una tarea con descripción, avisos y adjuntos.

Acceso propietario, miembros del equipo o claves de agente con scope tasks:read

Respuesta

Campo	Tipo	Nota
task	Objeto
results	Lista de Objeto
attachments	Lista de Objeto

PATCH`/v1/tasks/:id`

Cambiar campos de una tarea.

Acceso propietario, miembros del equipo o claves de agente con scope tasks:write

Cuerpo (JSON)

Campo	Tipo	Nota
title	Texto	al menos 1 caracteres
descriptionMd	Texto o null
status	"hold" \| "todo" \| "in_progress" \| "question" \| "review" \| "done"
assignee	"owner" \| "staff" \| "claude" \| "external" o null
area	"frontend" \| "backend" \| "design" \| "infra" \| "support" o null
dueDate	Fecha (AAAA-MM-DD) o null
estimateMinutes	Entero o null	> 0
position	Texto	al menos 1 caracteres
triggerCondition	Texto o null

POST`/v1/tasks/:id/claim`

Reclamar una tarea de forma atómica: dos ejecuciones nunca reciben la misma.

Acceso propietario, miembros del equipo o claves de agente con scope tasks:write

Cuerpo (JSON)

Campo	Tipo	Nota
maxAttempts	Entero	≥ 1 \| ≤ 20 \| Predeterminado: 3
runId	UUID

POST`/v1/tasks/:id/decision`

Aprobación o rechazo de un aviso por una persona; un rechazo exige un comentario.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
decision *	"approved" \| "rejected"
commentMd	Texto	al menos 1 caracteres \| como máximo 20000 caracteres
attachmentIds	Lista de UUID	Predeterminado: []

Respuesta

Campo	Tipo	Nota
task	Objeto
result	Objeto

POST`/v1/tasks/:id/handoff`

Pasar una tarea a Claude.

Acceso propietario, miembros del equipo o claves de agente con scope tasks:write

POST`/v1/tasks/:id/result`

Informar del estado de una tarea (arbeitet, kontrolle, frage, master, blockiert, erledigt).

Acceso propietario, miembros del equipo o claves de agente con scope tasks:write

Cuerpo (JSON)

Campo	Tipo	Nota
state *	"arbeitet" \| "kontrolle" \| "frage" \| "master" \| "blockiert" \| "erledigt"
summaryMd	Texto	al menos 1 caracteres
detailsMd	Texto	al menos 1 caracteres
prUrl	URL
evidence	Texto	al menos 1 caracteres
runId	UUID

Ejecuciones de agentes

POST`/v1/agent/runs`

Iniciar una ejecución de un agente.

Acceso solo claves de agente, con scope agent:run

Cuerpo (JSON)

Campo	Tipo	Nota
projectId	UUID
projectSlug	Texto
meta	Objeto (libre)	Predeterminado: {}

Respuesta

Campo	Tipo	Nota
run	Objeto

POST`/v1/agent/runs/:id/finish`

Terminar una ejecución de agente, con un resumen o un estado de error.

Acceso solo claves de agente

Cuerpo (JSON)

Campo	Tipo	Nota
status *	"succeeded" \| "failed"
summary	Texto	al menos 1 caracteres

Respuesta

Campo	Tipo	Nota
run	Objeto

POST`/v1/agent/runs/:id/heartbeat`

Señal de vida de una ejecución de agente en curso.

Acceso solo claves de agente

Respuesta

Campo	Tipo	Nota
run	Objeto

Proyectos

POST`/v1/errors/:id/resolve`

Marcar como resuelto un error abierto: primero en el servicio de seguimiento de errores (Sentry, Bugsnag, Rollbar) con el acceso de la fuente de errores, y solo si sale bien, en VentionDesk. Si el proveedor falla (acceso de solo lectura, error desconocido, sin respuesta), el error sigue abierto: 409 o 502 con el motivo. Para el propietario, los miembros del equipo y los agentes con errors:write. Ocultar y eliminar no están disponibles aquí.

Acceso propietario, miembros del equipo o claves de agente con scope errors:write

Respuesta

Campo	Tipo	Nota
issue	Objeto
changed	true \| false

POST`/v1/errors/:id/task`

Crear una tarea a partir de un error.

Acceso propietario y miembros del equipo

GET`/v1/errors/summary`

Recuento de errores de todos los proyectos para el resumen.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
projects	Lista de Objeto

POST`/v1/monitors/probe`

Comprobar la URL de un monitor antes de crearlo e indicar las redirecciones, incluido el destino final.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
url *	URL	como máximo 2048 caracteres

GET`/v1/projects`

Proyectos que la cuenta o la clave puede ver.

Acceso propietario, miembros del equipo o claves de agente con scope projects:read

Parámetros de consulta

Campo	Tipo	Nota
status	"active" \| "blocked" \| "review" \| "paused"
includeArchived	"true" \| "false"
q	Texto	al menos 1 caracteres

Respuesta

Campo	Tipo	Nota
projects	Lista de Objeto

GET`/v1/projects/:id`

Un proyecto por su ID.

Acceso propietario, miembros del equipo o claves de agente con scope projects:read

PATCH`/v1/projects/:id/customer`

Asignar un proyecto a otro cliente; tickets, borradores y documentos lo acompañan.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
customerId *	UUID

Respuesta

Campo	Tipo	Nota
project	Objeto
changed	true \| false
moved	Objeto

GET`/v1/projects/:id/deploy`

Qué destinos de despliegue existen y qué le falta a cada uno.

Acceso propietario

Respuesta

Campo	Tipo	Nota
targets	Lista de Objeto

POST`/v1/projects/:id/deploy`

Lanzar un despliegue (202: lanzado, no completado).

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
target *	"production" \| "staging" \| "preview"
provider	"vercel" \| "render"

Respuesta

Campo	Tipo	Nota
provider	"vercel" \| "render"
target	"production" \| "staging" \| "preview"
externalId	Texto o null
started	Entero	> 0

POST`/v1/projects/:id/error-sources`

Asignar a este proyecto un proyecto del servicio de seguimiento de errores.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
provider *	"sentry" \| "bugsnag" \| "rollbar"
externalId *	Texto	al menos 1 caracteres \| como máximo 200 caracteres

DELETE`/v1/projects/:id/error-sources/:sourceId`

Desvincular una fuente de errores del proyecto.

Acceso propietario y miembros del equipo

GET`/v1/projects/:id/errors`

Errores de Sentry, Bugsnag o Rollbar de este proyecto. Un agente con errors:read recibe los errores de sus proyectos, sin fuentes ni conexiones.

Acceso propietario, miembros del equipo o claves de agente con scope errors:read

Respuesta

Campo	Tipo	Nota
issues	Lista de Objeto
stats	Objeto
sources	Lista de Objeto
providers	Lista de "sentry" \| "bugsnag" \| "rollbar"

GET`/v1/projects/:id/hosting`

Las asignaciones de hosting del proyecto.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
mappings	Lista de Objeto
providers	Lista de "netlify" \| "cloudflare_pages" \| "aws_amplify" \| "railway" \| "flyio" \| "digitalocean_app_platform"

POST`/v1/projects/:id/hosting`

Asignar un sitio, app o servicio del proveedor de hosting.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
provider *	"netlify" \| "cloudflare_pages" \| "aws_amplify" \| "railway" \| "flyio" \| "digitalocean_app_platform"
externalId *	Texto	al menos 1 caracteres \| como máximo 200 caracteres

DELETE`/v1/projects/:id/hosting/:mappingId`

Quitar una asignación de hosting.

Acceso propietario y miembros del equipo

DELETE`/v1/projects/:id/render-services/:serviceId`

Desvincular del proyecto un ID de servicio de Render obsoleto.

Acceso propietario

GET`/v1/projects/:id/report`

El estado del proyecto para un informe: progreso, tareas por estado, tickets abiertos y vencidos, hoja de ruta, monitores, despliegues y pull requests abiertos. Nada de dinero: ni ingresos, ni presupuesto, ni costes.

Acceso propietario, miembros del equipo o claves de agente con scope stats:read

GET`/v1/projects/:id/roadmap`

Las fases de la hoja de ruta de un proyecto en el orden planificado.

Acceso propietario, miembros del equipo o claves de agente con scope roadmap:write

Respuesta

Campo	Tipo	Nota
phases	Lista de Objeto

POST`/v1/projects/:id/roadmap`

Crear una fase de la hoja de ruta. Sin sort va al final; la siguiente fase abierta es el hito en el cockpit.

Acceso propietario, miembros del equipo o claves de agente con scope roadmap:write

Cuerpo (JSON)

Campo	Tipo	Nota
title *	Texto	al menos 1 caracteres \| como máximo 200 caracteres
startsOn *	Texto	patrón fijo
endsOn *	Texto	patrón fijo
sort	Entero	≥ 0

PATCH`/v1/projects/:id/roadmap/:phaseId`

Cambiar una fase (título, periodo, hecha u orden), solo los campos enviados. La API no elimina.

Acceso propietario, miembros del equipo o claves de agente con scope roadmap:write

Cuerpo (JSON)

Campo	Tipo	Nota
title	Texto	al menos 1 caracteres \| como máximo 200 caracteres
startsOn	Texto	patrón fijo
endsOn	Texto	patrón fijo
done	true \| false
sort	Entero	≥ 0

POST`/v1/projects/:id/sync`

Sincronizar ya los datos de GitHub del proyecto en lugar de por la noche.

Acceso propietario y miembros del equipo

GET`/v1/projects/:id/time`

Las entradas de tiempo de un proyecto: día, duración, descripción, tarea, facturable y facturado sí/no, nombre de la persona; sin tarifa por hora, importe ni ID de factura.

Acceso propietario, miembros del equipo o claves de agente con scope time:read

Parámetros de consulta

Campo	Tipo	Nota
from	Texto	patrón fijo
to	Texto	patrón fijo
limit	Entero	≥ 1 \| ≤ 500 \| Predeterminado: 200

Respuesta

Campo	Tipo	Nota
entries	Lista de Objeto
totalSeconds	Entero	≥ 0

GET`/v1/projects/by-slug/:slug`

Un proyecto por su slug.

Acceso propietario, miembros del equipo o claves de agente con scope projects:read

Tickets

GET`/v1/tickets`

Leer tickets, filtrados por estado, canal, prioridad, proyecto o cliente.

Acceso propietario, miembros del equipo o claves de agente con scope tickets:read

Parámetros de consulta

Campo	Tipo	Nota
status	"open" \| "in_progress" \| "waiting" \| "resolved"
source	"contact_form" \| "app" \| "email" \| "monitor" \| "portal" \| "phone" \| "on_site" \| "stripe" \| "api"
priority	"low" \| "normal" \| "high" \| "critical"
project	UUID
projectSlug	Texto
customer	UUID
withSla	"true" \| "false"
q	Texto	al menos 1 caracteres
limit	Entero	≥ 1 \| ≤ 100 \| Predeterminado: 50

Respuesta

Campo	Tipo	Nota
tickets	Lista de Objeto

POST`/v1/tickets`

Crear un ticket, por ejemplo tras una llamada telefónica.

Acceso propietario, miembros del equipo o claves de agente con scope tickets:write

Cuerpo (JSON)

Campo	Tipo	Nota
subject *	Texto	al menos 3 caracteres
bodyMd *	Texto	al menos 1 caracteres
source *	"contact_form" \| "app" \| "email" \| "monitor" \| "portal" \| "phone" \| "on_site" \| "stripe" \| "api"
customerId	UUID o null
projectId	UUID o null
priority	"low" \| "normal" \| "high" \| "critical"	Predeterminado: "normal"
requesterName	Texto
requesterEmail	Correo electrónico
requesterMeta	Objeto (libre)

DELETE`/v1/tickets/:id`

Eliminar un ticket.

Acceso propietario y miembros del equipo

GET`/v1/tickets/:id`

Un ticket con su historial.

Acceso propietario, miembros del equipo o claves de agente con scope tickets:read

Respuesta

Campo	Tipo	Nota
ticket	Objeto
messages	Lista de Objeto

PATCH`/v1/tickets/:id`

Cambiar asunto, estado, prioridad, canal, cliente, proyecto, responsable o visibilidad en el portal de un ticket.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
subject	Texto	al menos 3 caracteres
status	"open" \| "in_progress" \| "waiting" \| "resolved"
priority	"low" \| "normal" \| "high" \| "critical"
source	"contact_form" \| "app" \| "email" \| "monitor" \| "portal" \| "phone" \| "on_site" \| "stripe" \| "api"
customerId	UUID o null
projectId	UUID o null
assignedTo	UUID o null
portalVisible	true \| false

POST`/v1/tickets/:id/messages`

Escribir una entrada en el historial: nota interna o borrador. No sale ningún correo.

Acceso propietario, miembros del equipo o claves de agente con scope tickets:write

Cuerpo (JSON)

Campo	Tipo	Nota
bodyMd *	Texto	al menos 1 caracteres
isInternalNote	true \| false	Predeterminado: false
isDraft	true \| false	Predeterminado: false

POST`/v1/tickets/:id/reply`

Responder al cliente: la única vía por la que sale un correo. Pone el ticket en «En espera». La respuesta de un agente lleva siempre el aviso de que la ha escrito un asistente de IA y está limitada a 20 por hora y clave y a 3 por ticket y día (por encima, 429).

Acceso propietario, miembros del equipo o claves de agente con scope tickets:reply

Cuerpo (JSON)

Campo	Tipo	Nota
bodyMd *	Texto	al menos 1 caracteres
isInternalNote	true \| false	Predeterminado: false
isDraft	true \| false	Predeterminado: false
draftId	UUID

POST`/v1/tickets/:id/to-task`

Crear una tarea a partir de un ticket: el asunto como título, todo el historial como descripción.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
projectId *	UUID
title	Texto	al menos 10 caracteres
assignee	"owner" \| "staff" \| "claude" \| "external" o null

GET`/v1/tickets/attachments/:id/url`

URL de corta duración para un adjunto de un ticket; un agente solo la recibe para tickets de sus proyectos.

Acceso propietario, miembros del equipo o claves de agente con scope tickets:read

Respuesta

Campo	Tipo	Nota
url	URL
expiresInSeconds	Entero	> 0

Notas

POST`/v1/notes`

Crear una nota en un proyecto (ID o slug del proyecto).

Acceso propietario, miembros del equipo o claves de agente con scope notes:write

Cuerpo (JSON)

Campo	Tipo	Nota
projectId	UUID
projectSlug	Texto
bodyMd *	Texto	al menos 1 caracteres
kind	"idea" \| "decision" \| "risk"	Predeterminado: "idea"

Respuesta

Campo	Tipo	Nota
note	Objeto

POST`/v1/notes/:id/to-task`

Crear una tarea a partir de una nota.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
title	Texto	al menos 25 caracteres
assignee	"owner" \| "staff" \| "claude" \| "external" o null

Respuesta

Campo	Tipo	Nota
ok	false
error	Texto
code	"note_already_converted"
task	Objeto

Ideas

POST`/v1/ideas`

Crear una idea, siempre «Abierta». Un agente solo crea: no lee, cambia ni elimina ninguna idea; sin proyecto, solo con una clave para todos los proyectos.

Acceso propietario o claves de agente con scope ideas:write

Cuerpo (JSON)

Campo	Tipo	Nota
title *	Texto	al menos 1 caracteres \| como máximo 200 caracteres
bodyMd	Texto	como máximo 20000 caracteres
tags	Lista de Texto	Predeterminado: []
potential	"low" \| "medium" \| "high"
priority	"low" \| "high"
projectId	UUID o null

Respuesta

Campo	Tipo	Nota
idea	Objeto

Tiempo

GET`/v1/time/entries`

Leer entradas de tiempo.

Acceso propietario y miembros del equipo

Parámetros de consulta

Campo	Tipo	Nota
from	Texto
to	Texto
project	UUID
user	UUID
unbilled	"true" \| "false"
limit	Entero	≥ 1 \| ≤ 500 \| Predeterminado: 200

Respuesta

Campo	Tipo	Nota
entries	Lista de Objeto

POST`/v1/time/entries`

Añadir tiempo a posteriori.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
label *	Texto	al menos 1 caracteres
startedAt *	Marca de tiempo (ISO 8601)
endedAt *	Marca de tiempo (ISO 8601)
seconds	Entero	> 0
projectId	UUID o null
ticketId	UUID o null
taskId	UUID o null
billable	true \| false	Predeterminado: true

DELETE`/v1/time/entries/:id`

Eliminar una entrada de tiempo.

Acceso propietario y miembros del equipo

PATCH`/v1/time/entries/:id`

Cambiar una entrada de tiempo.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
label	Texto	al menos 1 caracteres
seconds	Entero	> 0
billable	true \| false
projectId	UUID o null
ticketId	UUID o null

GET`/v1/time/timer`

El temporizador en marcha de la cuenta.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
timer	Objeto o null

POST`/v1/time/timer/start`

Iniciar el temporizador.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
label	Texto	Predeterminado: ""
projectId	UUID o null
ticketId	UUID o null
taskId	UUID o null

POST`/v1/time/timer/stop`

Parar el temporizador y registrar el tiempo como entrada.

Acceso propietario y miembros del equipo

GET`/v1/time/unbilled`

Horas facturables aún sin facturar, por proyecto, con el importe.

Acceso propietario

Respuesta

Campo	Tipo	Nota
projects	Lista de Objeto
totals	Objeto

Clientes

DELETE`/v1/customers/:id`

Eliminar un cliente, incluidos los archivos.

Acceso propietario

Respuesta

Campo	Tipo	Nota
customerId	UUID
shortName	Texto
impact	Objeto
files	Objeto
portalAccounts	Objeto

GET`/v1/customers/:id/deletion`

Vista previa de lo que se quitaría junto con un cliente.

Acceso propietario

Respuesta

Campo	Tipo	Nota
customerId	UUID
shortName	Texto
deletable	true \| false
reason	Texto o null
blockers	Objeto
impact	Objeto

POST`/v1/customers/:id/portal-access`

Dar acceso al portal de clientes a una persona de contacto.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
email *	Correo electrónico
displayName	Texto	al menos 1 caracteres

Respuesta

Campo	Tipo	Nota
access	Objeto
mail	Objeto

DELETE`/v1/customers/:id/portal-access/:userId`

Retirar el acceso al portal de una cuenta. Un token ya emitido sigue siendo válido hasta que se renueve.

Acceso propietario

Respuesta

Campo	Tipo	Nota
revoked	Objeto

POST`/v1/customers/:id/portal-access/:userId/invite`

Volver a enviar la invitación al portal de clientes.

Acceso propietario

Respuesta

Campo	Tipo	Nota
mail	Objeto

Documentos

GET`/v1/documents`

Leer documentos, filtrados por cliente, proyecto o tipo.

Acceso cualquier cuenta con sesión iniciada; su rol decide lo que ve

Parámetros de consulta

Campo	Tipo	Nota
customer	UUID
project	UUID
type	"pdf" \| "image" \| "sheet" \| "contract" \| "other"
q	Texto	al menos 1 caracteres \| como máximo 120 caracteres
limit	Entero	≥ 1 \| ≤ 200 \| Predeterminado: 50

Respuesta

Campo	Tipo	Nota
documents	Lista de Objeto

PATCH`/v1/documents/:id`

Cambiar asignación, tipo, etiquetas o visibilidad en el portal de un documento.

Acceso cualquier cuenta con sesión iniciada; su rol decide lo que ve

Cuerpo (JSON)

Campo	Tipo	Nota
name	Texto	al menos 1 caracteres \| como máximo 200 caracteres
type	"pdf" \| "image" \| "sheet" \| "contract" \| "other"
projectId	UUID o null
sharedWithPortal	true \| false
tags	Lista de Texto

GET`/v1/documents/:id/url`

URL de corta duración para descargar un documento.

Acceso cualquier cuenta con sesión iniciada; su rol decide lo que ve

Respuesta

Campo	Tipo	Nota
url	URL
expiresInSeconds	Entero	> 0

Finanzas

GET`/v1/finance/export`

Exportación anual para el asesor fiscal: ZIP con un CSV por tabla y los justificantes guardados.

Acceso propietario

GET`/v1/invoices`

Leer facturas, filtradas por estado, cliente o «vencidas». Un agente solo ve borradores de sus proyectos.

Acceso propietario o claves de agente con scope invoices:write

Parámetros de consulta

Campo	Tipo	Nota
status	"draft" \| "open" \| "overdue" \| "paid" \| "cancelled"
customer	UUID
overdue	"true" \| "false"
limit	Entero	≥ 1 \| ≤ 200 \| Predeterminado: 50

Respuesta

Campo	Tipo	Nota
invoices	Lista de Objeto

POST`/v1/invoices`

Crear un borrador de factura, todavía sin número de factura. Sin customerId se aplica el cliente del proyecto; un agente solo crea borradores en uno de sus proyectos. Finalizar, enviar y registrar pagos sigue siendo cosa del propietario.

Acceso propietario o claves de agente con scope invoices:write

Cuerpo (JSON)

Campo	Tipo	Nota
customerId	UUID
projectId	UUID o null
paymentTermsDays	Entero	≥ 1 \| ≤ 90
vatRate	Entero
vatScheme	"standard" \| "reverse_charge"
serviceFrom	Texto	patrón fijo
serviceTo	Texto	patrón fijo
serviceDateEqualsInvoiceDate	true \| false	Predeterminado: false
positions	Lista de Objeto	Predeterminado: []

GET`/v1/invoices/:id`

Una factura con partidas, totales y pagos.

Acceso propietario o claves de agente con scope invoices:write

Respuesta

Campo	Tipo	Nota
invoice	Objeto
positions	Lista de Objeto

POST`/v1/invoices/:id/cancel`

Anular una factura finalizada; se crea un documento de anulación.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
reason *	Texto	al menos 3 caracteres \| como máximo 500 caracteres
serviceRendered *	true \| false

Respuesta

Campo	Tipo	Nota
invoice	Objeto
releasedEntries	Entero	≥ 0
entries	"released" \| "failed"
correction	"stored" \| "skipped" \| "failed"
taxOfficeConsent	true \| false

GET`/v1/invoices/:id/cancellation/pdf`

El documento de anulación en PDF.

Acceso propietario

POST`/v1/invoices/:id/cancellation/send`

Enviar el documento de anulación por correo.

Acceso propietario

Respuesta

Campo	Tipo	Nota
mail	"sent" \| "skipped"
reason	Texto	puede faltar
invoice	Objeto

POST`/v1/invoices/:id/dunning/send`

Enviar el nivel de aviso que toca.

Acceso propietario

Respuesta

Campo	Tipo	Nota
mail	"sent" \| "skipped"
reason	Texto	puede faltar
invoice	Objeto
level	Entero o null	≥ 1 \| ≤ 4

POST`/v1/invoices/:id/finalize`

Finalizar un borrador: asigna el número correlativo, bloquea la factura y guarda el PDF.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
settle	Objeto

Respuesta

Campo	Tipo	Nota
invoice	Objeto
pdf	"stored" \| "skipped" \| "failed"
payment	"none" \| "booked" \| "failed"
paymentError	Texto	puede faltar

POST`/v1/invoices/:id/payments`

Registrar un pago o una devolución.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
amountCents *	Entero
paidOn	Texto	patrón fijo
method	"transfer" \| "stripe" \| "cash" \| "other"	Predeterminado: "transfer"
note	Texto	como máximo 500 caracteres

GET`/v1/invoices/:id/pdf`

La factura en PDF: el documento guardado al finalizarla.

Acceso propietario

POST`/v1/invoices/:id/positions`

Añadir una partida a un borrador.

Acceso propietario o claves de agente con scope invoices:write

Cuerpo (JSON)

Campo	Tipo	Nota
description *	Texto	al menos 1 caracteres
quantity *	Número	> 0
unit	"hour" \| "flat"	Predeterminado: "hour"
unitPriceCents *	Entero	≥ 0
sort	Entero

DELETE`/v1/invoices/:id/positions/:positionId`

Quitar una partida de un borrador.

Acceso propietario o claves de agente con scope invoices:write

PATCH`/v1/invoices/:id/positions/:positionId`

Cambiar una partida de un borrador, solo los campos enviados. Una factura finalizada responde con 409.

Acceso propietario o claves de agente con scope invoices:write

Cuerpo (JSON)

Campo	Tipo	Nota
description	Texto	al menos 1 caracteres
quantity	Número	> 0
unit	"hour" \| "flat"	Predeterminado: "hour"
unitPriceCents	Entero	≥ 0
sort	Entero

POST`/v1/invoices/:id/remind`

Enviar un recordatorio de pago.

Acceso propietario

Respuesta

Campo	Tipo	Nota
mail	"sent" \| "skipped"
reason	Texto	puede faltar
invoice	Objeto

POST`/v1/invoices/:id/send`

Enviar una factura finalizada por correo.

Acceso propietario

Respuesta

Campo	Tipo	Nota
mail	"sent" \| "skipped"
reason	Texto	puede faltar
invoice	Objeto

GET`/v1/invoices/:id/stripe-refund`

Si se puede reembolsar un pago de Stripe y cuánto.

Acceso propietario

POST`/v1/invoices/:id/stripe-refund`

Reembolsar mediante Stripe una factura pagada con Stripe; se registra a través del webhook.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
amountCents	Entero	> 0

GET`/v1/invoices/:id/test-pay-link`

Un enlace de pago en el modo de prueba de Stripe para probar.

Acceso propietario

POST`/v1/invoices/from-unbilled`

Convertir las horas facturables pendientes de un proyecto en un borrador de factura: una partida por entrada de tiempo.

Acceso propietario o claves de agente con scope invoices:write

Cuerpo (JSON)

Campo	Tipo	Nota
projectId *	UUID
untilDate	Texto
paymentTermsDays	Entero	≥ 1 \| ≤ 90
vatRate	Entero
vatScheme	"standard" \| "reverse_charge"

Respuesta

Campo	Tipo	Nota
invoice	Objeto
entries	Entero	≥ 0
hours	Número	≥ 0

GET`/v1/quotes`

Leer presupuestos. Un agente solo ve borradores de sus proyectos.

Acceso propietario o claves de agente con scope quotes:write

Respuesta

Campo	Tipo	Nota
quotes	Lista de Objeto

POST`/v1/quotes`

Crear un borrador de presupuesto, todavía sin número. Sin customerId se aplica el cliente del proyecto; un agente solo crea borradores en uno de sus proyectos y nunca para un interesado.

Acceso propietario o claves de agente con scope quotes:write

Cuerpo (JSON)

Campo	Tipo	Nota
title *	Texto	al menos 3 caracteres
customerId	UUID o null
prospectName	Texto
prospectEmail	Correo electrónico
projectId	UUID o null
validUntil	Texto
vatRate	Entero
vatScheme	"standard" \| "reverse_charge"
positions	Lista de Objeto	Predeterminado: []

DELETE`/v1/quotes/:id`

Eliminar un borrador de presupuesto: todavía no tiene número.

Acceso propietario o claves de agente con scope quotes:write

GET`/v1/quotes/:id`

Un presupuesto con sus partidas.

Acceso propietario o claves de agente con scope quotes:write

Respuesta

Campo	Tipo	Nota
quote	Objeto
positions	Lista de Objeto

PATCH`/v1/quotes/:id`

Cambiar el título y la validez de un borrador. Un presupuesto enviado responde con 409.

Acceso propietario o claves de agente con scope quotes:write

Cuerpo (JSON)

Campo	Tipo	Nota
title	Texto	al menos 3 caracteres
validUntil	Texto o null	patrón fijo

GET`/v1/quotes/:id/pdf`

Un presupuesto en PDF.

Acceso propietario

POST`/v1/quotes/:id/positions`

Añadir una partida a un borrador de presupuesto.

Acceso propietario o claves de agente con scope quotes:write

Cuerpo (JSON)

Campo	Tipo	Nota
description *	Texto	al menos 1 caracteres
quantity *	Número	> 0
unit	"hour" \| "flat"	Predeterminado: "hour"
unitPriceCents *	Entero	≥ 0
sort	Entero

DELETE`/v1/quotes/:id/positions/:positionId`

Quitar una partida de un borrador de presupuesto.

Acceso propietario o claves de agente con scope quotes:write

PATCH`/v1/quotes/:id/positions/:positionId`

Cambiar una partida de un borrador de presupuesto, solo los campos enviados.

Acceso propietario o claves de agente con scope quotes:write

Cuerpo (JSON)

Campo	Tipo	Nota
description	Texto	al menos 1 caracteres
quantity	Número	> 0
unit	"hour" \| "flat"	Predeterminado: "hour"
unitPriceCents	Entero	≥ 0
sort	Entero

POST`/v1/quotes/:id/send`

Enviar un presupuesto por correo.

Acceso propietario

Respuesta

Campo	Tipo	Nota
mail	"sent" \| "skipped"
reason	Texto	puede faltar
quote	Objeto

Conexiones

GET`/v1/integrations`

Las fuentes conectadas del espacio de trabajo, sin secretos.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
integrations	Lista de Objeto
plattform	true \| false
githubInstallierbar	true \| false

POST`/v1/integrations`

Conectar una fuente. El acceso se comprueba con el proveedor antes de guardarlo.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
provider *	"vercel" \| "render" \| "netlify" \| "cloudflare_pages" \| "aws_amplify" \| "railway" \| "flyio" \| "digitalocean_app_platform" \| "postmark" \| "mailgun" \| "amazon_ses" \| "resend" \| "sentry" \| "bugsnag" \| "rollbar" \| "stripe"
fields *	Objeto (libre)

DELETE`/v1/integrations/:id`

Quitar una conexión.

Acceso propietario

PATCH`/v1/integrations/:id`

Editar una conexión; un secreto vacío se mantiene sin cambios.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
fields *	Objeto (libre)

GET`/v1/integrations/:id/webhook`

La dirección del webhook de una conexión (Stripe, Sentry, Bugsnag, Rollbar) para introducirla en el proveedor.

Acceso propietario

Respuesta

Campo	Tipo	Nota
url	URL
signiert	true \| false
bereit	true \| false

GET`/v1/integrations/:provider/error-projects`

Proyectos que el acceso ve en el servicio de seguimiento de errores.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
resources	Lista de Objeto

GET`/v1/integrations/:provider/resources`

Sitios, apps o servicios que el acceso de hosting ve en el proveedor.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
resources	Lista de Objeto

GET`/v1/integrations/github/callback`

Vuelta desde GitHub tras la instalación; vincula la instalación al espacio de trabajo.

Acceso state firmado e inicio de sesión en GitHub

Parámetros de consulta

Campo	Tipo	Nota
installation_id	Texto	patrón fijo
setup_action	Texto	como máximo 20 caracteres
code	Texto	como máximo 200 caracteres
state	Texto	como máximo 2000 caracteres

POST`/v1/integrations/github/install-url`

URL para instalar la app de VentionDesk en GitHub.

Acceso propietario

Respuesta

Campo	Tipo	Nota
url	URL

Cuenta, ajustes y administración

GET`/v1/admin/api-keys`

Las claves de API del espacio de trabajo, sin texto plano.

Acceso propietario

Respuesta

Campo	Tipo	Nota
keys	Lista de Objeto

POST`/v1/admin/api-keys`

Crear una clave de agente o de entrada. El texto plano solo aparece en esta respuesta.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
name *	Texto	al menos 3 caracteres
kind	"agent" \| "intake"	Predeterminado: "agent"
scopes *	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
projectIds *	Lista de UUID o null
expiresAt	Marca de tiempo (ISO 8601)

Respuesta

Campo	Tipo	Nota
key	Objeto
plaintext	Texto

DELETE`/v1/admin/api-keys/:id`

Revocar una clave: surte efecto de inmediato.

Acceso propietario

PATCH`/v1/admin/api-keys/:id`

Cambiar los permisos y proyectos de una clave; la clave en sí sigue siendo la misma.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
scopes *	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
projectIds *	Lista de UUID o null

Respuesta

Campo	Tipo	Nota
key	Objeto

DELETE`/v1/admin/api-keys/:id/endgueltig`

Eliminar definitivamente una clave revocada.

Acceso propietario

GET`/v1/admin/members`

Los miembros del espacio de trabajo con su rol.

Acceso propietario

Respuesta

Campo	Tipo	Nota
members	Lista de Objeto

PATCH`/v1/admin/members/:id`

Cambiar el rol de un miembro.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
role *	"owner" \| "staff"

Respuesta

Campo	Tipo	Nota
member	Objeto
activeHere	true \| false

DELETE`/v1/admin/users/:id`

Eliminar una cuenta del portal; antes se seudonimizan el nombre y la dirección en el historial.

Acceso propietario

Respuesta

Campo	Tipo	Nota
removed	Objeto
account	"kept" \| "deleted" \| "locked"

POST`/v1/admin/users/invite`

Invitar a un miembro del equipo por correo.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
email *	Correo electrónico
role *	"owner" \| "staff"
displayName	Texto	al menos 1 caracteres

Respuesta

Campo	Tipo	Nota
user	Objeto
existingAccount	true \| false	puede faltar \| Predeterminado: false

GET`/v1/ki-apps`

Apps de IA conectadas: las propias en todos los espacios de trabajo y, para el propietario, todas las del espacio de trabajo.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
apps	Lista de Objeto
alleImBetrieb	true \| false

POST`/v1/ki-apps`

Guardar el consentimiento para una app de IA (espacio de trabajo, permisos, proyectos) antes de la aprobación en el inicio de sesión. Supabase Auth identifica la app, no quien llama.

Acceso propietario y miembros del equipo

Cuerpo (JSON)

Campo	Tipo	Nota
authorizationId *	Texto	al menos 1 caracteres \| como máximo 200 caracteres
orgId *	UUID
scopes *	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
projectIds *	Lista de UUID o null

Respuesta

Campo	Tipo	Nota
app	Objeto

DELETE`/v1/ki-apps/:id`

Desconectar una app de IA: surte efecto de inmediato; para las propias se retira también la aprobación del inicio de sesión.

Acceso propietario y miembros del equipo

GET`/v1/ki-apps/rahmen`

Lo que ofrece la página de consentimiento: los espacios de trabajo de la persona, los permisos permitidos y los proyectos.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
betriebe	Lista de Objeto
betrieb	UUID
rolle	"owner" \| "staff"
erlaubt	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
projekte	Lista de Objeto

GET`/v1/ki-apps/vorgabe`

Qué permisos pueden dar los miembros del equipo a una app de IA.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
scopes	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
abWerk	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
waehlbar	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"

PUT`/v1/ki-apps/vorgabe`

Cambiar esta configuración predeterminada.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
scopes *	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"

Respuesta

Campo	Tipo	Nota
scopes	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
abWerk	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"
waehlbar	Lista de "projects:read" \| "tasks:read" \| "tasks:write" \| "tickets:read" \| "tickets:write" \| "tickets:reply" \| "notes:write" \| "deployments:read" \| "agent:run" \| "intake:write" \| "access-log:write" \| "invoices:write" \| "errors:read" \| "errors:write" \| "time:read" \| "stats:read" \| "quotes:write" \| "roadmap:write" \| "ideas:write"

GET`/v1/me`

Tu propia cuenta: rol, espacio de trabajo, espacios de trabajo disponibles y direcciones de servicio.

Acceso cualquier cuenta con sesión iniciada; su rol decide lo que ve

Respuesta

Campo	Tipo	Nota
id	UUID
role	"owner" \| "staff" \| "customer" \| "agent"
customerId	UUID o null
displayName	Texto	al menos 1 caracteres
email	Correo electrónico
mfaRequired	true \| false
intake	Objeto
organization	Objeto o null	puede faltar \| Predeterminado: null
memberships	Lista de Objeto	puede faltar \| Predeterminado: []
support	Objeto o null	puede faltar
locale	"de" \| "en" \| "zh" \| "es" \| "hi" \| "tr" o null	puede faltar

PATCH`/v1/me/locale`

Guardar en la cuenta tu propio idioma de la interfaz.

Acceso cualquier cuenta con sesión iniciada; su rol decide lo que ve

Cuerpo (JSON)

Campo	Tipo	Nota
locale *	"de" \| "en" \| "zh" \| "es" \| "hi" \| "tr"

POST`/v1/me/organization`

Cambiar el espacio de trabajo activo si la cuenta pertenece a varios.

Acceso cualquier cuenta con sesión iniciada; su rol decide lo que ve

Cuerpo (JSON)

Campo	Tipo	Nota
orgId *	UUID

Respuesta

Campo	Tipo	Nota
organization	Objeto
role	"owner" \| "staff"

GET`/v1/settings`

Ajustes del espacio de trabajo, incluido el membrete para los documentos.

Acceso propietario

Respuesta

Campo	Tipo	Nota
company	Objeto

PATCH`/v1/settings`

Cambiar ajustes y membrete.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
company *	Objeto

Respuesta

Campo	Tipo	Nota
company	Objeto

GET`/v1/settings/agreements`

Estado del consentimiento a las condiciones y al contrato de encargo del tratamiento.

Acceso propietario

POST`/v1/settings/agreements`

Aceptar o rechazar una nueva versión de las condiciones o del contrato de encargo del tratamiento.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
document *	"agb" \| "avv"
version *	Texto	al menos 1 caracteres \| como máximo 40 caracteres
decision *	"accepted" \| "declined"

GET`/v1/settings/benachrichtigungen`

Correo con cada ticket nuevo: activado o no, destinatarios, canales y prioridad mínima.

Acceso propietario

PATCH`/v1/settings/benachrichtigungen`

Configurar el correo con cada ticket nuevo (solo el propietario).

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
aktiv *	true \| false
wiederoeffnen	true \| false
empfaenger *	Lista de Correo electrónico o null
kanaele *	Lista de "contact_form" \| "app" \| "email" \| "monitor" \| "portal" \| "phone" \| "on_site" \| "stripe" \| "api" o null
mindestPrioritaet *	"low" \| "normal" \| "high" \| "critical"

GET`/v1/settings/mail`

Remitente de los correos a clientes y estado del dominio de remitente propio.

Acceso propietario

PATCH`/v1/settings/mail`

Cambiar el nombre y la dirección del remitente.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
absenderName	Texto o null	como máximo 60 caracteres
postfachname	Texto	como máximo 40 caracteres

GET`/v1/settings/mail-templates`

Las plantillas de correo del espacio de trabajo, incluidos los textos predeterminados.

Acceso propietario

Respuesta

Campo	Tipo	Nota
vorlagen	Lista de Objeto

DELETE`/v1/settings/mail-templates/:kind`

Restablecer una plantilla de correo al texto predeterminado.

Acceso propietario

PUT`/v1/settings/mail-templates/:kind`

Guardar una plantilla de correo.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
subject *	Texto	al menos 1 caracteres \| como máximo 200 caracteres
html *	Texto	al menos 1 caracteres \| como máximo 102400 caracteres

Respuesta

Campo	Tipo	Nota
kind	"invoice_send" \| "invoice_reminder" \| "dunning" \| "invoice_cancellation" \| "quote_send" \| "ticket_reply" \| "ticket_receipt" \| "ticket_internal" \| "ticket_reopened" \| "member_invite" \| "portal_invite" \| "deletion_reminder"
angepasst	true \| false
subject	Texto o null
html	Texto o null
aktualisiertAm	Texto o null
bereinigt	true \| false

DELETE`/v1/settings/mail/domain`

Quitar el dominio de remitente propio.

Acceso propietario

POST`/v1/settings/mail/domain`

Crear un dominio de remitente propio; la respuesta enumera los registros DNS.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
adresse *	Texto	al menos 3 caracteres \| como máximo 254 caracteres

POST`/v1/settings/mail/domain/verify`

Hacer comprobar los registros DNS del dominio de remitente.

Acceso propietario

Suscripción a VentionDesk

GET`/v1/abo`

Estado de la suscripción a VentionDesk del espacio de trabajo: plan, prueba, suspensión.

Acceso propietario y miembros del equipo

Respuesta

Campo	Tipo	Nota
betrieb	Texto
tarif	"solo" \| "team" \| "enterprise"
abrechnung	"jaehrlich" \| "monatlich"
status	"trial" \| "active" \| "past_due" \| "canceled"
testphaseBis	Texto o null
laufzeitBis	Texto o null
kuendigtZum	Texto o null	puede faltar \| Predeterminado: null
loeschungAm	Texto o null	puede faltar \| Predeterminado: null
gesperrt	true \| false	puede faltar \| Predeterminado: false
sperrGrund	"beendet" \| "testphase" \| "zahlungsverzug" \| "anbieter" o null	puede faltar \| Predeterminado: null
sperreAb	Texto o null	puede faltar \| Predeterminado: null
plaetze	Entero o null
mitglieder	Entero
stripeKunde	true \| false
stripeAbo	true \| false	puede faltar \| Predeterminado: false
befreit	true \| false
stripeBereit	true \| false

POST`/v1/abo/cancel`

Cancelar la suscripción a VentionDesk al final del periodo.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
nonce *	Texto	patrón fijo
grund	"too_expensive" \| "missing_features" \| "switched_service" \| "unused" \| "too_complex" \| "low_quality" \| "customer_service" \| "other"
kommentar	Texto	como máximo 500 caracteres

Respuesta

Campo	Tipo	Nota
angenommen	true
ausstehend	true \| false	puede faltar
hinweis	Texto	puede faltar

POST`/v1/abo/change`

Cambiar el plan o la periodicidad de pago de la suscripción a VentionDesk.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
tarif *	"solo" \| "team" \| "enterprise"
abrechnung *	"jaehrlich" \| "monatlich"
plaetze *	Entero	≥ 1 \| ≤ 10000
nonce *	Texto	patrón fijo

POST`/v1/abo/checkout`

Contratar una suscripción a VentionDesk (redirige a Stripe Checkout).

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
tarif *	"solo" \| "team" \| "enterprise"
abrechnung *	"jaehrlich" \| "monatlich"

Respuesta

Campo	Tipo	Nota
url	URL

GET`/v1/abo/export`

Exportación de datos de todo el espacio de trabajo en ZIP (estructura: ver Exportación de datos).

Acceso propietario

POST`/v1/abo/preview`

Vista previa de un cambio de plan con el importe proporcional.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
tarif *	"solo" \| "team" \| "enterprise"
abrechnung *	"jaehrlich" \| "monatlich"
plaetze *	Entero	≥ 1 \| ≤ 10000

Respuesta

Campo	Tipo	Nota
waehrung	Texto
anteiligCent	Entero
rechnungCent	Entero
steuerCent	Entero
sofortCent	Entero
faelligAm	Texto o null
imTest	true \| false

GET`/v1/abo/rechnungen`

Las facturas de VentionDesk al espacio de trabajo.

Acceso propietario

Respuesta

Campo	Tipo	Nota
rechnungen	Lista de Objeto

POST`/v1/abo/resume`

Retirar una cancelación mientras el periodo sigue en curso.

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
nonce *	Texto	patrón fijo

Respuesta

Campo	Tipo	Nota
angenommen	true
ausstehend	true \| false	puede faltar
hinweis	Texto	puede faltar

GET`/v1/abo/verlauf`

Historial de la suscripción: alta, cambios, cancelación.

Acceso propietario

Respuesta

Campo	Tipo	Nota
eintraege	Lista de Objeto

POST`/v1/abo/zahlungsdaten`

Cambiar los datos de pago en Stripe (redirige a Stripe).

Acceso propietario

Cuerpo (JSON)

Campo	Tipo	Nota
nonce *	Texto	patrón fijo

Respuesta

Campo	Tipo	Nota
url	URL

GET`/v1/abo/zahlungsmittel`

El método de pago guardado para la suscripción.

Acceso propietario

Respuesta

Campo	Tipo	Nota
zahlungsmittel	Objeto o null

Entrada pública

POST`/f/:publicKey`

Formulario HTML en un sitio de terceros: crea un ticket (application/x-www-form-urlencoded).

Acceso clave pública del proyecto (vd_pub_…) en la URL

Respuesta

Campo	Tipo	Nota
ok	true
ticket	Objeto

POST`/v1/contact`

Formulario de contacto del sitio web de VentionDesk (/kontakt, enlazado desde el aviso legal).

Acceso público

Respuesta

Campo	Tipo	Nota
ok	true

POST`/v1/intake/reports`

Aviso desde el navegador de una app del cliente, opcionalmente con captura de pantalla, con la clave pública del proyecto.

Acceso clave pública del proyecto en la cabecera x-ventiondesk-key, origen permitido

Respuesta

Campo	Tipo	Nota
ok	true
ticket	Objeto

POST`/v1/intake/tickets`

Enviar un ticket de servidor a servidor, opcionalmente con captura de pantalla, con una clave de entrada.

Acceso clave de entrada (vd_intake_…) como Bearer

Respuesta

Campo	Tipo	Nota
ok	true
ticket	Objeto

POST`/v1/signup`

Registro de un nuevo espacio de trabajo, incluida la cuenta del propietario.

Acceso público

Respuesta

Campo	Tipo	Nota
ok	true
email	Correo electrónico
testphaseBis	Texto
checkoutUrl	URL o null	puede faltar \| Predeterminado: null

MCP

GET`/.well-known/oauth-protected-resource`

Metadatos del recurso protegido (RFC 9728): dirección MCP y servidor de autorización (Supabase Auth) para el inicio de sesión de una app de IA.

Acceso público

GET`/.well-known/oauth-protected-resource/mcp`

Los mismos metadatos bajo la ruta del recurso, para clientes que la añaden.

Acceso público

ALL`/mcp`

Cualquier método distinto de POST responde con 405 y Allow: POST.

Acceso público

POST`/mcp`

Servidor MCP sobre HTTP (sin estado): las herramientas para Claude, con una clave de agente o el token de una app de IA conectada. Sin un inicio de sesión válido, 401 con WWW-Authenticate y el camino a los metadatos.

Acceso clave de agente (vd_live_…) o token de una app de IA conectada como Bearer

Webhooks

POST`/webhooks/errors/:provider/:integrationId`

Webhook de un servicio de seguimiento de errores con firma en la cabecera (Sentry).

Acceso firma del proveedor

POST`/webhooks/errors/:provider/:integrationId/:token`

Webhook de un servicio de seguimiento de errores con el secreto en la URL (Bugsnag, Rollbar).

Acceso secreto en la URL

POST`/webhooks/stripe/:orgId`

Webhook de Stripe de la cuenta de Stripe propia de un espacio de trabajo: registra pagos y reembolsos de facturas.

Acceso firma Stripe-Signature

Operaciones y enlace de pago

GET`/api/health`

Señal de vida del servicio: responde mientras el proceso esté en marcha.

Acceso público

GET`/api/health/ready`

Disponibilidad: indica qué servicios están configurados; «degraded» sin base de datos.

Acceso público

GET`/pay/:token`

Enlace de pago de una factura: redirige (303) a la página de pago de Stripe. El enlace está en el correo de la factura y en el PDF.

Acceso token en la URL

GET`/pay/:token/abgebrochen`

Página de retorno cuando el pago se canceló en Stripe.

Acceso token en la URL

GET`/pay/:token/danke`

Página de retorno tras un pago correcto en Stripe.

Acceso token en la URL

Referencia de la API

Tareas

GET/v1/tasks

POST/v1/tasks

GET/v1/tasks/:id

PATCH/v1/tasks/:id

POST/v1/tasks/:id/claim

POST/v1/tasks/:id/decision

POST/v1/tasks/:id/handoff

POST/v1/tasks/:id/result

Ejecuciones de agentes

POST/v1/agent/runs

POST/v1/agent/runs/:id/finish

POST/v1/agent/runs/:id/heartbeat

Proyectos

POST/v1/errors/:id/resolve

POST/v1/errors/:id/task

GET/v1/errors/summary

POST/v1/monitors/probe

GET/v1/projects

GET/v1/projects/:id

PATCH/v1/projects/:id/customer

GET/v1/projects/:id/deploy

POST/v1/projects/:id/deploy

POST/v1/projects/:id/error-sources

DELETE/v1/projects/:id/error-sources/:sourceId

GET/v1/projects/:id/errors

GET/v1/projects/:id/hosting

POST/v1/projects/:id/hosting

DELETE/v1/projects/:id/hosting/:mappingId

DELETE/v1/projects/:id/render-services/:serviceId

GET/v1/projects/:id/report

GET/v1/projects/:id/roadmap

POST/v1/projects/:id/roadmap

PATCH/v1/projects/:id/roadmap/:phaseId

POST/v1/projects/:id/sync

GET/v1/projects/:id/time

GET/v1/projects/by-slug/:slug

Tickets

GET/v1/tickets

POST/v1/tickets

DELETE/v1/tickets/:id

GET/v1/tickets/:id

PATCH/v1/tickets/:id

POST/v1/tickets/:id/messages

POST/v1/tickets/:id/reply

POST/v1/tickets/:id/to-task

GET/v1/tickets/attachments/:id/url

Notas

POST/v1/notes

POST/v1/notes/:id/to-task

Ideas

POST/v1/ideas

Tiempo

GET/v1/time/entries

POST/v1/time/entries

DELETE/v1/time/entries/:id

PATCH/v1/time/entries/:id

GET/v1/time/timer

POST/v1/time/timer/start

POST/v1/time/timer/stop

GET/v1/time/unbilled

Clientes

DELETE/v1/customers/:id

GET/v1/customers/:id/deletion

POST/v1/customers/:id/portal-access

DELETE/v1/customers/:id/portal-access/:userId

POST/v1/customers/:id/portal-access/:userId/invite

Documentos

GET/v1/documents

PATCH/v1/documents/:id

GET/v1/documents/:id/url

Finanzas

GET/v1/finance/export

GET/v1/invoices

POST/v1/invoices

GET/v1/invoices/:id

POST/v1/invoices/:id/cancel

GET/v1/invoices/:id/cancellation/pdf

POST/v1/invoices/:id/cancellation/send

GET`/v1/tasks`

POST`/v1/tasks`

GET`/v1/tasks/:id`

PATCH`/v1/tasks/:id`

POST`/v1/tasks/:id/claim`

POST`/v1/tasks/:id/decision`

POST`/v1/tasks/:id/handoff`

POST`/v1/tasks/:id/result`

POST`/v1/agent/runs`

POST`/v1/agent/runs/:id/finish`

POST`/v1/agent/runs/:id/heartbeat`

POST`/v1/errors/:id/resolve`

POST`/v1/errors/:id/task`

GET`/v1/errors/summary`

POST`/v1/monitors/probe`

GET`/v1/projects`

GET`/v1/projects/:id`

PATCH`/v1/projects/:id/customer`

GET`/v1/projects/:id/deploy`

POST`/v1/projects/:id/deploy`

POST`/v1/projects/:id/error-sources`

DELETE`/v1/projects/:id/error-sources/:sourceId`

GET`/v1/projects/:id/errors`

GET`/v1/projects/:id/hosting`

POST`/v1/projects/:id/hosting`

DELETE`/v1/projects/:id/hosting/:mappingId`

DELETE`/v1/projects/:id/render-services/:serviceId`

GET`/v1/projects/:id/report`

GET`/v1/projects/:id/roadmap`

POST`/v1/projects/:id/roadmap`

PATCH`/v1/projects/:id/roadmap/:phaseId`

POST`/v1/projects/:id/sync`

GET`/v1/projects/:id/time`

GET`/v1/projects/by-slug/:slug`

GET`/v1/tickets`

POST`/v1/tickets`

DELETE`/v1/tickets/:id`

GET`/v1/tickets/:id`

PATCH`/v1/tickets/:id`

POST`/v1/tickets/:id/messages`

POST`/v1/tickets/:id/reply`

POST`/v1/tickets/:id/to-task`

GET`/v1/tickets/attachments/:id/url`

POST`/v1/notes`

POST`/v1/notes/:id/to-task`

POST`/v1/ideas`

GET`/v1/time/entries`

POST`/v1/time/entries`

DELETE`/v1/time/entries/:id`

PATCH`/v1/time/entries/:id`

GET`/v1/time/timer`

POST`/v1/time/timer/start`

POST`/v1/time/timer/stop`

GET`/v1/time/unbilled`

DELETE`/v1/customers/:id`

GET`/v1/customers/:id/deletion`

POST`/v1/customers/:id/portal-access`

DELETE`/v1/customers/:id/portal-access/:userId`

POST`/v1/customers/:id/portal-access/:userId/invite`

GET`/v1/documents`

PATCH`/v1/documents/:id`

GET`/v1/documents/:id/url`

GET`/v1/finance/export`

GET`/v1/invoices`

POST`/v1/invoices`

GET`/v1/invoices/:id`

POST`/v1/invoices/:id/cancel`

GET`/v1/invoices/:id/cancellation/pdf`

POST`/v1/invoices/:id/cancellation/send`

POST`/v1/invoices/:id/dunning/send`

POST`/v1/invoices/:id/finalize`

POST`/v1/invoices/:id/payments`

GET`/v1/invoices/:id/pdf`

POST`/v1/invoices/:id/positions`

DELETE`/v1/invoices/:id/positions/:positionId`

PATCH`/v1/invoices/:id/positions/:positionId`

POST`/v1/invoices/:id/remind`

POST`/v1/invoices/:id/send`

GET`/v1/invoices/:id/stripe-refund`

POST`/v1/invoices/:id/stripe-refund`