VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp Commerce: fluxos e experiência

Textos e pedidos de mudança

Troca só as frases do fluxo do seller sem mexer no desenho e pede à plataforma uma mudança de estrutura.

Nem todo ajuste precisa do editor de blocos. Para trocar uma saudação ou o texto de uma opção do menu, use flow-copy: você grava textos que prevalecem sobre os do fluxo, e o desenho continua intacto. Para mudar a estrutura (acrescentar um passo, mudar a ordem), o seller pode editar blocos e conexões ou, se preferir que a plataforma faça, abrir um pedido de mudança (flow-requests).

Ler os textos editáveis

GET/api/v1/vendor/whatsapp/flow-copySeller

Lista as frases do fluxo que o seller pode trocar

Usa o fluxo ativo do seller (o mesmo de Fluxo ativo). Só blocos de texto e de escolha entram: message e human_handoff (campo text) e menu, list e button (campo question e uma entrada option_N por opção). Blocos estruturais, como login e carrinho, não aparecem.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp/flow-copy" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Textos do fluxo
json
{
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "flow_name": "Welcome Retail",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "fields": [
    {
      "block_id": "b1a2c3d4-0000-4000-8000-000000000001",
      "block_name": "Boas-vindas",
      "block_type": "message",
      "field_key": "text",
      "label": "Mensagem",
      "base_text": "Oi! Bem-vindo à {{vendor_name}}.",
      "value": "Oi! Que bom ter você na {{vendor_name}}.",
      "overridden": true
    },
    {
      "block_id": "b1a2c3d4-0000-4000-8000-000000000002",
      "block_name": "Menu principal",
      "block_type": "menu",
      "field_key": "option_0",
      "label": "Opção 1",
      "base_text": "Ver produtos",
      "value": "Ver produtos",
      "overridden": false
    }
  ]
}

Campos da resposta

flow_iduuid
Fluxo de onde vêm os textos. Vazio quando o seller não tem nenhum fluxo.
flow_namestring
Nome do fluxo.
vendor_iduuid
Seller.
fieldsarray
Campos editáveis. Lista vazia quando não há fluxo.
fields[].block_iduuid
Bloco do texto.
fields[].block_namestring
Nome do bloco.
fields[].block_typestring
Tipo do bloco.
fields[].field_keystring
text, question ou option_N. Junto com block_id, identifica o campo.
fields[].labelstring
Rótulo para mostrar ao usuário, em português.
fields[].base_textstring
Texto original do fluxo.
fields[].valuestring
Texto em vigor: a sua troca, ou o original se não houve.
fields[].overriddenboolean
true quando existe uma troca do seller.

Erros

StatusQuandoCorpo
401 / 403Autenticação, módulo ou privilégioveja Fluxo
404Usuário sem cadastro de seller{"error":"vendor profile not found","code":"vendor_profile_not_found"}
500Falha ao montar{"error":"..."}

Gravar textos

PUT/api/v1/vendor/whatsapp/flow-copySeller

Grava as trocas de texto do seller

Sem aprovação: a troca vale na hora para as próximas conversas. Devolve a mesma estrutura da leitura, já com os novos valores. Para voltar ao texto original, grave o texto original de base_text; não existe rota para apagar uma troca.

Corpo da requisição

flow_iduuid
Fluxo dos textos. Se omitido, usa o fluxo ativo do seller.
fieldsarrayobrigatório

Lista de trocas.

block_iduuidobrigatório
Bloco do texto (fields[].block_id da leitura).
field_keystringobrigatório
Campo (text, question ou option_N).
valuestringobrigatório
Novo texto. Variáveis como {{vendor_name}} continuam valendo.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/whatsapp/flow-copy" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "fields": [
    {
      "block_id": "b1a2c3d4-0000-4000-8000-000000000001",
      "field_key": "text",
      "value": "Oi! Que bom ter você na {{vendor_name}}."
    }
  ]
}'

Resposta

