Referência da API de Flows

Todo endpoint abaixo autentica com uma chave de API com escopo de número (x-api-key) cujo número seja Meta (API Oficial). A WABA é DERIVADA desse número — não existe parâmetro para nomear uma, de propósito.

Permissão	Cobre
`flows:read`	Listar Flows e ler as respostas dos formulários
`flows:manage`	Toda escrita: criar, atualizar, subir JSON, publicar, depreciar, apagar

flows:read é um slug próprio e não é templates:read. A listagem de templates devolve texto que o seu workspace escreveu; a resposta de um Flow devolve o que um cliente digitou num formulário — um nome, um telefone, às vezes um documento. As duas coisas são gateadas separadamente de propósito.

Listar Flows

curl "https://pilotstatus.com.br/v1/flows?page=1&pageSize=30" \
  -H "x-api-key: ps_sua_chave_aqui"

{
  "flows": [
    {
      "id": "flw_local_1",
      "metaFlowId": "1122334455",
      "name": "Agendamento",
      "metaStatus": "PUBLISHED",
      "categories": ["APPOINTMENT_BOOKING"],
      "jsonVersion": "7.1",
      "healthStatus": "AVAILABLE",
      "clonedFromFlowId": null,
      "supersededByFlowId": null,
      "createdAt": "2026-08-30T12:00:00.000Z",
      "updatedAt": "2026-09-01T09:12:00.000Z"
    }
  ],
  "total": 1, "page": 1, "pageSize": 30
}

id é o id local e é o único id que você manda de volta para nós. metaFlowId é o da Meta e é somente leitura — vem null enquanto o Flow existe aqui e ainda não chegou à Meta.

Criar ou clonar

curl -X POST "https://pilotstatus.com.br/v1/flows" \
  -H "x-api-key: ps_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agendamento v2",
    "categories": ["APPOINTMENT_BOOKING"],
    "cloneFromFlowId": "flw_local_1"
  }'

Devolve 201 com o Flow novo em DRAFT. Omita cloneFromFlowId para começar do zero.

cloneFromFlowId é o id local do Flow de origem — o campo id, não o metaFlowId. Clonar é a única forma de mudar um Flow que já foi publicado.

Renomear e recategorizar

curl -X PATCH "https://pilotstatus.com.br/v1/flows/flw_local_1" \
  -H "x-api-key: ps_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Agendamento (matriz)", "categories": ["APPOINTMENT_BOOKING"] }'

Aceita apenas name e categories. Nunca publica e nunca deprecia — essas têm endpoint próprio, para um engano num formulário não alcançar uma operação irreversível.

Subir o Flow JSON

curl -X POST "https://pilotstatus.com.br/v1/flows/flw_local_1/json" \
  -H "x-api-key: ps_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "flowJson": "{\"version\":\"7.1\",\"screens\":[...]}" }'

Um 200 significa que o documento compilou, e aí validationErrors vem sempre vazio:

{ "validationErrors": [] }

Documento que a Meta recusa volta como 422 FLOW_JSON_INVALID, com a lista dela anexada:

{
  "error": "A Meta recusou este Flow JSON. Veja validationErrors.",
  "errorEN": "Meta rejected this Flow JSON. See validationErrors.",
  "code": "FLOW_JSON_INVALID",
  "validationErrors": [ { "error": "...", "line_start": 12, "message": "..." } ]
}

Isto NÃO é como a API da Meta se comporta, de propósito — e a diferença é o ponto.A Meta responde 200 com os problemas listados dentro do payload. Ou seja: lá, sucesso aparente sobre documento inválido é o caso normal, e um cliente que olha só o status publica um Flow que nunca compilou.Esta rota lê a LISTA em vez do status da Graph, e responde 422 sempre que ela não está vazia. Um 200 nosso significa, então, o que um 200 deve significar. Leia validationErrors no 422 — é a resposta da Meta, verbatim.flowJson é uma string, nunca um objeto aninhado: a Meta compila os bytes exatos, e re-serializar reordenaria em silêncio o que você escreveu.

Publicar

curl -X POST "https://pilotstatus.com.br/v1/flows/flw_local_1/publish" \
  -H "x-api-key: ps_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "confirm": true }'

Irreversível na Meta. Um Flow publicado nunca mais pode ser editado nem despublicado — só clonado num novo. "confirm": true é obrigatório; sem ele a requisição é recusada com 400.

Depreciar

curl -X POST "https://pilotstatus.com.br/v1/flows/flw_local_1/deprecate" \
  -H "x-api-key: ps_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "supersededByFlowId": "flw_local_2" }'

