API atual/Referência completa/Mini-loja WhatsApp: atendimento

Solicitações de suporte

Envia uma reclamação, uma qualificação de revendedor ou o pedido de falar com uma pessoa, e recebe um protocolo.

Três ações da tela "Ajuda" gravam algo para a equipe da loja. As duas primeiras geram um protocolo que o cliente guarda; a terceira passa a conversa para um atendente. Antes de mostrar os botões, leia a central de ajuda: ela diz quais ações a loja aceita (complaint_enabled, reseller_enabled, human_available).

Duas regras valem para as três:

O corpo é JSON estrito: qualquer campo desconhecido é recusado (400 invalid_support_request) e o corpo tem no máximo 32 KB.
As solicitações são idempotentes pelo submission_id: reenviar o mesmo submission_id (duplo toque, rede instável) devolve o mesmo protocolo, sem criar um segundo registro. Gere um UUID novo por formulário preenchido.

Enviar uma reclamação

POST/api/v1/storefront/wa-coex/support/{token}/complaintsPública

Registra uma reclamação e devolve o protocolo

Se a conversa do cliente com a loja já existe, a reclamação fica ligada a ela para o atendente ver o histórico. Informar order_id liga a reclamação a um pedido do próprio cliente.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

submission_iduuidobrigatório

Identificador desta submissão, gerado pelo seu front-end. Garante a idempotência.

issue_typestringobrigatório

defectivewrong_itemdelivery_delaynot_receivedbillingother

Tipo do problema: produto com defeito, item errado, atraso na entrega, não recebido, cobrança ou outro.

descriptionstringobrigatório

Descrição do cliente, de 10 a 2.000 caracteres.

order_iduuid

Pedido a que a reclamação se refere. Precisa ser um pedido do cliente do token.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/support/$TOKEN/complaints" \
  -H "Content-Type: application/json" \
  -d '{
    "submission_id": "3f0b6d3a-2c5e-4a39-9a5e-6a4c2f1d8b77",
    "issue_type": "delivery_delay",
    "description": "O pedido está atrasado há uma semana.",
    "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33"
  }'

Resposta

201Reclamação registrada

json

{
  "status": "accepted",
  "protocol": "SAC-1A2B3C4D",
  "next_action": "support",
  "message": "Recebemos sua solicitação. Nossa equipe vai analisar e continuar o atendimento.",
  "contact_url": "https://wa.me/5511999998888"
}

Campos da resposta (comuns às três ações)

statusstring

acceptedredirectunavailable

accepted: registrado. redirect e unavailable só aparecem em falar com uma pessoa.

protocolstring

Protocolo para o cliente guardar: SAC- mais 8 caracteres numa reclamação, REV- mais 8 numa qualificação. Ausente em "falar com uma pessoa".

next_actionstring

O que a tela faz em seguida. Reclamação: support. Qualificação: registration ou prepare_document. Atendimento: wait_in_chat, open_whatsapp ou faq.

messagestring

Frase em português para mostrar ao cliente.

contact_urlstring

Link wa.me da loja, quando há.

Erros

Status	Quando	Corpo
400	JSON inválido, com campo desconhecido ou maior que 32 KB.	`{"error":"invalid_support_request"}`
404	A loja desligou reclamações.	`{"error":"complaints_disabled"}`
422	`submission_id` que não é UUID.	`{"error":"invalid_submission_id"}`
422	`issue_type` fora da lista, ou `description` com menos de 10 ou mais de 2.000 caracteres.	`{"error":"invalid_complaint"}`
422	`order_id` que não é UUID, ou de um pedido que não é do cliente.	`{"error":"order_not_available"}`
503	Falha ao gravar.	`{"error":"support_unavailable"}`

Qualificar como revendedor

POST/api/v1/storefront/wa-coex/support/{token}/reseller-leadsPública

Registra a qualificação de um possível revendedor

Em lojas B2B, quem quer revender responde a algumas perguntas antes do cadastro da empresa. A resposta diz o próximo passo: seguir para o cadastro (quando tem CNPJ) ou providenciar o documento.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

submission_iduuidobrigatório

Identificador desta submissão, gerado pelo seu front-end.

has_cnpjstringobrigatório

yesnoin_progress

Tem CNPJ: sim, não ou em andamento.

store_typestringobrigatório

physicalonlinebothnone

Tipo de loja: física, online, as duas ou nenhuma.

statestringobrigatório

UF da loja, uma das 27 siglas, em maiúsculas (ou minúsculas, que são convertidas).

monthly_volumestringobrigatório

up_to_2k2k_5k5k_10kabove_10k

Faixa de compra mensal esperada, em reais: até 2 mil, de 2 a 5 mil, de 5 a 10 mil, acima de 10 mil.

how_found_usstringobrigatório

