> ## Documentation Index > Fetch the complete documentation index at: https://docs.ararahq.com/llms.txt > Use this file to discover all available pages before exploring further. # Criar formulário > 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`. ## OpenAPI ````yaml /openapi.yaml post /v1/flows openapi: 3.0.3 info: title: API da Arara description: > API REST da Arara para WhatsApp Business: mensagens, templates, campanhas, contatos, conversas, formulários, automações, smart links e carteira. Esta especificação cobre só os endpoints que aceitam **chave de API** (`Authorization: Bearer ara_live_...`). Rotas usadas apenas pelo painel (gestão de chaves, configuração do webhook, pagamentos e perfil pessoal) ficam de fora. ## Autenticação Header `Authorization: Bearer ara_live_...`. Crie a chave em https://app.ararahq.com/dashboard/apikeys. As chaves são sempre LIVE: mensagens são entregues de verdade e o custo sai da carteira. ## Permissões da chave Chave criada sem permissões explícitas tem acesso total (`ADMIN`). Chave com permissões restritas só alcança: - `READ`: `GET` em `/v1/messages`, `/v1/campaigns`, `/v1/templates`, `/v1/flows`, `/v1/automations` e `/v1/organizations/me/numbers`. - `MESSAGES_SEND`: escrita em `/v1/messages/**`, `POST /v1/media/upload` e `POST /v1/flows/{id}/test`. - `TEMPLATES_WRITE`: escrita em `/v1/templates/**` e `/v1/flows/**`. - `CAMPAIGNS_SEND`: escrita em `/v1/campaigns/**`. - `CONTACTS_WRITE`: escrita em `/v1/contacts/**`. - `AUTOMATIONS_MANAGE`: escrita em `/v1/automations/**`. - `WEBHOOKS_MANAGE`: escrita em `/webhook/**`. Qualquer outra rota exige `ADMIN`. Fora do escopo, a resposta é `403`. ## Rate limit Por usuário da chave: 1.200 leituras (`GET`) por minuto e 3.000 escritas por minuto. Toda resposta traz `X-RateLimit-Remaining`. Acima do limite: `429` com `Retry-After` e `error.code = RATE_LIMIT_EXCEEDED`. O envio tem limites próprios (`SEND_RATE_LIMITED`, `BATCH_BUSY`, `MARKETING_FREQUENCY_EXCEEDED`). ## Formato de erro ```json { "error": { "code": "ERROR_CODE", "message": "Descrição", "details": {} } } ``` Exceções: falha de autenticação (`401`, `403` e `503` do filtro de chave) volta no formato padrão do Spring (`timestamp`, `status`, `error`, `path`, sem `code`), e alguns `404` e `403` voltam sem corpo. version: 2.1.0 contact: name: AraraHQ url: https://ararahq.com email: oi@ararahq.com servers: - url: https://api.ararahq.com description: Produção security: - bearerAuth: [] tags: - name: Mensagens description: Envio, consulta e histórico de mensagens de WhatsApp, e upload de mídia. - name: Conversas description: >- Conversas com cada telefone, resposta dentro da janela de 24h e situação da janela. - name: Templates description: Criação, listagem, status de aprovação e métricas de templates. - name: Campanhas description: >- Envio do mesmo template para muitos contatos, com estimativa, agendamento, cancelamento e teste A/B. - name: Contatos description: Base de contatos da organização e direitos do titular (LGPD). - name: Opt-out description: Registro e consulta de quem pediu para não receber mensagens. - name: Formulários description: >- Formulários nativos do WhatsApp (Flows) e as respostas recebidas. Disponíveis do plano Voo para cima. - name: Automações description: >- Sequências de passos que rodam sozinhas para cada contato que entra por um gatilho. Exigem plano com recuperação de receita. - name: Smart Links description: Links wa.me rastreáveis, com QR code. - name: Números description: >- Números de WhatsApp da organização e o perfil comercial exibido no WhatsApp. - name: Carteira description: Saldo, extrato, recarga automática e preços. - name: Consulta de telefone description: Consulta de tipo de linha e de WhatsApp de um número (cobrada). - name: Recuperação description: Endpoint de recuperação de receita (carrinho abandonado, Pix, boleto). - name: Conta description: Identidade da chave, plano da organização e status da API. paths: /v1/flows: post: tags: - Formulários summary: Criar formulário description: > 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`. operationId: createFlow requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateFlowRequest' example: name: Captar contato category: LEAD_GENERATION title: Fale com a gente intro: Leva menos de um minuto. submitLabel: Enviar fields: - label: Seu nome type: TEXT key: nome - label: Seu melhor e-mail type: EMAIL key: email - label: O que você procura? type: SELECT key: interesse options: - Falar com vendas - Suporte - Parceria - label: Observações type: LONG_TEXT key: obs required: false responses: '201': description: Formulário criado content: application/json: schema: $ref: '#/components/schemas/Flow' '400': description: >- `INVALID_FLOW`: pergunta em branco, opções de menos, chave inválida ou JSON recusado pela Meta. Também `INVALID_JSON`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: INVALID_FLOW message: O formulário precisa de 1 a 10 perguntas. details: {} '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': description: >- `FLOW_NAME_TAKEN` (nome já usado no número) ou `FLOW_NUMBER_REQUIRED` (nenhum número conectado). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: FLOW_NAME_TAKEN message: Já existe um formulário com o nome 'Captar contato'. details: {} '429': $ref: '#/components/responses/RateLimited' components: schemas: CreateFlowRequest: type: object required: - name - category - title - fields properties: name: type: string maxLength: 120 description: Nome interno, único por número. Só você vê. category: $ref: '#/components/schemas/FlowCategory' title: type: string maxLength: 30 description: Aparece no topo do formulário. intro: type: string maxLength: 300 nullable: true description: Texto de introdução, abaixo do título. submitLabel: type: string maxLength: 30 default: Enviar description: Texto do botão de envio. fields: type: array minItems: 1 maxItems: 10 description: De 1 a 10 perguntas, todas na mesma tela. items: $ref: '#/components/schemas/FlowFieldRequest' Flow: type: object required: - id - name - category - status - definition - responseCount properties: id: type: string format: uuid description: Use como `flowId` no envio e no botão `FLOW` do template. name: type: string category: $ref: '#/components/schemas/FlowCategory' status: $ref: '#/components/schemas/FlowStatus' definition: type: object required: - title - submitLabel - fields description: O formulário como foi criado, já com as chaves finais. properties: title: type: string intro: type: string nullable: true submitLabel: type: string fields: type: array items: $ref: '#/components/schemas/FlowField' responseCount: type: integer format: int64 description: Total de respostas recebidas. publishError: type: string nullable: true description: >- Preenchido só quando o formulário foi criado mas a publicação falhou. createdAt: type: string format: date-time nullable: true publishedAt: type: string format: date-time nullable: true example: 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' Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: INSUFFICIENT_FUNDS description: >- Código estável do erro. Use este campo no seu tratamento, não a mensagem. message: type: string nullable: true description: Descrição legível, em português. Pode mudar. details: type: object additionalProperties: true description: Dados extras do erro. Vazio na maioria dos casos. example: error: code: INSUFFICIENT_FUNDS message: Saldo insuficiente. details: {} FlowCategory: type: string enum: - SIGN_UP - LEAD_GENERATION - SURVEY - APPOINTMENT_BOOKING - CONTACT_US - OTHER FlowFieldRequest: type: object required: - label - type properties: label: type: string maxLength: 80 description: Texto da pergunta. type: $ref: '#/components/schemas/FlowFieldType' required: type: boolean default: true description: Pergunta opcional sem resposta chega como string vazia no webhook. options: type: array nullable: true minItems: 2 maxItems: 20 items: type: string maxLength: 30 description: >- Só em `SELECT` e `MULTI_SELECT`. De 2 a 20 opções, até 30 caracteres cada. key: type: string nullable: true maxLength: 40 pattern: ^[a-z][a-z0-9_]*$ description: > Nome do campo no webhook (`fields.email`). Minúsculas, números e `_`, começando por letra. Sem ela, nasce do texto da pergunta. Não muda depois de publicado. FlowStatus: type: string enum: - DRAFT - PUBLISHED - DEPRECATED description: | `DRAFT`: criado, mas a publicação falhou (veja `publishError`). `PUBLISHED`: no ar, pode ser enviado. `DEPRECATED`: desativado. FlowField: type: object required: - key - label - type - required - options properties: key: type: string description: Chave estável da resposta. label: type: string type: $ref: '#/components/schemas/FlowFieldType' required: type: boolean options: type: array items: type: object required: - id - title properties: id: type: string title: type: string SpringError: type: object description: >- Corpo padrão do Spring nas falhas de autenticação (`401`, `403` e `503` do filtro de chave). Não tem `error.code`. properties: timestamp: type: string format: date-time status: type: integer example: 401 error: type: string example: Unauthorized path: type: string example: /v1/messages FlowFieldType: type: string enum: - TEXT - EMAIL - PHONE - NUMBER - LONG_TEXT - SELECT - MULTI_SELECT - DATE - OPT_IN description: >- Texto, e-mail, telefone, número, texto longo, escolha única, múltipla escolha, data ou aceite. responses: Unauthorized: description: > Chave inexistente, revogada, expirada, com prefixo errado (`ara_` sem `ara_live_`) ou vinda de IP fora da allowlist. O corpo é o JSON padrão do Spring, sem `error.code`. content: application/json: schema: $ref: '#/components/schemas/SpringError' example: timestamp: '2026-09-15T14:30:00.000+00:00' status: 401 error: Unauthorized path: /v1/messages Forbidden: description: > Dois casos, com corpos diferentes: - Autenticação: header `Authorization` ausente, Bearer que não começa com `ara_`, chave sem a permissão da rota ou rota que não aceita chave de API. Corpo no formato padrão do Spring, sem `error.code`. - Regra de negócio, no formato `{ "error": { ... } }`: `PLAN_FEATURE_LOCKED`, `PLAN_LIMIT_REACHED`, `ACCOUNT_NOT_ACTIVATED`, `NO_DEDICATED_NUMBER`, `ORGANIZATION_SUSPENDED`, `NUMBER_BLOCKED`, `FRAUD_SUSPECTED`, `RESOURCE_FORBIDDEN`, `VIEWER_READ_ONLY`. content: application/json: schema: anyOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/SpringError' examples: regraDeNegocio: summary: Regra de negócio value: error: code: PLAN_FEATURE_LOCKED message: Seu plano não inclui este recurso. details: {} autenticacao: summary: Sem header ou sem permissão value: timestamp: '2026-09-15T14:30:00.000+00:00' status: 403 error: Forbidden path: /v1/messages RateLimited: description: >- `RATE_LIMIT_EXCEEDED`: limite geral da API (1.200 leituras ou 3.000 escritas por minuto, por usuário da chave). headers: Retry-After: schema: type: integer description: Segundos a aguardar antes de repetir a chamada. X-RateLimit-Remaining: schema: type: integer description: Requisições restantes na janela atual. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: RATE_LIMIT_EXCEEDED message: Muitas requisições. Tente de novo em instantes. details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: ara_live_... description: >- Chave de API da Arara (`ara_live_...`), enviada no header `Authorization: Bearer ara_live_...`. Crie e gerencie as chaves no painel: https://app.ararahq.com/dashboard/apikeys. O valor completo aparece uma única vez, na criação. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.