Formulários

Formulários

Acesso programático aos formulários do Dailybot — listar, filtrar, ordenar, buscar, enviar respostas com modos de automação ou anônimo, anexar identidades de convidado, transitar estados de workflow e gerenciar fluxos de aprovação.

Veja a referência completa de endpoints — com parâmetros, schemas de request/response, códigos de erro e exemplos — na página interativa: /pt/developers/api/forms.

Cada endpoint deste grupo aceita tanto API key (X-API-KEY) quanto token Bearer do CLI (Authorization: Bearer …), salvo exceção explícita, conforme a matriz de métodos de autenticação em /pt/developers/authentication#parity-matrix.

Identificador

Os recursos Form e Form Response usam um campo uuid dedicado (RFC 4122 v4) como identificador canônico em toda solicitação e resposta. Parâmetros de rota como /v1/forms/{uuid}/responses/{response_uuid}/ também usam o valor uuid.

Paginação

Todos os endpoints de lista retornam o envelope de paginação padrão:

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

Veja /pt/developers/conventions#pagination para a especificação completa.

Listar formulários

GET /v1/forms/ retorna todos os formulários da organização do chamador (arquivados excluídos por padrão). As capacidades — edição, visibilidade de respostas, mudanças de estado — são governadas pelas permissões do formulário; o proprietário e os administradores sempre têm acesso completo.

Suporta filtragem por escopo, proprietário, busca por nome, ordenação e intervalos de data.

Filtros de escopo (?filter=):

Filtro por proprietário (?owner_user_ids=): UUIDs de usuários separados por vírgulas (máx. 50). Retorna apenas formulários desses proprietários. AND com todos os outros parâmetros (search, filter, paginação, ordenação). UUIDs de outras organizações nunca correspondem (retorna 0 resultados, não um erro). Substitui o obsoleto filter=me.

Ordenação (?order=):

Use ?is_ascend=true para inverter a direção de ordenação.

# Formulários com workflow, ordenados alfabeticamente ascendente
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/?filter=workflow&order=alphabetical&is_ascend=true"

# Buscar por nome
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/?search=Solicitação%20de%20Acesso"

# Formulários ordenados por mais respostas
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/?order=total"

Incluir perguntas — passe ?include=questions para incluir as perguntas de cada formulário:

{
  "uuid": "...",
  "name": "Retro de Sprint",
  "questions": [
    {
      "uuid": "q-uuid-1",
      "label": "O que você realizou?",
      "type": "text",
      "required": true,
      "options": null
    }
  ]
}

Descobrir proprietários de formulários

GET /v1/forms/form-owners/ retorna uma lista paginada e pesquisável de membros da organização que possuem pelo menos um formulário não arquivado. Apenas membros ativos e aprovados aparecem. Ordenado por full_name ascendente.

Projetado para seletores de UI: uma organização de 1000 membros retorna apenas seus (tipicamente poucos) proprietários de formulários, não todo o diretório.

Cada resultado contém uuid, full_name, image e role (slug do papel: ADMIN_ORG, MANAGER, ADMIN, MEMBER, GUEST).

Visibilidade do email: o campo email aparece apenas quando o chamador tem visibilidade de email — admins da organização, managers e admins de equipe. Chamadores com escopo de membro recebem linhas sem a chave email (omitida, nunca null). API keys herdam o papel do proprietário da chave. O parâmetro search ainda corresponde ao email no servidor para todos, mas o valor nunca é retornado para chamadores sem visibilidade. Integradores não devem assumir que email está presente nas linhas do seletor.

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

# Filtrar lista de formulários por proprietário
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 — ainda aceito em POST /v1/forms/create/ e PATCH /v1/forms/{uuid}/config/ mas é um no-op no servidor. A visibilidade na lista agora é organizacional. Para ocultar um formulário, arquive-o.
• filter=me — ainda funciona por retrocompatibilidade mas está obsoleto. Use owner_user_ids com seu próprio UUID. Quando ambos são enviados, eles se intersectam. O escopo me em endpoints de respostas de formulário não está relacionado e não está obsoleto.

