API atual/Referência completa/WhatsApp Commerce: fluxos e experiência

Fluxos nativos da Meta

Consulta, ativa e desativa os formulários nativos do WhatsApp (Flows), que substituem o link da mini-loja dentro da conversa.

Os fluxos nativos (WhatsApp Flows) são telas do próprio WhatsApp: o cliente se cadastra, escolhe endereço, frete e pagamento sem sair da conversa. A alternativa é a mini-loja, uma página web leve aberta por link (os botões "Abrir carrinho" e "Pagar pedido" de Carrinho e cobrança). Os dois modos não convivem: ativar os fluxos nativos desliga a mini-loja, e desativar religa.

Situação dos fluxos nativos

GET/api/v1/vendor/whatsapp/native-flows/statusSeller

Mostra se os fluxos nativos estão ativos e o que falta

Consulta a Meta ao vivo para comparar a chave de criptografia local com a registrada lá, então a resposta pode demorar um pouco.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/native-flows/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Situação

json

{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "104857392011234",
  "waba_id": "112233445566778",
  "encryption_matches": true,
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=104857392011234",
  "web_preview_disabled": false,
  "blockers": [],
  "flows": [
    { "key": "checkout", "name": "minhaloja checkout", "meta_flow_id": "", "status": "", "published": false }
  ],
  "activating": false
}

Campos da resposta

enabledboolean

true quando os fluxos nativos estão ligados na loja.

number_registeredboolean

true quando há número e token da Meta configurados. Sem isso não dá para ativar.

phone_number_idstring

Número usado.

waba_idstring

Conta WhatsApp Business. Ausente se não conhecida.

encryption_matchesboolean

true quando a chave de criptografia local é igual à registrada na Meta. Ao ativar, a plataforma reenvia a chave local, então um false aqui não impede.

local_public_keystring

Chave pública local (PEM). Ausente se ainda não gerada.

meta_public_keystring

Chave pública registrada na Meta (PEM). Ausente se não foi possível ler.

endpoint_uristring

URL pública que a Meta chama para trocar dados com o formulário. Vazia quando a loja não tem endereço público.

web_preview_disabledboolean

true quando a mini-loja está desligada (acompanha enabled).

blockersarray

Textos em português com o que impede ou atrapalha a ativação. Vazio quando está tudo certo.

flowsarray

Os 11 formulários padrão (catálogo, produto, busca, carrinho, checkout, login, cadastro, pedidos, perfil e outros) e a situação de cada um na Meta.

flows[].keystring

Chave do formulário.

flows[].namestring

Nome do formulário na Meta.

flows[].meta_flow_idstring

Id do formulário na Meta. Vazio antes da primeira ativação.

flows[].statusstring

Situação do formulário (por exemplo published).

flows[].publishedboolean

true quando está publicado na Meta.

activatingboolean

true enquanto a ativação roda em segundo plano.

activation_errorstring

Último erro da ativação em segundo plano, se houve.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado	veja Fluxo
500	Falha ao consultar	`{"error":"..."}`

Ativar

POST/api/v1/vendor/whatsapp/native-flows/activateSeller

Começa a ativação dos fluxos nativos

Sem corpo. A ativação é assíncrona: a chamada confere os pré-requisitos, dispara o trabalho em segundo plano e responde na hora com o estado atual (activating: true). Criar e publicar os formulários na Meta leva de cerca de 1 a 2 minutos. Acompanhe com GET /native-flows/status até activating: false e enabled: true.

Só quando todos os formulários são criados o modo muda: enabled vira true e a mini-loja é desligada. Se falhar, nada muda e o motivo fica em activation_error.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/native-flows/activate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ativação iniciada

json

{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "104857392011234",
  "waba_id": "112233445566778",
  "encryption_matches": true,
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=104857392011234",
  "web_preview_disabled": false,
  "blockers": [],
  "flows": [],
  "activating": true
}

422Pré-requisito faltando

json

{ "error": "cadastre o número do WhatsApp (phone_number_id + token) antes de ligar o Flow" }

A resposta 200 tem os mesmos campos de Situação.

Erros

Status	Quando	Corpo
401 / 403	Autenticação ou módulo	veja Fluxo
422	Sem número ou token da Meta	`{"error":"cadastre o número do WhatsApp (phone_number_id + token) antes de ligar o Flow"}`
422	Sem conta WhatsApp Business conhecida	`{"error":"WABA da loja ausente ... reconecte o número"}`
422	Loja sem endereço público	`{"error":"URL pública da loja ausente para o data exchange"}`
422	Uma ativação anterior ainda termina na Meta	`{"error":"a ativação anterior ainda está terminando na Meta ... tente de novo em 1–2 minutos"}`

Desativar

POST/api/v1/vendor/whatsapp/native-flows/deactivateSeller

Desliga os fluxos nativos e religa a mini-loja

Sem corpo. Cancela qualquer ativação em andamento (para ela não religar o modo logo depois), desliga os fluxos nativos e religa a mini-loja. Os formulários criados na Meta não são apagados.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/native-flows/deactivate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fluxos nativos desligados