200Textos atualizados
json
{
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "flow_name": "Welcome Retail",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "fields": [
    {
      "block_id": "b1a2c3d4-0000-4000-8000-000000000001",
      "block_name": "Boas-vindas",
      "block_type": "message",
      "field_key": "text",
      "label": "Mensagem",
      "base_text": "Oi! Bem-vindo à {{vendor_name}}.",
      "value": "Oi! Que bom ter você na {{vendor_name}}.",
      "overridden": true
    }
  ]
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid json"}
400Sem flow_id e o seller não tem fluxo{"error":"no flow for vendor; ask admin to assign a playbook"}
400block_id que não é UUID válido{"error":"..."}
401 / 403Autenticação, módulo ou privilégioveja Fluxo
Itens incompletos são ignorados em silêncio

Uma entrada de fields sem block_id ou sem field_key é descartada sem aviso, e a resposta continua sendo 200. A rota também não confere se o bloco pertence ao seu fluxo. Compare value na resposta com o que você enviou.

Listar pedidos de mudança

GET/api/v1/vendor/whatsapp/flow-requestsSeller

Lista os pedidos de mudança de estrutura do seller

Devolve até 100 pedidos, do mais novo para o mais antigo.

Parâmetros de consulta

statusstring
pendingapprovedrejectedapplied
Filtra por situação. Sem o parâmetro, devolve todas.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/vendor/whatsapp/flow-requests?status=pending" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Pedidos do seller
json
{
  "requests": [
    {
      "id": "e7d6c5b4-0000-4000-8000-000000000001",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
      "title": "Acrescentar passo de troca e devolução",
      "description": "Depois do menu, uma opção que explique o prazo de troca.",
      "status": "pending",
      "created_by": "d4613dde-ac7a-4319-9232-50d8cd6ad5fc",
      "created_at": "2026-10-11T14:40:00Z",
      "updated_at": "2026-10-11T14:40:00Z"
    }
  ]
}

Campos da resposta

requestsarray
Pedidos do seller.
requests[].iduuid
Id do pedido.
requests[].vendor_iduuid
Seller que pediu.
requests[].flow_iduuid
Fluxo a que o pedido se refere. Ausente se não havia fluxo.
requests[].titlestring
Resumo do pedido.
requests[].descriptionstring
Detalhes.
requests[].statusstring
pendingapprovedrejectedapplied
pending aguarda análise; approved foi aceito; rejected foi recusado; applied já foi feito no fluxo.
requests[].admin_notesstring
Resposta da plataforma. Ausente enquanto não houver.
requests[].created_byuuid
Usuário que abriu o pedido.
requests[].reviewed_byuuid
Quem analisou. Ausente enquanto pendente.
requests[].reviewed_atstring
RFC 3339. Quando foi analisado.
requests[].created_atstring
RFC 3339.
requests[].updated_atstring
RFC 3339.

Erros

StatusQuandoCorpo
401 / 403Autenticação, módulo ou privilégioveja Fluxo
500Falha ao ler{"error":"..."}

Abrir um pedido de mudança

POST/api/v1/vendor/whatsapp/flow-requestsSeller

Pede à plataforma uma mudança na estrutura do fluxo

Registra o pedido como pending. A mudança não é aplicada automaticamente: uma pessoa da plataforma analisa, e o resultado aparece no status e em admin_notes. Responde 201 com o pedido.

Corpo da requisição

titlestringobrigatório
Resumo do que você quer. Não pode ficar vazio.
descriptionstring
Detalhes, com o comportamento esperado.
flow_iduuid
Fluxo envolvido. Se omitido, usa o fluxo ativo do seller.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/flow-requests" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Acrescentar passo de troca e devolução",
  "description": "Depois do menu, uma opção que explique o prazo de troca."
}'

Resposta

201Pedido registrado
json
{
  "id": "e7d6c5b4-0000-4000-8000-000000000001",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "title": "Acrescentar passo de troca e devolução",
  "description": "Depois do menu, uma opção que explique o prazo de troca.",
  "status": "pending",
  "created_by": "d4613dde-ac7a-4319-9232-50d8cd6ad5fc",
  "created_at": "2026-10-11T14:40:00Z",
  "updated_at": "2026-10-11T14:40:00Z"
}

Erros

StatusQuandoCorpo
400JSON inválido{"error":"invalid json"}
400title vazio{"error":"vendor_id and title required"}
401 / 403Autenticação, módulo ou privilégioveja Fluxo
Acompanhe pela listagem

Não há notificação por esta API quando o pedido muda de situação. Consulte GET /flow-requests de tempos em tempos ou mostre a lista ao usuário.

Veja também

  • Fluxo
  • Blocos
  • Modelos prontos
Anterior
Conexões
Próxima
Modelos prontos
Nesta página
  • Ler os textos editáveis
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar textos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Listar pedidos de mudança
  • Exemplo de requisição
  • Resposta
  • Erros
  • Abrir um pedido de mudança
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também