Formularios

Formularios

Acceso programático a los formularios de Dailybot — listar, filtrar, ordenar, buscar, enviar respuestas con modos de automación o anónimo, adjuntar identidades de invitado, transitar estados de workflow y gestionar flujos de aprobación.

Ver la referencia completa de endpoints — con parámetros, schemas de request/response, códigos de error y ejemplos — en la página interactiva: /es/developers/api/forms.

Cada endpoint de este grupo acepta tanto API key (X-API-KEY) como token Bearer del CLI (Authorization: Bearer …), salvo excepción explícita, según la matriz de métodos de autenticación en /es/developers/authentication#parity-matrix.

Identificador

Los recursos Form y Form Response usan un campo uuid dedicado (RFC 4122 v4) como identificador canónico en toda solicitud y respuesta. Los parámetros de ruta como /v1/forms/{uuid}/responses/{response_uuid}/ también usan el valor uuid.

Paginación

Todos los endpoints de lista devuelven el envelope de paginación estándar:

{
  "count": 42,
  "next": "https://api.dailybot.com/v1/forms/?offset=25&limit=25",
  "previous": null,
  "results": [...]
}

Ver /es/developers/conventions#pagination para la especificación completa.

Listar formularios

GET /v1/forms/ devuelve todos los formularios de la organización del llamante (archivados excluidos por defecto). Las capacidades — edición, visibilidad de respuestas, cambios de estado — están gobernadas por los permisos del formulario; el propietario y los administradores siempre tienen acceso completo.

Soporta filtrado por alcance, propietario, búsqueda por nombre, ordenamiento y rangos de fecha.

Filtros de alcance (?filter=):

Filtro por propietario (?owner_user_ids=): UUIDs de usuarios separados por comas (máx. 50). Devuelve solo formularios de esos propietarios. AND con todos los demás parámetros (search, filter, paginación, ordenamiento). UUIDs de otras organizaciones nunca coinciden (devuelve 0 resultados, no un error). Reemplaza el obsoleto filter=me.

Ordenamiento (?order=):

Usa ?is_ascend=true para invertir la dirección de ordenamiento.

# Formularios con workflow, ordenados alfabéticamente ascendente
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/?filter=workflow&order=alphabetical&is_ascend=true"

# Buscar por nombre
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/?search=Solicitud%20de%20Acceso"

# Formularios ordenados por más respuestas
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/?order=total"

Incluir preguntas — pasa ?include=questions para incluir las preguntas de cada formulario:

{
  "uuid": "...",
  "name": "Retro de Sprint",
  "questions": [
    {
      "uuid": "q-uuid-1",
      "label": "¿Qué lograste?",
      "type": "text",
      "required": true,
      "options": null
    }
  ]
}

Descubrir propietarios de formularios

GET /v1/forms/form-owners/ devuelve una lista paginada y buscable de miembros de la organización que poseen al menos un formulario no archivado. Solo aparecen miembros activos y aprobados. Ordenado por full_name ascendente.

Diseñado para selectores de UI: una organización de 1000 miembros devuelve solo sus (típicamente pocos) propietarios de formularios, no todo el directorio.

Cada resultado contiene uuid, full_name, image y role (slug del rol: ADMIN_ORG, MANAGER, ADMIN, MEMBER, GUEST).

Visibilidad del email: el campo email aparece solo cuando el llamante tiene visibilidad de email — admins de organización, managers y admins de equipo. Los llamantes con alcance de miembro reciben filas sin la clave email (omitida, nunca null). Las API keys heredan el rol del propietario de la clave. El parámetro search aún coincide con el email del lado del servidor para todos, pero el valor nunca se devuelve a llamantes sin visibilidad. Los integradores no deben asumir que email está presente en las filas del selector.

# Buscar propietarios de formularios por nombre
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/form-owners/?search=serg&limit=20"

# Filtrar lista de formularios por propietario
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/?owner_user_ids=<uuid-1>,<uuid-2>"

Campos obsoletos:

• available_on_list_view — todavía aceptado en POST /v1/forms/create/ y PATCH /v1/forms/{uuid}/config/ pero es un no-op del lado del servidor. La visibilidad en la lista ahora es organizacional. Para ocultar un formulario, archívelo.
• filter=me — sigue funcionando por retrocompatibilidad pero está obsoleto. Usa owner_user_ids con tu propio UUID. Cuando ambos se envían, se intersectan. El alcance me en endpoints de respuestas de formulario no está relacionado y no está obsoleto.