Ambos os campos obsoletos continuam sendo aceitos indefinidamente; a remoção (e a eventual eliminação da coluna) será anunciada como uma entrada de changelog separada com sua própria janela de migração. Os integradores devem migrar agora mas nada quebra no dia do deploy.

Nota de migração para integradores: substitua filter=me por owner_user_ids=<seu-uuid>. Clientes que dependiam de available_on_list_view para ocultar formulários agora devem filtrar do lado do cliente ou arquivar o formulário.

Listar respostas de formulário

GET /v1/forms/{uuid}/responses/ retorna as respostas do chamador por padrão. Passe ?all=true ou qualquer filtro avançado para ver todas as respostas (requer permissão VIEW_REPORTS no formulário).

Modelo de permissões:

Filtro de origem de envio (?submission_sources=):

Cada resposta pertence a exatamente uma destas quatro categorias mutuamente exclusivas:

Valores separados por vírgulas usam semântica OR: ?submission_sources=automation,public retorna respostas de automação OU públicas.

Filtro de fluxo de aprovação (?flow_status=): Um de pending, approved, denied. Ignorado silenciosamente se o formulário não tem fluxo de aprovação.

Filtro de estado de workflow (?state=): Filtra por chave de estado de workflow (ex. draft, in_review, done). Retorna 400 invalid_workflow_state se o formulário não tem workflow.

Ordenação (?order=): Um de recent (padrão, mais recente primeiro) ou oldest.

Composição de filtros — todos os filtros se compõem com AND entre grupos e OR dentro de cada grupo:

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

Comportamento de busca — o parâmetro search busca no conteúdo da resposta, nome/email do membro e nome/email do convidado. Identidades de membros anônimos nunca são pesquisáveis (proteção de privacidade).

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

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

# Apenas envios de automação
curl -H "X-API-KEY: $DAILYBOT_API_KEY" \
  "https://api.dailybot.com/v1/forms/$FORM_UUID/responses/?all=true&submission_sources=automation"

# Aprovação pendente + origem membro + busca
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"

# Mais antigo primeiro com intervalo de datas
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 uma resposta de formulário

POST /v1/forms/{uuid}/responses/ cria uma nova resposta. O campo content mapeia cada UUID de pergunta ao seu valor de resposta (strings, booleanos, números ou arrays de escalares para múltipla escolha).

Modos de envio:

Identidade de convidado — use guest_user para anexar a identidade de uma pessoa externa (nome e email) a envios de automação. Aceito apenas quando automation: true; ignorado caso contrário. Obrigatório quando o formulário tem email_and_name_mandatory habilitado. guest_user.full_name máx. 255 caracteres; guest_user.email email válido, máx. 254 caracteres.

Origem do envio — use submission_source (máx. 512 caracteres) para marcar qual automação ou integração produziu a resposta. Armazenado nos metadados da resposta e retornado nas visualizações de lista e detalhe. Valores sugeridos: "github-actions:deploy-pipeline", "zapier:feedback-sync", "cli:ci-release-bot", "make:onboarding-flow".

Regras de validação:

• content é obrigatório e deve conter respostas correspondentes às perguntas do formulário
• guest_user requer automation: true — ignorado caso contrário
• Se o formulário tem email_and_name_mandatory=true e automation=true, tanto guest_user.full_name quanto guest_user.email devem ser fornecidos
• Limite de tamanho do payload: 64 KB máximo
• Valores de resposta não podem ser objetos aninhados — listas devem conter apenas escalares

# Modo automação com identidade de convidado e origem
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>": "Aprovado"},
    "automation": true,
    "guest_user": {"full_name": "Ops Bot", "email": "ops@company.com"},
    "submission_source": "workflow:on-call-handoff"
  }'

# Envio 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 o processo"},
    "anonymous": true
  }'

URLs do aplicativo web para integradores