Ir al contenido

Comunicación: recibir solicitudes en tus formularios

Los formularios de Comunicación reciben solicitudes (contacto, cotización, reclamo, ejercicio de derechos sobre datos personales) y cada una entra a la bandeja del equipo de la empresa como un caso con número, plazo y responsable. La persona que escribió recibe un acuse por correo con ese número.

Esta ficha cubre la puerta de servidor: el sistema de la persona ya tiene los datos (un pedido, un ticket) y crea la solicitud directamente en un formulario publicado, con o sin archivos adjuntos, y después se entera por webhook cuando el equipo la resuelve. La misma solicitud puede entrar por otras dos puertas (el formulario alojado y un formulario HTML propio, descritas más abajo); las tres crean el mismo caso.

Lo que esta ficha no hace: la llave de esta puerta sólo crea solicitudes y sube sus archivos. No lee casos, no lista formularios y no configura nada; crear y publicar formularios, ver la bandeja y descargar los archivos de un caso son tareas del panel, de una persona. Para enviar mensajes de WhatsApp por plantilla, ve a WhatsApp.

  • El servicio Comunicación habilitado en la empresa. Si no lo tiene, las operaciones responden 403 y lo dicen.
  • Un formulario publicado. Se crea y se publica en el panel, en Comunicación, tipos de solicitud y formularios. Uno en borrador o despublicado responde 409 FORMULARIO_NO_PUBLICADO; uno archivado, 404. De ese formulario necesitas dos datos, que sólo ve una persona en el panel:
    • El identificador del formulario (idPublico): 22 letras y números, en la pestaña Publicar, sección «Enviar desde tu servidor».
    • La clave de cada campo: en la pestaña Campos, el «Identificador interno» de cada uno (por ejemplo correo o mensaje). Una vez guardado un campo su clave no cambia; si se elimina un campo y se crea otro, la clave es otra. Pídeselos a la persona; no los adivines ni los inventes.
  • Una llave con el rol COMUNICACION_SOLICITUDES_CREAR. La crea un administrador de la empresa en el panel, en General → API Keys, eligiendo el rol «Comunicación — crear solicitudes» y, para probar, activando «Llave de prueba». El rol es angosto a propósito: con esa llave cualquier otra operación responde 403, de modo que una llave filtrada no permite leer ninguna solicitud. La llave del proyecto que instala redcumbre init es FULL-API; la operación declara el rol COMUNICACION_SOLICITUDES_CREAR (redcumbre api describir crearSolicitudComunicacion lo muestra).
  • El archivo de esa llave en el proyecto. La pantalla de API Keys permite descargarla como JSON, con el mismo formato que keys/redcumbre-prueba.json. La persona lo deja en keys/ (por ejemplo keys/comunicacion-prueba.json). No lo leas, no lo imprimas ni le pidas que pegue el secreto en el chat.
  • Cómo funciona el modo de prueba y qué cambia en producción: Modo de prueba y producción. Paginación, errores y límites: Reglas comunes. Firma, eventos y reintentos de los avisos: Webhooks.

Vale para la puerta de servidor y para la pública. Todo va en campos, por clave de campo, salvo los archivos:

Tipo de campo (en el panel)Valor en campos
Texto cortoTexto, hasta 200 caracteres
Texto largoTexto, hasta 5.000 caracteres
Correo electrónicoTexto con un correo válido, hasta 254 caracteres
TeléfonoTexto, hasta 20 caracteres
RUTTexto, con o sin puntos y guion. Se valida el dígito verificador
Lista de opcionesEl valor de la opción, no su etiqueta. Si admite varias, un arreglo de valores sin repetir
Casillatrue o false. Una casilla obligatoria o de declaración tiene que ir en true
ArchivoNo va en campos: va en archivos, con su archivoId