Aposenta o Flow sem apagar, e sem apagar as respostas já enviadas. supersededByFlowId é opcional — mas, se você mandar, tem de nomear um Flow real seu: string vazia é recusada em vez de ignorada em silêncio, porque cadeia de versões rompida é invisível depois.

Apagar

curl -X DELETE "https://pilotstatus.com.br/v1/flows/flw_local_1" \
  -H "x-api-key: ps_sua_chave_aqui"

Só um DRAFT pode ser apagado. Qualquer outro estado devolve 409.

Ler as respostas dos formulários

curl "https://pilotstatus.com.br/v1/flows/flw_local_1/responses?page=1&pageSize=30" \
  -H "x-api-key: ps_sua_chave_aqui"

Devolve o que os clientes enviaram, ligado ao contato que respondeu, dentro da janela de retenção. Resposta vencida nunca é servida.

Chave do endpoint `data_exchange`

Ainda não exposta na API pública. A gestão da chave do endpoint data_exchange — gerar o par, registrar a metade pública na Meta e conferir se a Meta ainda tem a nossa — está construída, mas ainda não tem rota REST. Esta seção lista os endpoints no dia em que existirem.O que o recurso faz, e o desenho por trás dele, está em Flows. Se você precisar antes de estar exposto, fale com o suporte.

Erros

Toda falha desta superfície responde o mesmo envelope — existe exatamente uma forma para ler, e uma grafia:

{ "error": "<português>", "errorEN": "<inglês>", "code": "<CÓDIGO>" }

FLOW_JSON_INVALID acrescenta um array validationErrors; FLOW_UNKNOWN_FIELDS acrescenta as chaves recusadas. Nunca assuma que o conjunto de códigos é fechado — trate os que você conhece e caia no code para o resto.

Código	Status	Significado
`FLOW_NOT_FOUND`	404	Nenhum Flow com esse id dentro da WABA da sua chave
`FLOW_NOT_DRAFT`	409	O Flow saiu de `DRAFT` — clone para começar nova versão
`FLOW_REQUIRES_META_NUMBER`	422	O número da chave não é Meta, ou não tem WABA
`FLOW_NUMBER_FROM_KEY`	422	Não foi possível derivar o número a partir da chave
`FLOW_JSON_INVALID`	422	A Meta recusou o documento — leia `validationErrors`
`FLOW_JSON_REQUIRED`	400	`flowJson` ausente ou vazio
`FLOW_NAME_REQUIRED`	400	`name` faltando na criação
`FLOW_NAME_INVALID`	400	`name` presente mas não é string utilizável
`FLOW_CATEGORY_INVALID`	400	Categoria fora do conjunto que a Meta aceita
`FLOW_CLONE_SOURCE_INVALID`	400	`cloneFromFlowId` não é um id local utilizável
`FLOW_PATCH_EMPTY`	400	`PATCH` sem `name` e sem `categories`
`FLOW_UNKNOWN_FIELDS`	400	O corpo trouxe campo que a rota não aceita
`FLOW_PUBLISH_REQUIRES_CONFIRMATION`	400	`publish` sem `"confirm": true`
`FLOW_DEPRECATE_INVALID_SUCCESSOR`	400	`supersededByFlowId` presente mas em branco ou desconhecido
`FLOW_BODY_INVALID`	400	Corpo malformado, ou campo obrigatório faltando
`INVALID_PAGINATION`	400	`page` × `pageSize` além do teto de offset profundo
`INTERNAL_ERROR`	500	Nosso. Tente de novo e informe o código ao suporte

Os dois últimos não têm prefixo FLOW_ — são compartilhados por toda a API pública e mantêm a grafia global. Um cliente que filtre por code.startsWith("FLOW_") perderia os dois.

Visão Geral

Mensagens

Modelos

Números

Conversas & Dados

Webhooks

Chamadas de Voz

Camada de Compatibilidade

Conta & Cobrança

Marca & Incorporação

Referência da API de Flows

Listar Flows

Criar ou clonar

Renomear e recategorizar

Subir o Flow JSON

Publicar

Depreciar

Apagar

Ler as respostas dos formulários

Chave do endpoint `data_exchange`

Erros

Relacionado

​Listar Flows

​Criar ou clonar

​Renomear e recategorizar

​Subir o Flow JSON

​Publicar

​Depreciar

​Apagar

​Ler as respostas dos formulários

​Chave do endpoint data_exchange

​Erros

​Relacionado

Listar Flows

Criar ou clonar

Renomear e recategorizar

Subir o Flow JSON

Publicar

Depreciar

Apagar

Ler as respostas dos formulários

Chave do endpoint `data_exchange`

Erros

Relacionado