Crear un formulario y una solicitud en una sola llamada

Cuándo usarlo

Normalmente, una solicitud apunta a un formulario que alguien creó en el editor y publicó. Cuando las preguntas dependen del caso, el llamante las envía con la solicitud: requests.create acepta form en lugar de formId. Formstep crea un formulario normal a partir de los bloques, lo publica y crea la solicitud en un solo paso, así que existen los dos o ninguno. Lo llamamos formulario integrado.

Sigue usando formId para un formulario que envías a muchas personas con la misma forma y quieres diseñar a mano en el editor. Usa form cuando una automatización decide qué preguntar.

La llamada

curl -X POST https://api.formstep.io/api/v1 \
  -H "Authorization: Bearer $FORMSTEP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"method":"requests.create","params":{
        "form":{
          "name":"Documents and fee for your mortgage application",
          "logo":{"type":"image","url":"https://acme.example/logo.png"},
          "cover":{"type":"color","color":"#0f4c81"},
          "emoji":"🏦",
          "blocks":[
            {"type":"paragraph","content":"Upload the two documents and pay the processing fee."},
            {"type":"file","key":"payslips","title":"Your last two payslips","maxFiles":2},
            {"type":"payment","key":"fee","title":"Processing fee","amount":40,"currency":"EUR"},
            {"type":"scheduleAppointment","key":"call","title":"Pick a time for our call","eventType":"15 min call"}]},
        "recipient":{"email":"ada@example.com","name":"Ada"},
        "delivery":"email",
        "idempotencyKey":"call-8841"}}'

Todo lo demás de la solicitud conserva su significado: recipient, prefill, context, readonly, delivery, los recordatorios, la caducidad, callbackUrl, test e idempotencyKey se comprueban contra el nuevo formulario igual que contra uno creado a mano. La respuesta añade el formulario, con las claves con las que vuelven sus respuestas:

{
  "id": "kd7...",
  "status": "pending",
  "url": "https://form.formstep.io/r/rq_...",
  "form": {
    "id": "j58...",
    "name": "Documents and fee for your mortgage application",
    "reused": false,
    "fields": [
      { "key": "payslips", "type": "file" },
      { "key": "fee", "type": "payment" },
      { "key": "call", "type": "schedule-appointment" }
    ]
  }
}

Para precompletar una pregunta de elección en la misma llamada, envía claves de opción, como con cualquier formulario. La clave de una opción se deriva de su etiqueta, así que Self-employed pasa a ser self_employed. Una etiqueta en lugar de una clave falla con INVALID_PREFILL_VALUE, que lista las claves válidas.

El objeto form

Bloques

Un bloque acepta los parámetros de la herramienta editor_insert* correspondiente del servidor MCP, sin formId ni after, más una key opcional. Sin ella, la clave se deriva del título, así que “Full name” pasa a ser full_name. Un parámetro que el bloque no conoce se rechaza en lugar de ignorarse.

El texto de header y paragraph, los elementos de lista y las celdas de tabla admiten bold, italic, struck, <u>underlined</u>, code, $$equation$$, text, <span color=“red” background=“yellow” font=“font-georgia” size=“1.25”>…</span> con los colores, fuentes y tamaños de la barra de herramientas del editor, y {{key}}, que muestra el valor del campo con esa clave. Las marcas se pueden anidar; un marcador sin pareja es texto. Una columna de una fila admite cualquier bloque excepto pageDivider, logic, hiddenField, calculatedField, repeatingGroup, row y scheduleAppointment. Un bloque decision acepta su title y sus labels para aprobar, rechazar y pedir cambios en el idioma del formulario.

Los bloques se refieren unos a otros por clave, nunca por id de elemento: un bloque logic acepta su rule como lo hace editor_insertLogic, con claves de campo donde pide ids, etiquetas de opción como valores de condición y nombres de página para setNextPage.

Pagos

Un bloque payment acepta amount y currency, o amountFromField: la clave de un campo oculto o de una pregunta numérica. Con un campo oculto, cada solicitud pasa su propio importe en context, así que un solo formulario cobra a cada cliente su propio importe:

{
  "form": {
    "name": "Pay your invoice",
    "blocks": [
      { "type": "hiddenField", "key": "invoice_total" },
      { "type": "payment", "key": "invoice", "title": "Invoice", "currency": "EUR", "amountFromField": "invoice_total" }
    ]
  },
  "recipient": { "email": "ada@example.com" },
  "context": { "invoice_total": 1200 }
}