Un campo obligatorio que falta, o un valor que no cumple su tipo, responde 422 CAMPO_INVALIDO con el campo y el motivo: nunca se rellena un valor ni se crea la solicitud a medias. Una clave que el formulario no define responde 422 CAMPO_NO_DEFINIDO con la lista de claves y no crea nada. Manda sólo las claves que el formulario define.

  1. Ubica y lee la operación.

    Ventana de terminal
    redcumbre buscar "crear una solicitud en un formulario de comunicación"
    redcumbre api describir crearSolicitudComunicacion

    Resultado esperado: la operación crearSolicitudComunicacion (POST a las solicitudes de Comunicación de la empresa), su efecto (envia), su métrica (comunicacion_formulario_envio), su rol y que la clave de repetición es claveIdempotencia, en el cuerpo.

  2. Arma el cuerpo con los datos del formulario. formulario, claveIdempotencia (de 8 a 100 caracteres) y campos son obligatorios; referencia (hasta 200 caracteres) queda con la solicitud y vuelve en cada aviso; persona.idExterno (hasta 100) es el identificador de la persona en el sistema de ella; archivos lleva el archivoId de cada campo de tipo archivo.

    {
    "formulario": "4fT9kQ2mXbR7vLpZ1cN8sW",
    "claveIdempotencia": "contacto-pedido-4471",
    "referencia": "pedido-4471",
    "persona": { "idExterno": "cliente-0932" },
    "campos": {
    "correo": "ana.prueba@ejemplo.cl",
    "mensaje": "El pedido llegó incompleto."
    }
    }

    Cambia formulario por el identificador real y campos por las claves de ese formulario. La claveIdempotencia tiene que ser estable y de tu sistema (el número del pedido más el motivo del contacto, el id del ticket), no un UUID nuevo en cada intento: un UUID por intento no protege de nada, porque cada reintento sería una solicitud distinta. El correo que mandas por esta puerta queda registrado como confiable: no lo mandes como verificado si tu sistema no lo verificó.

  3. Ensaya y crea la solicitud en modo de prueba. Apunta la variable de la llave de prueba al archivo de la llave de Comunicación, sólo en ese comando:

    Ventana de terminal
    REDCUMBRE_LLAVE_PRUEBA=keys/comunicacion-prueba.json redcumbre api crearSolicitudComunicacion --cuerpo @solicitud.json --ensayo
    REDCUMBRE_LLAVE_PRUEBA=keys/comunicacion-prueba.json redcumbre api crearSolicitudComunicacion --cuerpo @solicitud.json

    Resultado esperado: el ensayo muestra la petición sin hacerla. La ejecución responde 201 con el número del caso, sandbox y el bloque cobro en modo de prueba:

    { "numero": 42, "sandbox": true, "cobro": { "modo": "prueba", "mensaje": "En modo de prueba no se cobra." } }

    La respuesta no trae nada más: ni el estado, ni la persona, ni los campos. numero es el mismo que ve el equipo en la bandeja.

  4. Comprueba el reintento seguro. Repite el mismo comando con la misma claveIdempotencia.

    Resultado esperado: 200 con el mismo numero; no se crea otra solicitud y la persona no recibe otro acuse. El primer envío responde 201. La clave vale por empresa y la llave de prueba y la de producción tienen cada una su espacio: una clave usada probando no choca con la misma en producción.

  5. Mira el acuse que habría salido. En modo de prueba nadie recibe correo: el acuse queda en la bandeja de mensajes simulados.

    Ventana de terminal
    redcumbre bandeja --canal correo

    Resultado esperado: el correo de acuse a la dirección que mandaste, retenido en vez de enviado.

  6. Adjunta un archivo (si el formulario tiene un campo de tipo archivo). Son dos pasos: primero subes cada archivo y después creas la solicitud con los identificadores.

    • La subida (crearArchivoSolicitudComunicacion) es multipart/form-data con el archivo en el campo archivo. redcumbre api envía JSON, no multipart: esta subida la hace el código del proyecto, que lee la llave de la ruta del archivo.
    • Devuelve { "archivoId": "…", "sandbox": … }. Ese archivoId va en archivos, bajo la clave del campo:
    {
    "formulario": "4fT9kQ2mXbR7vLpZ1cN8sW",
    "claveIdempotencia": "reclamo-pedido-4471",
    "campos": { "correo": "ana.prueba@ejemplo.cl", "mensaje": "Adjunto la boleta." },
    "archivos": { "comprobante": "cmb2x7k1p0003qz8f4h2d9n1e" }
    }

    Reglas: PDF, JPEG y PNG reconocidos por su contenido (un ejecutable renombrado .pdf se rechaza al subirlo); hasta 10 MB por archivo (más grande: 413); hasta 10 subidas por llave cada 24 horas; el archivo queda ligado a la llave que lo subió (crear la solicitud con otra responde 422 ARCHIVO_NO_DISPONIBLE); y uno que no se usa en 24 horas se borra. El equipo descarga los archivos desde el caso en el panel: no hay una dirección pública del archivo.

  7. Recibe los avisos. Ninguna puerta lee solicitudes: lo que pasa después te llega por webhook, con tres eventos de Comunicación. Suscríbete en el panel, en General → Webhooks.

    EventoCuándo
    solicitud.creadaSe creó una solicitud, entrara por la puerta que entrara
    solicitud.resueltaEl equipo la cerró; trae el motivo (por ejemplo respondida o descartada)
    solicitud.reabiertaUna solicitud cerrada se volvió a abrir
    {
    "event": "solicitud.resuelta",
    "data": {
    "numero": 42,
    "tipo": "contacto",
    "estado": "resuelto",
    "motivo": "respondida",
    "referencia": "pedido-4471",
    "puerta": "servidor",
    "retenidaPorCuota": false,
    "ocurridoAt": "2026-10-20T14:05:12.000Z"
    },
    "timestamp": "2026-10-20T14:05:13.000Z",
    "sandbox": false
    }

    referencia es la que mandaste al crear (si no mandaste, el campo no viene): úsala para amarrar el aviso con el registro de tu sistema. estado es abierto en solicitud.creada y solicitud.reabierta, y resuelto en solicitud.resuelta. puerta dice por dónde entró (servidor, publica o alojada; una solicitud que el equipo creó dentro de la bandeja trae conversion, cambio_tipo o respuesta_tardia). El aviso no trae datos de la persona: ni nombre, ni correo, ni valores de los campos. La firma HMAC, los reintentos y la verificación son los de todos los webhooks: Webhooks.

    Los eventos solicitud.* no se disparan con redcumbre eventos disparar. En modo de prueba se provocan creando una solicitud con la llave de prueba (paso 3): los avisos salen firmados con el secreto de prueba y llegan a la URL de prueba, nunca a la de producción.

