ARararahq
Formulários

Criar formulário

Changed on

Cria o formulário e já publica: quando a chamada volta 201 com status: PUBLISHED, ele está no ar e não pode mais ser editado. Se só a publicação falhar, o formulário fica em DRAFT com publishError preenchido; publique de novo em POST /v1/flows/{id}/publish.

Não aceita Idempotency-Key. O nome é único por número, então repetir um POST que já passou responde 409 FLOW_NAME_TAKEN em vez de duplicar.

Disponível do plano Voo para cima. Permissão: TEMPLATES_WRITE.

post/v1/flows

Request

Request body

namestring required

Nome interno, único por número. Só você vê.

category'SIGN_UP' | 'LEAD_GENERATION' | 'SURVEY' | 'APPOINTMENT_BOOKING' | 'CONTACT_US' | 'OTHER' required
titlestring required

Aparece no topo do formulário.

introstring nullable

Texto de introdução, abaixo do título.

submitLabelstring

Texto do botão de envio.

Response

Formulário criado

idstring uuid required

Use como flowId no envio e no botão FLOW do template.

namestring required
category'SIGN_UP' | 'LEAD_GENERATION' | 'SURVEY' | 'APPOINTMENT_BOOKING' | 'CONTACT_US' | 'OTHER' required
status'DRAFT' | 'PUBLISHED' | 'DEPRECATED' required

DRAFT: criado, mas a publicação falhou (veja publishError). PUBLISHED: no ar, pode ser enviado. DEPRECATED: desativado.

responseCountinteger required

Total de respostas recebidas.

publishErrorstring nullable

Preenchido só quando o formulário foi criado mas a publicação falhou.

createdAtstring date-time nullable
publishedAtstring date-time nullable

Example response

{
  "id": "0b7e6a52-3c1d-4f7a-9a55-2f4f6f1f9c10",
  "name": "Captar contato",
  "category": "LEAD_GENERATION",
  "status": "PUBLISHED",
  "definition": {
    "title": "Fale com a gente",
    "intro": "Leva menos de um minuto.",
    "submitLabel": "Enviar",
    "fields": [
      {
        "key": "nome",
        "label": "Seu nome",
        "type": "TEXT",
        "required": true,
        "options": []
      },
      {
        "key": "email",
        "label": "Seu melhor e-mail",
        "type": "EMAIL",
        "required": true,
        "options": []
      },
      {
        "key": "interesse",
        "label": "O que você procura?",
        "type": "SELECT",
        "required": true,
        "options": [
          {
            "id": "falar_com_vendas",
            "title": "Falar com vendas"
          },
          {
            "id": "suporte",
            "title": "Suporte"
          }
        ]
      }
    ]
  },
  "responseCount": 42,
  "publishError": null,
  "createdAt": "2026-09-15T14:30:00Z",
  "publishedAt": "2026-09-15T14:30:04Z"
}

Changes