VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp: conhecimento do assistente

Correções de marca

Dicionário de grafias erradas e apelidos que o assistente corrige antes de buscar produtos.

Clientes escrevem "mengao", "camiza", "adidaz". O dicionário de correções liga cada grafia ao nome certo para a busca de produtos achar o que o cliente quer. Estas rotas mantêm o dicionário e testam o resultado. Além do privilégio comum, exigem manage_whatsapp.

Listar correções

Devolve o dicionário de correções da loja, com filtros e paginação.

GET/api/v1/admin/whatsapp/brand-correctionsAdmin

Lista as correções de marca

Parâmetros de consulta

vendor_iduuid
Mostra só as correções desse seller (não inclui as da loja toda).
sourcestring
manualauto-learned
Filtra pela origem.
searchstring
Trecho a procurar na grafia errada e no nome correto.
limitintegerpadrão: 50
Itens por página. Valores menores que 1 ou maiores que 500 voltam para 50.
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição (Listar correções)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/brand-corrections?source=manual" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar correções)

200Correções devolvidas
json
{
  "entries": [
    {
      "id": "2c8d4e7a-91b3-4a05-b6f2-7e3a9d1c5b48",
      "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
      "misspelling": "mengao",
      "canonical": "Flamengo",
      "weight": 100,
      "source": "manual",
      "use_count": 0,
      "created_at": "2026-10-11T14:20:00.000000Z",
      "updated_at": "2026-10-11T14:20:00.000000Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Campos da resposta

entriesarray

Correções da página.

iduuid
Identificador da correção.
vendor_iduuid
Seller dono da correção. Ausente quando vale para a loja toda.
misspellingstring
A grafia errada ou apelido, sempre em minúsculas.
canonicalstring
O nome correto que substitui a grafia errada.
weightinteger
Prioridade quando duas correções disputam a mesma grafia: vence o maior peso.
sourcestring
manualauto-learned
Origem: manual (cadastrada por pessoa) ou auto-learned (aprendida pela plataforma).
last_used_atstring
Último uso em uma busca (RFC 3339). Ausente se nunca foi usada.
use_countinteger
Quantas vezes foi aplicada.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).
totalinteger
Total que casa com os filtros.
limitinteger
Limite aplicado.
offsetinteger
Deslocamento aplicado.

Erros (Listar correções)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
500Falha ao consultar.{"error":"Failed to list brand corrections: ..."}

Criar ou atualizar uma correção

Ensina a plataforma que uma grafia (por exemplo mengao) significa um nome certo (Flamengo). Se a mesma grafia já existir para o mesmo seller, a correção existente é atualizada no lugar, sem erro.

POST/api/v1/admin/whatsapp/brand-correctionsAdmin

Cria (ou atualiza) uma correção de marca

Corpo da requisição

misspellingstringobrigatório
Grafia errada ou apelido. Obrigatório. É gravado em minúsculas e sem espaços nas pontas.
canonicalstringobrigatório
Nome correto. Obrigatório.
weightintegerpadrão: 100
Prioridade. Zero, negativo ou omitido vira 100.
vendor_iduuid
Seller dono da correção. Omitido, vale para a loja toda.

Exemplo de requisição (Criar uma correção)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/brand-corrections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "misspelling": "mengao",
    "canonical": "Flamengo",
    "weight": 100
  }'

Resposta (Criar uma correção)

201Correção gravada
json
{
  "id": "2c8d4e7a-91b3-4a05-b6f2-7e3a9d1c5b48",
  "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
  "misspelling": "mengao",
  "canonical": "Flamengo",
  "weight": 100,
  "source": "manual",
  "use_count": 0,
  "created_at": "2026-10-11T14:20:00.000000Z",
  "updated_at": "2026-10-11T14:20:00.000000Z"
}

Campos da resposta

iduuid
Identificador da correção.
vendor_iduuid
Seller dono da correção. Ausente quando vale para a loja toda.
misspellingstring
A grafia errada ou apelido, sempre em minúsculas.
canonicalstring
O nome correto que substitui a grafia errada.
weightinteger
Prioridade quando duas correções disputam a mesma grafia: vence o maior peso.
sourcestring
manualauto-learned
Origem: manual (cadastrada por pessoa) ou auto-learned (aprendida pela plataforma).
last_used_atstring
Último uso em uma busca (RFC 3339). Ausente se nunca foi usada.
use_countinteger
Quantas vezes foi aplicada.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Criar uma correção)

StatusQuandoCorpo
400Corpo que não é JSON, ou grafia ou nome vazios.{"error":"whatsapp brand_correction: misspelling required"} ou {"error":"whatsapp brand_correction: canonical required"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Sempre 201

O status é 201 também quando uma correção existente foi atualizada no lugar.

Aprendizado automático

Além das correções cadastradas aqui, a plataforma aprende sozinha novas grafias (source = auto-learned). Revise-as de vez em quando, ordenando mentalmente por use_count.

Alterar uma correção

Muda o nome correto e/ou o peso. A grafia errada não muda: para renomeá-la, apague e crie de novo.

PATCH/api/v1/admin/whatsapp/brand-corrections/{id}Admin

Altera uma correção de marca

Parâmetros de caminho

iduuidobrigatório
Id da correção.

Corpo da requisição

canonicalstring
Novo nome correto. Não pode ficar vazio.
weightinteger
Novo peso. Zero ou negativo vira 100.

Exemplo de requisição (Alterar uma correção)

bash
curl -X PATCH "$BASE_URL/api/v1/admin/whatsapp/brand-corrections/2c8d4e7a-91b3-4a05-b6f2-7e3a9d1c5b48" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "canonical": "Flamengo",
    "weight": 150
  }'

Resposta (Alterar uma correção)