La misma solicitud entra por otras dos puertas, sin credencial y con captcha. Estas rutas no están en el documento público de la API; su referencia es la guía Formularios de Comunicación.

  • Alojada: la plataforma dibuja el formulario. En la pestaña Publicar el panel entrega el enlace y el código para incrustarlo en el sitio; no se programa nada.
  • Pública (formulario HTML propio): el navegador de la persona llama, sin cookies ni cabeceras propias, a tres rutas bajo /public/comunicacion/formularios/{idPublico}: GET de la definición (trae la sesion, válida 2 horas), GET …/desafio (un captcha de prueba de trabajo que el navegador resuelve solo, válido para un solo envío y por 5 minutos) y POST …/envios con sesion, altcha, trampa y campos. Agrega un input oculto para las personas y manda su valor en trampa: llena, el envío responde 200 { "numero": null } sin crear nada. Los topes son 5 envíos por hora por visitante y por formulario, 30 por hora por IP y 1.000 al día por empresa (429 CUOTA_DIARIA_ALCANZADA).
  • La puerta pública no tiene modo de prueba: cada envío crea una solicitud de verdad y manda el acuse a la persona; su precio depende de tu plan (redcumbre tarifas crearSolicitudComunicacion --produccion). Prueba con un correo propio y resuelve el caso en la bandeja con el motivo «Descartada».
  • La creación responde 201 con un numero, y en modo de prueba sandbox: true y cobro.modo: "prueba".
  • El mismo comando con la misma claveIdempotencia responde 200 con el mismo numero.
  • redcumbre bandeja --canal correo muestra el acuse retenido (modo de prueba).
  • Con el webhook de prueba suscrito, llega solicitud.creada firmado con el secreto de prueba y con tu referencia.
  • En producción, además, la persona del equipo ve el caso con ese número en la bandeja de Comunicación.
Si vesSignificaQué haces
401Falta la llave, no es válida o fue revocadaNo reintentes. Revisa la llave que usa el comando
403La llave no tiene el rol COMUNICACION_SOLICITUDES_CREAR, o la empresa no tiene el servicio ComunicaciónNo reintentes. Pide a la persona una llave con ese rol o que habilite el servicio
404El formulario no existe en la empresa o está archivadoNo reintentes. Revisa el identificador
409 FORMULARIO_NO_PUBLICADOEl formulario está en borrador o despublicadoNo reintentes hasta que alguien lo publique en el panel
422 CAMPO_NO_DEFINIDOMandaste claves que el formulario no tiene (vienen en campos)Corrige el cuerpo: manda sólo las claves del formulario
422 CAMPO_INVALIDOFalta un obligatorio o un valor no cumple su tipo (vienen campo y motivo)Corrige el cuerpo
422 ARCHIVO_TIPO_NO_PERMITIDOAl subir: el contenido no es PDF, JPEG ni PNGSube otro archivo
422 ARCHIVO_NO_DISPONIBLEEl archivo no existe, venció o lo subió otra llaveSúbelo de nuevo con la misma llave
413Al subir: el archivo pasa de 10 MBReduce el archivo
5xxError del lado de REDCUMBREReintenta con la misma claveIdempotencia

Los 422 llevan el código en error: decide por el código, no por el texto de message. La forma general de los errores está en Reglas comunes.

  • Qué cambia: cada solicitud crea un caso en la bandeja del equipo y le manda un acuse por correo a la persona. Cada solicitud cuenta como un envío de formulario; no cuentan un reintento con la misma clave, un envío rechazado ni una solicitud de prueba. Lo que cuesta depende de tu plan: redcumbre tarifas crearSolicitudComunicacion --produccion.

  • La llave: hace falta otra llave con el mismo rol COMUNICACION_SOLICITUDES_CREAR, creada sin «Llave de prueba». La crea la persona en General → API Keys; no la pegues en el chat ni en el repositorio.

  • El comando:

    Ventana de terminal
    REDCUMBRE_LLAVE_PRODUCCION=keys/comunicacion-produccion.json redcumbre api crearSolicitudComunicacion --cuerpo @solicitud.json --produccion --confirmar <empresa>

    Pide a la persona su confirmación antes: la solicitud le llega a una persona. No verificado: que las comprobaciones previas que hace el CLI en producción (identidad de la empresa y consumo del plan) las acepte una llave de rol angosto; si se detiene ahí, la creación la hace el código del proyecto.

  • En el código del proyecto: claveIdempotencia estable, reintento sólo ante 5xx y con la misma clave, y los avisos de producción llegando a una URL https con la firma verificada.

  • Más detalle: Modo de prueba y producción.