Una pregunta numérica que fija el importe debe ser obligatoria y tener un min mayor que 0, para que nadie llegue al checkout con un importe vacío, cero o negativo.

El formulario cobra a través de la cuenta de Stripe predeterminada del espacio de trabajo, o de la que indique connection. Una persona conecta Stripe una vez para el espacio de trabajo; una automatización no puede. Sin una cuenta utilizable, la llamada falla y te dice dónde conectarla.

Reservas

Un bloque scheduleAppointment acepta eventType, el título o el id de un tipo de evento de la conexión de Cal.com del espacio de trabajo, y connection cuando el espacio de trabajo tiene varias. Formstep busca el tipo de evento al crear la solicitud. prefill: { name, email } indica las preguntas cuyas respuestas rellenan la reserva.

Tu marca

Una automatización no puede inventarse tu imagen, así que se la das una vez y la envía con cada solicitud: logo, cover y emoji junto a los bloques, y theme para los colores y la tipografía.

Cada imagen, incluido el src de un bloque image, debe ser un JPEG, PNG o WebP público. Formstep descarga cada una una vez al crear el formulario y guarda su propia copia, así que el formulario y los PDF de sus envíos sobreviven al original. Una URL que no se puede descargar hace fallar la llamada con INLINE_FORM_IMAGE_UNREACHABLE, que indica el campo. Sin marca, el formulario se ve como uno nuevo creado desde el panel.

Traducciones

translations publica el formulario en más idiomas a la vez, y el destinatario recibe el selector de idioma que tiene un formulario traducido: { "de": { "Your name": "Ihr Name", "Order for **{{customer}}**": "Bestellung für **{{customer}}**" } }. Debe estar cada texto del formulario, con el texto exacto que escribieron los bloques como clave: títulos de preguntas, opciones, marcadores de posición, encabezados, párrafos, elementos de lista, celdas de tabla, nombres de grupo y etiquetas de botones. El marcado y {{key}} se mantienen como en el original. Si falta un texto, la llamada falla con INLINE_FORM_TRANSLATION_MISSING, que lista los textos que hay que añadir. El texto de los correos no se traduce.

Una definición, un formulario

Una llamada posterior con el mismo objeto form reutiliza el mismo formulario, y la respuesta indica “reused”: true. Cien solicitudes con una misma definición crean un solo formulario, con un solo conjunto de respuestas que exportar. Cambiar un bloque, el nombre, la marca o una traducción crea un formulario nuevo; las solicitudes ya enviadas conservan el formulario con el que se crearon. Un formulario cerrado o despublicado no se reutiliza: la siguiente llamada con la misma definición crea uno nuevo.

Cuando una llamada crea un formulario nuevo aunque un formulario integrado abierto tenga los mismos tipos de bloque en el mismo orden, la respuesta nombra ese formulario en form.similarForm. Normalmente se debe a un nombre o un título cambiados. Para leer todas las respuestas de un formulario integrado, lista sus envíos en lugar de leer cada solicitud.

En el panel

Un formulario integrado pertenece a su solicitud, así que vive en la página de la solicitud y no en la página Formularios. La página lista las respuestas por clave de campo, y Vista previa abre el formulario tal como lo vio el destinatario, rellenado con sus respuestas. Un enlace al editor o a los envíos de un formulario integrado abre en su lugar la página Solicitudes filtrada por ese formulario. Los agentes siguen viendo los formularios integrados en form_list, y la API se niega a modificarlos.

Un formulario integrado no tiene enlace público y no se le puede añadir uno: sus solicitudes son la única forma de entrar, y el callback lleva todas las respuestas. Tampoco tiene integraciones.

Como no tiene una página propia, un formulario integrado nunca se elimina a mano. Se va con su última solicitud: cuando eliminas una solicitud, o el período de retención del formulario se la lleva, y ninguna otra solicitud sigue usando el formulario, el formulario también se elimina.

Cuando se rechaza la llamada

Cada rechazo es un VALIDATION_ERROR con un details.reason según el cual tu automatización puede decidir qué hacer. No se crea nada.

Desde un agente

En el servidor MCP, request_create acepta el mismo form. Antes de crear un formulario con un pago o una reserva, un agente consulta workspaceConnection_list: muestra las cuentas de Stripe y Cal.com conectadas y, cuando falta una, el enlace que una persona debe abrir una vez. scheduler_listEventTypes enumera los tipos de evento que puede indicar una reserva, y paymentConnection_setDefault cambia la cuenta de Stripe predeterminada. En la API REST, esas mismas tres son connections.list, scheduler.listEventTypes y paymentConnections.setDefault.