googleinstagramfacebookreferraleventother

Como conheceu a loja.

has_state_registrationstringobrigatório

yesnounknown

Tem inscrição estadual: sim, não ou não sabe.

brands_soldstring

Marcas que já vende, até 500 caracteres.

Resposta

201Qualificação registrada

json

{
  "status": "accepted",
  "protocol": "REV-9F8E7D6C",
  "next_action": "registration",
  "message": "Qualificação recebida. Você pode continuar no cadastro da empresa.",
  "contact_url": "https://wa.me/5511999998888"
}

Com has_cnpj diferente de yes, next_action vem prepare_document e a message diz que o cliente pode voltar quando o CNPJ estiver pronto ou falar com a equipe agora. Os campos da resposta são os de Enviar uma reclamação.

Erros

Status	Quando	Corpo
400	JSON inválido, com campo desconhecido ou maior que 32 KB.	`{"error":"invalid_support_request"}`
404	A loja não faz qualificação de revendedor.	`{"error":"reseller_qualification_disabled"}`
422	`submission_id` que não é UUID.	`{"error":"invalid_submission_id"}`
422	Algum campo fora dos valores aceitos.	`{"error":"invalid_lead"}`
422	`brands_sold` com mais de 500 caracteres.	`{"error":"support_value_too_large"}`
503	Falha ao gravar.	`{"error":"support_unavailable"}`

Falar com uma pessoa

POST/api/v1/storefront/wa-coex/support/{token}/handoffPública

Pede para um atendente assumir a conversa

Pede que uma pessoa da loja continue o atendimento. O resultado depende de a loja ter atendimento humano ligado, de estar dentro do horário e de o cliente já ter uma conversa no WhatsApp. Nunca é um erro HTTP: a resposta é sempre 200 e o campo status conta o que aconteceu.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Não tem corpo.

Resposta

200Atendimento solicitado

json

{
  "status": "accepted",
  "next_action": "wait_in_chat",
  "message": "Atendimento solicitado. Um atendente vai continuar nesta conversa.",
  "contact_url": "https://wa.me/5511999998888"
}

200Sem atendimento agora

json

{
  "status": "unavailable",
  "next_action": "faq",
  "message": "O atendimento com uma pessoa não está disponível no momento.",
  "contact_url": "https://wa.me/5511999998888"
}

`status`	`next_action`	Quando
`accepted`	`wait_in_chat`	O cliente tem conversa com a loja no WhatsApp e um atendente assumiu.
`redirect`	`open_whatsapp`	O cliente ainda não tem conversa (ou é visitante): abra `contact_url` para começar uma.
`unavailable`	`faq`	Atendimento humano desligado, fora do horário ou sem como contatar. `message` explica.

Veja também

API atual/Referência completa/Mini-loja WhatsApp: atendimento

Solicitações de suporte

Envia uma reclamação, uma qualificação de revendedor ou o pedido de falar com uma pessoa, e recebe um protocolo.

Duas regras valem para as três:

O corpo é JSON estrito: qualquer campo desconhecido é recusado (400 invalid_support_request) e o corpo tem no máximo 32 KB.
As solicitações são idempotentes pelo submission_id: reenviar o mesmo submission_id (duplo toque, rede instável) devolve o mesmo protocolo, sem criar um segundo registro. Gere um UUID novo por formulário preenchido.

Enviar uma reclamação

POST/api/v1/storefront/wa-coex/support/{token}/complaintsPública

Registra uma reclamação e devolve o protocolo

Se a conversa do cliente com a loja já existe, a reclamação fica ligada a ela para o atendente ver o histórico. Informar order_id liga a reclamação a um pedido do próprio cliente.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

submission_iduuidobrigatório

Identificador desta submissão, gerado pelo seu front-end. Garante a idempotência.

issue_typestringobrigatório

defectivewrong_itemdelivery_delaynot_receivedbillingother

Tipo do problema: produto com defeito, item errado, atraso na entrega, não recebido, cobrança ou outro.

descriptionstringobrigatório

Descrição do cliente, de 10 a 2.000 caracteres.

order_iduuid

Pedido a que a reclamação se refere. Precisa ser um pedido do cliente do token.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/wa-coex/support/$TOKEN/complaints" \
  -H "Content-Type: application/json" \
  -d '{
    "submission_id": "3f0b6d3a-2c5e-4a39-9a5e-6a4c2f1d8b77",
    "issue_type": "delivery_delay",
    "description": "O pedido está atrasado há uma semana.",
    "order_id": "9f4a6d2e-1b7c-4c53-8d21-5e0b6a7c1f33"
  }'

Resposta

201Reclamação registrada

json

{
  "status": "accepted",
  "protocol": "SAC-1A2B3C4D",
  "next_action": "support",
  "message": "Recebemos sua solicitação. Nossa equipe vai analisar e continuar o atendimento.",
  "contact_url": "https://wa.me/5511999998888"
}

