Entrada de tickets

La entrada de tickets acepta avisos de fuera — del formulario de contacto del sitio de un cliente, de una app o de un servidor. Las tres vías crean un ticket en el proyecto correspondiente, con el plazo de respuesta del contrato del cliente.

Además están el correo y los monitores — más abajo.

Todo se configura en un solo lugar: Ajustes › Entrada de tickets (solo el propietario). Allí aparece cada proyecto con el estado medido de su entrada; un clic lo despliega y muestra las tres tarjetas «Servidor y app» (claves de entrada), «Entrada pública de tickets» (formulario y navegador) y «Entrada por correo» (buzones). Desde la página del proyecto, «Configurar» en la fila «Entrada de tickets» del resumen lleva directamente al proyecto desplegado. VentionDesk reconoce por qué vía llegó un ticket por la URL a la que se entregó — no por nada que indique el remitente.

Antes de configurarla: Quien escribe a través del formulario o de la app te entrega datos personales a ti y, con ello, a VentionDesk como proveedor de servicios. Configura la entrada para el sitio de un cliente solo cuando exista el contrato de encargo del tratamiento con tu cliente, e indícalo en el sitio — el código del formulario de abajo incluye para ello una frase con un enlace a la política de privacidad de tu cliente.

Configurar la clave pública y los orígenes

En Ajustes › Entrada de tickets, despliega el proyecto, tarjeta «Entrada pública de tickets»:

1. «Configurar entrada» crea la clave pública vd_pub_…. «Copiar» la pone en el portapapeles.
2. En «Orígenes permitidos» introduces cada dirección desde la que pueden llegar avisos del navegador — solo esquema, host y puerto, es decir https://kunde.de, sin ruta y sin barra final. VentionDesk compara literalmente.
3. Sin ningún origen introducido, la vía del navegador no acepta nada. El formulario HTML y la vía de servidor no se ven afectados.
4. «Desactivar la entrada» vuelve a eliminar la clave.

La clave pública no es secreta — está en el código fuente del sitio del cliente. Solo puede crear tickets en exactamente este proyecto.

Vía 1: formulario HTML

Un formulario normal que envía a https://in.ventiondesk.com/f/<clave pública>. El código listo lo copias en VentionDesk en Tickets › «?» › «Copiar código del formulario»:

<form method="post" action="https://in.ventiondesk.com/f/DEIN_PUBLIC_KEY">
  <input name="name" placeholder="Ihr Name" required />
  <input name="email" type="email" placeholder="Ihre E-Mail" required />
  <input name="subject" placeholder="Betreff" required />
  <textarea name="message" placeholder="Ihre Nachricht" required></textarea>
  <p>Mit dem Absenden werden Ihre Angaben zur Bearbeitung an unseren Dienstleister
    übermittelt. Mehr dazu in unserer <a href="DEINE_DATENSCHUTZERKLAERUNG">Datenschutzerklärung</a>.</p>
  <button type="submit">Absenden</button>
</form>

Sustituye DEIN_PUBLIC_KEY por la clave pública y DEINE_DATENSCHUTZERKLAERUNG por la política de privacidad del sitio del cliente.

Opcional:

• _redirect — una URL absoluta a la que se redirige el navegador tras el envío (303). Su origen debe figurar en «Orígenes permitidos»; si no, VentionDesk responde con JSON.
• _hp — un honeypot contra bots: un campo oculto y vacío. Si se rellena, VentionDesk responde amablemente y no crea nada.
• cf-turnstile-response — el token de Cloudflare Turnstile, ver abajo.

Sin _redirect, VentionDesk responde con 201 y { "ok": true, "ticket": { "id": "…", "key": "TK-1044" } }.

Vía 2: aviso desde el navegador

POST https://api.ventiondesk.com/v1/intake/reports con la clave pública en la cabecera x-ventiondesk-key — desde una app web cuyo origen figure en «Orígenes permitidos»:

await fetch('https://api.ventiondesk.com/v1/intake/reports', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-ventiondesk-key': 'vd_pub_…' },
  body: JSON.stringify({
    text: 'Saving does nothing',
    email: 'user@customer.com',
    screenshot: 'data:image/png;base64,…',
    meta: { url: location.origin + location.pathname, severity: 'high' },
  }),
});