json

{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "104857392011234",
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=104857392011234",
  "web_preview_disabled": false,
  "blockers": [],
  "flows": [],
  "activating": false
}

Os campos são os de Situação.

Erros

Status	Quando	Corpo
401 / 403	Autenticação ou módulo	veja Fluxo
500	Falha ao gravar	`{"error":"..."}`

Veja também

API atual/Referência completa/WhatsApp Commerce: fluxos e experiência

Fluxos nativos da Meta

Consulta, ativa e desativa os formulários nativos do WhatsApp (Flows), que substituem o link da mini-loja dentro da conversa.

Situação dos fluxos nativos

GET/api/v1/vendor/whatsapp/native-flows/statusSeller

Mostra se os fluxos nativos estão ativos e o que falta

Consulta a Meta ao vivo para comparar a chave de criptografia local com a registrada lá, então a resposta pode demorar um pouco.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/whatsapp/native-flows/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Situação

json

{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "104857392011234",
  "waba_id": "112233445566778",
  "encryption_matches": true,
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=104857392011234",
  "web_preview_disabled": false,
  "blockers": [],
  "flows": [
    { "key": "checkout", "name": "minhaloja checkout", "meta_flow_id": "", "status": "", "published": false }
  ],
  "activating": false
}

Campos da resposta

enabledboolean

true quando os fluxos nativos estão ligados na loja.

number_registeredboolean

true quando há número e token da Meta configurados. Sem isso não dá para ativar.

phone_number_idstring

Número usado.

waba_idstring

Conta WhatsApp Business. Ausente se não conhecida.

encryption_matchesboolean

true quando a chave de criptografia local é igual à registrada na Meta. Ao ativar, a plataforma reenvia a chave local, então um false aqui não impede.

local_public_keystring

Chave pública local (PEM). Ausente se ainda não gerada.

meta_public_keystring

Chave pública registrada na Meta (PEM). Ausente se não foi possível ler.

endpoint_uristring

URL pública que a Meta chama para trocar dados com o formulário. Vazia quando a loja não tem endereço público.

web_preview_disabledboolean

true quando a mini-loja está desligada (acompanha enabled).

blockersarray

Textos em português com o que impede ou atrapalha a ativação. Vazio quando está tudo certo.

flowsarray

Os 11 formulários padrão (catálogo, produto, busca, carrinho, checkout, login, cadastro, pedidos, perfil e outros) e a situação de cada um na Meta.

flows[].keystring

Chave do formulário.

flows[].namestring

Nome do formulário na Meta.

flows[].meta_flow_idstring

Id do formulário na Meta. Vazio antes da primeira ativação.

flows[].statusstring

Situação do formulário (por exemplo published).

flows[].publishedboolean

true quando está publicado na Meta.

activatingboolean

true enquanto a ativação roda em segundo plano.

activation_errorstring

Último erro da ativação em segundo plano, se houve.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado	veja Fluxo
500	Falha ao consultar	`{"error":"..."}`

Ativar

POST/api/v1/vendor/whatsapp/native-flows/activateSeller

Começa a ativação dos fluxos nativos

Só quando todos os formulários são criados o modo muda: enabled vira true e a mini-loja é desligada. Se falhar, nada muda e o motivo fica em activation_error.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/native-flows/activate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ativação iniciada

json

{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "104857392011234",
  "waba_id": "112233445566778",
  "encryption_matches": true,
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=104857392011234",
  "web_preview_disabled": false,
  "blockers": [],
  "flows": [],
  "activating": true
}

422Pré-requisito faltando

json

{ "error": "cadastre o número do WhatsApp (phone_number_id + token) antes de ligar o Flow" }

A resposta 200 tem os mesmos campos de Situação.

Erros

Status	Quando	Corpo
401 / 403	Autenticação ou módulo	veja Fluxo
422	Sem número ou token da Meta	`{"error":"cadastre o número do WhatsApp (phone_number_id + token) antes de ligar o Flow"}`
422	Sem conta WhatsApp Business conhecida	`{"error":"WABA da loja ausente ... reconecte o número"}`
422	Loja sem endereço público	`{"error":"URL pública da loja ausente para o data exchange"}`
422	Uma ativação anterior ainda termina na Meta	`{"error":"a ativação anterior ainda está terminando na Meta ... tente de novo em 1–2 minutos"}`

Desativar

POST/api/v1/vendor/whatsapp/native-flows/deactivateSeller

Desliga os fluxos nativos e religa a mini-loja

Sem corpo. Cancela qualquer ativação em andamento (para ela não religar o modo logo depois), desliga os fluxos nativos e religa a mini-loja. Os formulários criados na Meta não são apagados.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/native-flows/deactivate" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fluxos nativos desligados

json

{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "104857392011234",
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=104857392011234",
  "web_preview_disabled": false,
  "blockers": [],
  "flows": [],
  "activating": false
}

Os campos são os de Situação.

Erros

Status	Quando	Corpo
401 / 403	Autenticação ou módulo	veja Fluxo
500	Falha ao gravar	`{"error":"..."}`