Campos da resposta (comuns às três ações)

statusstring

acceptedredirectunavailable

accepted: registrado. redirect e unavailable só aparecem em falar com uma pessoa.

protocolstring

Protocolo para o cliente guardar: SAC- mais 8 caracteres numa reclamação, REV- mais 8 numa qualificação. Ausente em "falar com uma pessoa".

next_actionstring

O que a tela faz em seguida. Reclamação: support. Qualificação: registration ou prepare_document. Atendimento: wait_in_chat, open_whatsapp ou faq.

messagestring

Frase em português para mostrar ao cliente.

contact_urlstring

Link wa.me da loja, quando há.

Erros

Status	Quando	Corpo
400	JSON inválido, com campo desconhecido ou maior que 32 KB.	`{"error":"invalid_support_request"}`
404	A loja desligou reclamações.	`{"error":"complaints_disabled"}`
422	`submission_id` que não é UUID.	`{"error":"invalid_submission_id"}`
422	`issue_type` fora da lista, ou `description` com menos de 10 ou mais de 2.000 caracteres.	`{"error":"invalid_complaint"}`
422	`order_id` que não é UUID, ou de um pedido que não é do cliente.	`{"error":"order_not_available"}`
503	Falha ao gravar.	`{"error":"support_unavailable"}`

Qualificar como revendedor

POST/api/v1/storefront/wa-coex/support/{token}/reseller-leadsPública

Registra a qualificação de um possível revendedor

Em lojas B2B, quem quer revender responde a algumas perguntas antes do cadastro da empresa. A resposta diz o próximo passo: seguir para o cadastro (quando tem CNPJ) ou providenciar o documento.

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Corpo da requisição

submission_iduuidobrigatório

Identificador desta submissão, gerado pelo seu front-end.

has_cnpjstringobrigatório

yesnoin_progress

Tem CNPJ: sim, não ou em andamento.

store_typestringobrigatório

physicalonlinebothnone

Tipo de loja: física, online, as duas ou nenhuma.

statestringobrigatório

UF da loja, uma das 27 siglas, em maiúsculas (ou minúsculas, que são convertidas).

monthly_volumestringobrigatório

up_to_2k2k_5k5k_10kabove_10k

Faixa de compra mensal esperada, em reais: até 2 mil, de 2 a 5 mil, de 5 a 10 mil, acima de 10 mil.

how_found_usstringobrigatório

googleinstagramfacebookreferraleventother

Como conheceu a loja.

has_state_registrationstringobrigatório

yesnounknown

Tem inscrição estadual: sim, não ou não sabe.

brands_soldstring

Marcas que já vende, até 500 caracteres.

Resposta

201Qualificação registrada

json

{
  "status": "accepted",
  "protocol": "REV-9F8E7D6C",
  "next_action": "registration",
  "message": "Qualificação recebida. Você pode continuar no cadastro da empresa.",
  "contact_url": "https://wa.me/5511999998888"
}

Erros

Status	Quando	Corpo
400	JSON inválido, com campo desconhecido ou maior que 32 KB.	`{"error":"invalid_support_request"}`
404	A loja não faz qualificação de revendedor.	`{"error":"reseller_qualification_disabled"}`
422	`submission_id` que não é UUID.	`{"error":"invalid_submission_id"}`
422	Algum campo fora dos valores aceitos.	`{"error":"invalid_lead"}`
422	`brands_sold` com mais de 500 caracteres.	`{"error":"support_value_too_large"}`
503	Falha ao gravar.	`{"error":"support_unavailable"}`

Falar com uma pessoa

POST/api/v1/storefront/wa-coex/support/{token}/handoffPública

Pede para um atendente assumir a conversa

Parâmetros de caminho

tokenstringobrigatório

Token da mini-loja.

Não tem corpo.

Resposta

200Atendimento solicitado

json

{
  "status": "accepted",
  "next_action": "wait_in_chat",
  "message": "Atendimento solicitado. Um atendente vai continuar nesta conversa.",
  "contact_url": "https://wa.me/5511999998888"
}

200Sem atendimento agora

json

{
  "status": "unavailable",
  "next_action": "faq",
  "message": "O atendimento com uma pessoa não está disponível no momento.",
  "contact_url": "https://wa.me/5511999998888"
}

`status`	`next_action`	Quando
`accepted`	`wait_in_chat`	O cliente tem conversa com a loja no WhatsApp e um atendente assumiu.
`redirect`	`open_whatsapp`	O cliente ainda não tem conversa (ou é visitante): abra `contact_url` para começar uma.
`unavailable`	`faq`	Atendimento humano desligado, fora do horário ou sem como contatar. `message` explica.