• text (obligatorio): de 5 a 5.000 caracteres. email: opcional.
• screenshot: opcional, como data URL (data:image/png, image/jpeg o image/webp en Base64), de menos de 500 kB. La imagen se adjunta al ticket.
• meta: opcional — device, version, user, url y severity (low, normal, high, critical). critical pone la prioridad del ticket en «Crítica».
• turnstileToken: opcional, ver abajo.

El paquete @ventiondesk/sdk envuelve exactamente esta llamada (ventiondesk.init({ publicKey }) y después ventiondesk.report({ text, screenshot })); de momento no está publicado en npm. El fetch de arriba hace lo mismo.

Vía 3: de servidor a servidor

Si el sitio del cliente tiene su propio backend, envía con una clave de entrada. La creas en Ajustes › Entrada de tickets: el «+» arriba a la derecha de la sección y después eliges el proyecto — una clave de entrada vale para exactamente un proyecto y aparece luego en ese proyecto en «Servidor y app». La clave es secreta y solo debe estar en el servidor, nunca en el navegador.

curl -X POST https://api.ventiondesk.com/v1/intake/tickets \
  -H "Authorization: Bearer vd_intake_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Miller","email":"j.miller@customer.com","subject":"Login does not work","message":"Since this morning I can no longer get into my account."}'

Los campos son los mismos que en el formulario, más, opcionalmente, screenshot (como arriba) y meta (hasta 20 valores simples). Una clave de entrada no puede hacer nada salvo enviar — no puede leer tareas ni ver tickets.

Turnstile contra bots

Si Cloudflare Turnstile está activado por parte de VentionDesk, el formulario y la vía del navegador exigen un token de Turnstile (cf-turnstile-response o turnstileToken). Si falta, VentionDesk responde con 403. De fábrica, esta comprobación está desactivada para la entrada: el formulario y la vía del navegador están en tus páginas, y un widget de Turnstile solo funciona en los dominios de su clave de sitio. Solo se activa previo acuerdo; entonces tu página necesita su propio widget con una clave de sitio válida para su dominio. Si Cloudflare no responde, VentionDesk deja pasar el aviso y lo marca como no verificado — una caída en Cloudflare no debe costar ninguna solicitud de un cliente. La vía de servidor a servidor no necesita Turnstile.

Comprobar: ¿llega algo?

La clave pública y cada clave de entrada en «Ajustes › Entrada de tickets» muestran «último aviso hace …» o «todavía sin avisos» — medido en intentos reales. Si el último intento se rechazó, se muestra el motivo:

Límites

Cada vía de entrada acepta hasta 10 avisos por minuto por dirección IP; una solicitud puede ocupar como máximo 1 MB.

Correo

Los correos al buzón de tu espacio de trabajo se convierten en tickets; el nombre del buzón lo fijas en Ajustes › Remitente de correo. Si un cliente responde a un correo de VentionDesk, la respuesta llega al mismo ticket — reconocida por las cabeceras del correo, por el número de ticket en la dirección (buzon+TK-1044@…) o por [TK-1044] en el asunto. En la tarjeta «Entrada por correo» de un proyecto, en Ajustes › Entrada de tickets, asignas direcciones a ese proyecto; las direcciones de otro dominio necesitan allí un reenvío.

Qué direcciones crean un ticket nuevo: solo las registradas. Son el buzón de tu espacio de trabajo (también un nombre de buzón anterior y cada dirección con «+» de él), las direcciones de la tarjeta «Entrada por correo» de tus proyectos y las direcciones de inicio de sesión de los miembros de tu espacio de trabajo. Un correo a cualquier otra dirección no se convierte en ticket y no aparece en ningún sitio — así, los correos que los bots de spam envían a direcciones inventadas no acaban en tu entrada. Las respuestas a un ticket existente llegan siempre, sea cual sea la dirección a la que vayan. Si falta un correo, introduce su dirección en la tarjeta «Entrada por correo» del proyecto correspondiente.

Acuse de recibo por correo: solo se envía a remitentes que conoces — el ticket está asignado a un cliente, o la dirección es la de un cliente o de una cuenta del portal de tu espacio de trabajo. Para un remitente desconocido no sale ningún correo automático; en su lugar aparece una nota interna en el historial, y respondes a mano si la solicitud es auténtica. Por formulario, widget de app y vía de servidor, también los nuevos interesados reciben su acuse.

Monitores

En la pestaña Analítica de un proyecto creas monitores (URL, tipo «Disponibilidad» o «Certificado», intervalo). Si un monitor falla dos veces seguidas, VentionDesk abre un ticket; en cuanto vuelve a estar accesible, el ticket se resuelve.