Ambos campos obsoletos se aceptan indefinidamente; la remoción (y la eventual eliminación de la columna) se anunciará como una entrada de changelog separada con su propia ventana de migración. Los integradores deberían migrar ahora pero nada se rompe el día del deploy.

Nota de migración para integradores: reemplaza filter=me con owner_user_ids=<tu-uuid>. Los clientes que dependían de available_on_list_view para ocultar formularios ahora deben filtrar del lado del cliente o archivar el formulario.

Listar respuestas de formulario

GET /v1/forms/{uuid}/responses/ devuelve las respuestas del llamante por defecto. Pasa ?all=true o cualquier filtro avanzado para ver todas las respuestas (requiere permiso VIEW_REPORTS en el formulario).

Modelo de permisos:

Filtro de origen de envío (?submission_sources=):

Cada respuesta pertenece exactamente a una de estas cuatro categorías mutuamente excluyentes:

Valores separados por comas usan semántica OR: ?submission_sources=automation,public devuelve respuestas de automación O públicas.

Filtro de flujo de aprobación (?flow_status=): Uno de pending, approved, denied. Ignorado silenciosamente si el formulario no tiene flujo de aprobación.

Filtro de estado de workflow (?state=): Filtra por clave de estado de workflow (ej. draft, in_review, done). Devuelve 400 invalid_workflow_state si el formulario no tiene workflow.

Ordenamiento (?order=): Uno de recent (por defecto, más reciente primero) o oldest.

Composición de filtros — todos los filtros se componen con AND entre grupos y OR dentro de cada grupo:

Resultados = (submission_sources OR)
  AND (submitter_user_ids OR)
  AND flow_status
  AND state
  AND search
  AND rango_de_fechas

Comportamiento de búsqueda — el parámetro search busca en contenido de respuesta, nombre/email del miembro y nombre/email del invitado. Las identidades de miembros anónimos nunca son buscables (protección de privacidad).

FORM_UUID="96bd8829-1d2a-40fe-8acf-7edb08f742dd"

# Todas las respuestas
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/$FORM_UUID/responses/?all=true"

# Solo envíos de automación
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/$FORM_UUID/responses/?all=true&submission_sources=automation"

# Aprobación pendiente + origen miembro + búsqueda
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/$FORM_UUID/responses/?all=true&submission_sources=member&flow_status=pending&search=bug"

# Más antiguo primero con rango de fechas
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/$FORM_UUID/responses/?all=true&order=oldest&start_date=2026-07-01&end_date=2026-07-10"

Enviar una respuesta de formulario

POST /v1/forms/{uuid}/responses/ crea una nueva respuesta. El campo content mapea cada UUID de pregunta a su valor de respuesta (strings, booleanos, números o arrays de escalares para opción múltiple).

Modos de envío:

Identidad de invitado — usa guest_user para adjuntar la identidad de una persona externa (nombre y email) a envíos de automación. Solo se acepta cuando automation: true; se ignora en caso contrario. Requerido cuando el formulario tiene email_and_name_mandatory habilitado. guest_user.full_name máx. 255 caracteres; guest_user.email email válido, máx. 254 caracteres.

Origen de envío — usa submission_source (máx. 512 caracteres) para etiquetar qué automación o integración produjo la respuesta. Se almacena en los metadatos de la respuesta y se devuelve en vistas de lista y detalle. Valores sugeridos: "github-actions:deploy-pipeline", "zapier:feedback-sync", "cli:ci-release-bot", "make:onboarding-flow".

Reglas de validación:

• content es requerido y debe contener respuestas que coincidan con las preguntas del formulario
• guest_user requiere automation: true — se ignora en caso contrario
• Si el formulario tiene email_and_name_mandatory=true y automation=true, tanto guest_user.full_name como guest_user.email deben proporcionarse
• Límite de tamaño del payload: 64 KB máximo
• Los valores de respuesta no pueden ser objetos anidados — las listas deben contener solo escalares

# Modo automación con identidad de invitado y origen
curl -s -X POST \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.dailybot.com/v1/forms/{uuid}/responses/" \
  -d '{
    "content": {"<question-uuid>": "Aprobado"},
    "automation": true,
    "guest_user": {"full_name": "Ops Bot", "email": "ops@company.com"},
    "submission_source": "workflow:on-call-handoff"
  }'

# Envío anónimo
curl -s -X POST \
  -H "X-API-KEY: $DAILYBOT_API_KEY" \
  -H "Content-Type: application/json" \
  "https://api.dailybot.com/v1/forms/{uuid}/responses/" \
  -d '{
    "content": {"<question-uuid>": "Feedback honesto sobre el proceso"},
    "anonymous": true
  }'

URLs de la aplicación web para integradores