Comunicación: recibir solicitudes en tus formularios
Qué resuelve
Sección titulada «Qué resuelve»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.
Qué necesitas antes
Sección titulada «Qué necesitas antes»- El servicio Comunicación habilitado en la empresa. Si no lo tiene, las operaciones responden
403y 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
correoomensaje). 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.
- El identificador del formulario (
- 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 responde403, de modo que una llave filtrada no permite leer ninguna solicitud. La llave del proyecto que instalaredcumbre initesFULL-API; la operación declara el rolCOMUNICACION_SOLICITUDES_CREAR(redcumbre api describir crearSolicitudComunicacionlo 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 enkeys/(por ejemplokeys/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.
Qué valor lleva cada tipo de campo
Sección titulada «Qué valor lleva cada tipo de campo»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 corto | Texto, hasta 200 caracteres |
| Texto largo | Texto, hasta 5.000 caracteres |
| Correo electrónico | Texto con un correo válido, hasta 254 caracteres |
| Teléfono | Texto, hasta 20 caracteres |
| RUT | Texto, con o sin puntos y guion. Se valida el dígito verificador |
| Lista de opciones | El valor de la opción, no su etiqueta. Si admite varias, un arreglo de valores sin repetir |
| Casilla | true o false. Una casilla obligatoria o de declaración tiene que ir en true |
| Archivo | No 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.
-
Ubica y lee la operación.
Ventana de terminal redcumbre buscar "crear una solicitud en un formulario de comunicación"redcumbre api describir crearSolicitudComunicacionResultado esperado: la operación
crearSolicitudComunicacion(POSTa 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 esclaveIdempotencia, en el cuerpo. -
Arma el cuerpo con los datos del formulario.
formulario,claveIdempotencia(de 8 a 100 caracteres) ycamposson 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;archivoslleva elarchivoIdde 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
formulariopor el identificador real ycampospor las claves de ese formulario. LaclaveIdempotenciatiene 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ó. -
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 --ensayoREDCUMBRE_LLAVE_PRUEBA=keys/comunicacion-prueba.json redcumbre api crearSolicitudComunicacion --cuerpo @solicitud.jsonResultado esperado: el ensayo muestra la petición sin hacerla. La ejecución responde
201con el número del caso,sandboxy el bloquecobroen 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.
numeroes el mismo que ve el equipo en la bandeja. -
Comprueba el reintento seguro. Repite el mismo comando con la misma
claveIdempotencia.Resultado esperado:
200con el mismonumero; no se crea otra solicitud y la persona no recibe otro acuse. El primer envío responde201. 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. -
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 correoResultado esperado: el correo de acuse a la dirección que mandaste, retenido en vez de enviado.
-
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) esmultipart/form-datacon el archivo en el campoarchivo.redcumbre apienví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": … }. EsearchivoIdva enarchivos, 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
.pdfse 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 responde422 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. - La subida (
-
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.
Evento Cuándo solicitud.creadaSe creó una solicitud, entrara por la puerta que entrara solicitud.resueltaEl equipo la cerró; trae el motivo(por ejemplorespondidaodescartada)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}referenciaes la que mandaste al crear (si no mandaste, el campo no viene): úsala para amarrar el aviso con el registro de tu sistema.estadoesabiertoensolicitud.creadaysolicitud.reabierta, yresueltoensolicitud.resuelta.puertadice por dónde entró (servidor,publicaoalojada; una solicitud que el equipo creó dentro de la bandeja traeconversion,cambio_tipoorespuesta_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 conredcumbre 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.
Si el formulario va en un sitio web
Sección titulada «Si el formulario va en un sitio web»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}:GETde la definición (trae lasesion, 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) yPOST …/enviosconsesion,altcha,trampaycampos. Agrega un input oculto para las personas y manda su valor entrampa: llena, el envío responde200 { "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».
Cómo saber que funcionó
Sección titulada «Cómo saber que funcionó»- La creación responde
201con unnumero, y en modo de pruebasandbox: trueycobro.modo: "prueba". - El mismo comando con la misma
claveIdempotenciaresponde200con el mismonumero. redcumbre bandeja --canal correomuestra el acuse retenido (modo de prueba).- Con el webhook de prueba suscrito, llega
solicitud.creadafirmado con el secreto de prueba y con tureferencia. - En producción, además, la persona del equipo ve el caso con ese número en la bandeja de Comunicación.
Qué puede fallar
Sección titulada «Qué puede fallar»| Si ves | Significa | Qué haces |
|---|---|---|
401 | Falta la llave, no es válida o fue revocada | No reintentes. Revisa la llave que usa el comando |
403 | La llave no tiene el rol COMUNICACION_SOLICITUDES_CREAR, o la empresa no tiene el servicio Comunicación | No reintentes. Pide a la persona una llave con ese rol o que habilite el servicio |
404 | El formulario no existe en la empresa o está archivado | No reintentes. Revisa el identificador |
409 FORMULARIO_NO_PUBLICADO | El formulario está en borrador o despublicado | No reintentes hasta que alguien lo publique en el panel |
422 CAMPO_NO_DEFINIDO | Mandaste claves que el formulario no tiene (vienen en campos) | Corrige el cuerpo: manda sólo las claves del formulario |
422 CAMPO_INVALIDO | Falta un obligatorio o un valor no cumple su tipo (vienen campo y motivo) | Corrige el cuerpo |
422 ARCHIVO_TIPO_NO_PERMITIDO | Al subir: el contenido no es PDF, JPEG ni PNG | Sube otro archivo |
422 ARCHIVO_NO_DISPONIBLE | El archivo no existe, venció o lo subió otra llave | Súbelo de nuevo con la misma llave |
413 | Al subir: el archivo pasa de 10 MB | Reduce el archivo |
5xx | Error del lado de REDCUMBRE | Reintenta 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.
Antes de pasar a producción
Sección titulada «Antes de pasar a producción»-
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:
claveIdempotenciaestable, reintento sólo ante5xxy con la misma clave, y los avisos de producción llegando a una URLhttpscon la firma verificada. -
Más detalle: Modo de prueba y producción.