API de formularios (administración)

Estos son los endpoints con los que la pantalla Ajustes › Integraciones › Formularios de captación, necesitas entrar con tu cuenta gestiona los formularios: listarlos, crearlos, editarlos, publicarlos, pausarlos, archivarlos, ver sus estadísticas y obtener el código de inserción.

Exigen la sesión de una persona de tu organización (el token que obtiene al iniciar sesión en UTILIA OS), no una clave de API ni un token de OAuth. Si quieres gestionar formularios desde fuera, por ejemplo desde un asistente de IA, usa la herramienta MCP org_integrations_settings del servidor CRM, con sus operaciones lead_forms_* y los scopes crm:lead-forms:view (consultar) y crm:lead-forms:manage (crear y cambiar). Tienes cómo conectarte en Copiloto y MCP.

Plan y permisos

Cada llamada pasa dos puertas, en este orden:

1. El plan de la organización: el aplicativo CRM con la capacidad de leads (crm.leads). Sin él, todos los endpoints responden 403 con errorCode MODULE_NOT_ENABLED o CAPABILITY_NOT_ENABLED, aunque la persona tenga el permiso.
2. El permiso de la persona:

El Super Administrador y el Gerente ven y gestionan todos los formularios de la organización; el resto de roles, solo los que han creado. Con un formulario ajeno, la respuesta es 403.

Endpoints

Estados

Un formulario solo acepta envíos mientras está «Activo». Cada endpoint de estado responde 400 si el formulario ya estaba en el estado que pides.

publish funciona desde cualquier estado que no sea «Activo», y pause, desde cualquiera que no sea «Pausado». Desarchivar recupera la edición, no la publicación: el código pegado en tu web vuelve a valer en cuanto publiques el formulario otra vez.

Código de inserción

GET /api/lead-forms/:id/snippet devuelve el slug, el tipo de formulario, el código HTML (inlineSnippet y widgetSnippet, que hoy son idénticos) y la dirección de su configuración pública (apiEndpoint). Cómo usar ese código está en Insertar un formulario en tu web.

Catálogo de tipos de campo

GET /api/lead-forms/field-types/catalog devuelve { "types": [...] }, con una entrada por tipo (type, label, description y, cuando aplica, el leadField al que va por convención y su validation). Qué hace cada tipo está en Definición de los campos.

Cuerpo de creación y edición

POST exige name y fields; en PATCH todo es opcional. Al guardar, el servidor añade el consentimiento informativo obligatorio si los campos no traen uno. El detalle de fields está en Definición de los campos, y el de styling, en El objeto styling.

La respuesta de POST incluye apiKeyFull, la clave de API completa del formulario. Es la única vez que aparece entera: en las consultas posteriores solo verás su prefijo. La persona que creó el formulario puede regenerarla en Ajustes › Seguridad › Claves de acceso (API), necesitas entrar con tu cuenta; al hacerlo, la anterior deja de funcionar.

Errores

Un bloqueo de plan no se arregla reintentando ni dando permisos: hay que ampliar el plan. Más detalle en Errores de plan.

Ejemplo

# Crear un formulario
curl -X POST 'https://os.utilia.ai/api/lead-forms' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer TU_TOKEN_DE_SESION' \
  -d '{
    "name": "Formulario de contacto web",
    "fields": [
      { "id": "field_email", "type": "email", "label": "Correo electrónico", "required": true, "order": 1, "leadField": "email", "width": 12 },
      { "id": "field_nombre", "type": "text", "label": "Nombre completo", "required": true, "order": 2, "leadField": "fullName", "width": 12 }
    ],
    "widgetType": "POPUP",
    "widgetTrigger": "button",
    "allowedOrigins": ["https://tuempresa.com"]
  }'
 
# Publicarlo
curl -X PATCH 'https://os.utilia.ai/api/lead-forms/clx1234567890/publish' \
  -H 'Authorization: Bearer TU_TOKEN_DE_SESION'

Respuesta de la creación (resumida):

{
  "id": "clx1234567890",
  "name": "Formulario de contacto web",
  "slug": "a1b2c3d4e5",
  "status": "DRAFT",
  "widgetType": "POPUP",
  "widgetTrigger": "button",
  "apiKeyFull": "utl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "createdAt": "2026-10-08T10:00:00.000Z"
}

Siguiente paso

Publica el formulario y pega su código en tu web siguiendo Insertar un formulario en tu web. Los leads que entren aparecerán en el CRM, como se explica en Formularios de captación.