200Correção atualizada
json
{
  "status": "updated",
  "id": "2c8d4e7a-91b3-4a05-b6f2-7e3a9d1c5b48"
}

Campos da resposta

statusstring
updated
Sempre updated.
iduuid
O id alterado.

Erros (Alterar uma correção)

StatusQuandoCorpo
400Corpo que não é JSON, ou canonical vazio.{"error":"whatsapp brand_correction: canonical cannot be empty"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
404Correção não encontrada.{"error":"Brand correction not found"}
Não devolve a correção

A resposta só confirma. Para ver o resultado, liste de novo.

Apagar uma correção

Remove a correção do dicionário (remoção lógica).

DELETE/api/v1/admin/whatsapp/brand-corrections/{id}Admin

Apaga uma correção de marca

Parâmetros de caminho

iduuidobrigatório
Id da correção.

Exemplo de requisição (Apagar uma correção)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp/brand-corrections/2c8d4e7a-91b3-4a05-b6f2-7e3a9d1c5b48" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar uma correção)

200Correção apagada
json
{
  "status": "deleted",
  "id": "2c8d4e7a-91b3-4a05-b6f2-7e3a9d1c5b48"
}

Campos da resposta

statusstring
deleted
Sempre deleted.
iduuid
O id apagado.

Erros (Apagar uma correção)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
404Correção não encontrada.{"error":"Brand correction not found"}
500O id não é um UUID válido, ou falha ao apagar.{"error":"Failed to delete brand correction: ..."}

Testar uma frase

Roda a busca de produtos do assistente com uma frase de cliente e mostra o que ela entendeu: a frase corrigida, a intenção e os produtos encontrados. Não envia nada a ninguém.

POST/api/v1/admin/whatsapp/brand-corrections/testAdmin

Testa a busca inteligente com uma frase

Corpo da requisição

textstringobrigatório
Frase de cliente a testar, por exemplo quero uma camiza do mengao.
vendor_iduuid
Seller cujo catálogo será consultado. Omitido, consulta a loja.

Exemplo de requisição (Testar uma frase)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/brand-corrections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "quero uma camiza do mengao"
  }'

Resposta (Testar uma frase)

200Resultado da busca
json
{
  "original_query": "quero uma camiza do mengao",
  "corrected_query": "quero uma camiza do mengao",
  "intent": {
    "intent": "product_lookup",
    "confidence": 0.95,
    "brand": "Flamengo",
    "category": "camisa",
    "keywords": [
      "camisa"
    ]
  },
  "products": [
    {
      "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766",
      "name": "Camisa do Flamengo Masculina I 26",
      "sku": "FLA-I-26",
      "slug": "camisa-flamengo-masculina-i-26",
      "price": 30000,
      "list_price": 44990,
      "quantity": 38,
      "category_name": "Camisetas",
      "image_url": "/uploads/produtos/flamengo-i-26.png"
    }
  ],
  "duration_ms": 794,
  "search_intent_id": "8b5267f1-33c9-4fd2-a1f2-25f9104cf516"
}

Campos da resposta

original_querystring
A frase enviada.
corrected_querystring
A frase depois de aplicar as correções cadastradas.
correctionsarray
Substituições feitas, cada uma {from, to}. Ausente quando nenhuma correção cadastrada casou.
intentobject

O que o cliente quer.

intentstring
product_lookupprice_quoteorder_statusgeneralunknown
Intenção detectada.
confidencenumber
Confiança de 0 a 1.
brandstring
Marca ou assunto específico citado.
modelstring
Modelo citado, se houver.
categorystring
Categoria citada, se houver.
keywordsarray
Termos de busca já normalizados.
productsarray

Produtos encontrados. Preços em centavos inteiros (30000 = R$ 300,00).

iduuid
Id do produto.
namestring
Nome.
skustring
SKU.
slugstring
Slug de URL.
priceinteger
Preço de venda, em centavos.
list_priceinteger
Preço de tabela (antes do desconto), em centavos. Ausente quando não há.
quantityinteger
Estoque disponível.
vendor_iduuid
Seller do produto.
category_iduuid
Categoria.
category_namestring
Nome da categoria.
image_urlstring
Imagem principal (caminho relativo ou URL).
duration_msinteger
Tempo da busca, em milissegundos.
search_intent_iduuid
Id do registro da busca. Ausente quando não foi gravado.

Erros (Testar uma frase)

StatusQuandoCorpo
400Corpo que não é JSON ou falha na busca.{"error":"Invalid JSON body"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
Use para validar uma correção nova

Cadastre a correção, rode este teste com a grafia errada e confira se corrections traz a troca e se products melhora.

Depende da IA

A leitura da intenção usa a IA da loja. Sem ela, a plataforma cai numa leitura mais simples e com menos confiança.

Veja também

  • Entradas da base
  • Visão geral
Anterior
Busca e índice da base
Próxima
Registro de chamadas à IA
Nesta página
  • Listar correções
  • Exemplo de requisição (Listar correções)
  • Resposta (Listar correções)
  • Erros (Listar correções)
  • Criar ou atualizar uma correção
  • Exemplo de requisição (Criar uma correção)
  • Resposta (Criar uma correção)
  • Erros (Criar uma correção)
  • Alterar uma correção
  • Exemplo de requisição (Alterar uma correção)
  • Resposta (Alterar uma correção)
  • Erros (Alterar uma correção)
  • Apagar uma correção
  • Exemplo de requisição (Apagar uma correção)
  • Resposta (Apagar uma correção)
  • Erros (Apagar uma correção)
  • Testar uma frase
  • Exemplo de requisição (Testar uma frase)
  • Resposta (Testar uma frase)
  • Erros (Testar uma frase)
  • Veja também