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

Dicionário de marcas

Ensina o assistente do WhatsApp a entender marcas e termos escritos errado e testa como uma frase de cliente seria interpretada.

O cliente escreve do jeito que sabe: adidaz, ifone, nik. O dicionário de marcas guarda pares grafia errada para nome correto (misspelling para canonical). Antes de procurar no catálogo, o assistente troca a grafia errada pelo nome correto. Existem dois tipos de par:

  • manual: criado pelo seller por esta API.
  • auto-learned: aprendido pela própria plataforma a partir das conversas. Aparece na lista, e o seller pode ajustar ou apagar.

O weight (peso) desempata quando a mesma grafia aparece no dicionário do seller e também no dicionário geral da loja: vale o par de maior peso.

Listar os pares

GET/api/v1/vendor/whatsapp/brand-correctionsSeller

Lista os pares do dicionário do seller

Parâmetros de consulta

sourcestring
manualauto-learned
Filtra pela origem.
searchstring
Busca por trecho da grafia errada ou do nome correto, sem diferenciar maiúsculas.
limitintegerpadrão: 50
Itens por chamada, de 1 a 500. Fora desse intervalo volta para 50.
offsetintegerpadrão: 0
Quantos itens pular.

Exemplo de requisição

Resposta

200Pares devolvidos

Campos da resposta

entriesarray
Pares da página.
entries[].iduuid
Id do par.
entries[].vendor_iduuid
Seller dono.
entries[].misspellingstring
Grafia errada, sempre em minúsculas.
entries[].canonicalstring
Nome correto.
entries[].weightinteger
Peso de desempate.
entries[].sourcestring
manualauto-learned
Origem.
entries[].use_countinteger
Quantas vezes o par foi aplicado.
entries[].last_used_atstring
RFC 3339. Última aplicação. Ausente se nunca usado.
entries[].created_atstring
RFC 3339.
entries[].updated_atstring
RFC 3339.
totalinteger
Total de pares que atendem ao filtro.
limitinteger
Tamanho de página usado.
offsetinteger
Deslocamento usado.

Erros

StatusQuandoCorpo
401Sem token{"error":"authentication required"}
403Token que não é de seller; módulo desligado; falta o privilégioveja Entradas
404Usuário sem cadastro de seller{"error":"vendor profile not found","code":"vendor_profile_not_found"}
500Falha ao listar{"error":"Failed to list brand corrections: ..."}

Criar ou atualizar um par

POST/api/v1/vendor/whatsapp/brand-correctionsSeller

Cria um par ou atualiza o existente com a mesma grafia errada

Responde 201 com o par. Se o seller já tem um par para essa grafia errada, ele é atualizado (nome correto e peso) e a resposta continua 201.

Corpo da requisição

misspellingstringobrigatório
Como o cliente escreve. É aparado e convertido para minúsculas.
canonicalstringobrigatório
Como o produto ou a marca se chama de verdade.
weightintegerpadrão: 100
Peso de desempate. Zero ou negativo vale 100.
vendor_iduuid
Ignorado para sellers: vale o seller do token.

Exemplo de requisição

Resposta

201Par gravado

Erros

StatusQuandoCorpo
400JSON inválido{"error":"Invalid JSON body"}
400Falta misspelling{"error":"whatsapp brand_correction: misspelling required"}
400Falta canonical{"error":"whatsapp brand_correction: canonical required"}
401 / 403Autenticação, módulo ou privilégioveja Entradas
Repetir a grafia sobrescreve

Não há erro de duplicidade: mandar a mesma misspelling de novo troca o canonical e o weight do par existente. Guardar dois destinos para a mesma grafia não é possível por esta rota.

Alterar um par

PATCH/api/v1/vendor/whatsapp/brand-corrections/{id}Seller

Altera o nome correto ou o peso de um par

Só canonical e weight mudam. A grafia errada (misspelling) não pode ser alterada: apague o par e crie outro.

Parâmetros de caminho

iduuidobrigatório
Id do par.

Corpo da requisição

canonicalstring
Novo nome correto.
weightinteger
Novo peso. Zero ou negativo vale 100.

Exemplo de requisição

Resposta

200Par atualizado

A resposta não traz o par atualizado: leia a lista se precisar dos valores.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"Invalid JSON body"}
400canonical enviado vazio{"error":"whatsapp brand_correction: canonical cannot be empty"}
401 / 403Autenticação, módulo ou privilégioveja Entradas
404Par inexistente, apagado ou de outro seller{"error":"Brand correction not found"}

Alterar um par (PUT)

PUT/api/v1/vendor/whatsapp/brand-corrections/{id}Seller

Altera um par (mesmo comportamento do PATCH)

Mesmo tratamento do PATCH, inclusive o comportamento parcial: o que você não enviar não muda.

Parâmetros de caminho

iduuidobrigatório
Id do par.

Corpo da requisição

canonicalstring
Novo nome correto.
weightinteger
Novo peso. Zero ou negativo vale 100.

Exemplo de requisição

Resposta

200Par atualizado

Resposta e erros são os do PATCH.

Apagar um par

DELETE/api/v1/vendor/whatsapp/brand-corrections/{id}Seller

Apaga um par do dicionário

Exclusão lógica. Vale também para pares auto-learned.

Parâmetros de caminho

iduuidobrigatório
Id do par.

Exemplo de requisição

Resposta

200Par apagado

Erros

StatusQuandoCorpo
401 / 403Autenticação, módulo ou privilégioveja Entradas
404Par inexistente, já apagado ou de outro seller{"error":"Brand correction not found"}
500Falha ao apagar{"error":"Failed to delete brand correction: ..."}

Testar uma frase

POST/api/v1/vendor/whatsapp/brand-corrections/testSeller

Mostra como uma frase de cliente seria interpretada e quais produtos acharia

Executa a busca completa do assistente (correção de marcas, entendimento do pedido e busca no catálogo do seller) sobre uma frase, sem enviar nada a ninguém. Serve para conferir se o dicionário e o catálogo respondem como você espera.

Corpo da requisição

textstringobrigatório
A frase do cliente, por exemplo quero um tenis adidaz 42.
vendor_iduuid
Ignorado para sellers: vale o seller do token.

Exemplo de requisição

Resposta

200Resultado da busca

Campos da resposta

original_querystring
A frase enviada.
corrected_querystring
A frase depois das trocas do dicionário.
correctionsarray
Trocas aplicadas: objetos com from e to. Ausente quando nenhuma.
intentobject
O que o assistente entendeu: intent (por exemplo product_lookup), confidence (0 a 1), e quando identificados brand, model, category e keywords.
productsarray
Produtos do catálogo do seller que combinaram. Cada um traz id, name, price em centavos (29990 = R$ 299,90), quantity em estoque, image_url e outros campos de catálogo.
duration_msinteger
Quanto a busca levou, em milissegundos.
search_intent_idstring
Identificador do registro da busca, quando gravado.
display_querystring
Termos do produto sem filtros, quando a plataforma os separa. Ausente em geral.

Erros

StatusQuandoCorpo
400JSON inválido{"error":"Invalid JSON body"}
400Falha na busca{"error":"..."}
401 / 403Autenticação, módulo ou privilégioveja Entradas
Use para checar antes de criar o par

Rode test com a grafia que os clientes usam. Se corrections vier vazio e o produto não aparecer, crie o par e teste de novo. Os valores exatos de intent dependem do entendimento do pedido e podem variar entre chamadas.

Veja também

  • Entradas da base de conhecimento
  • Busca e vetores
Anterior
Busca e vetores
Próxima
Canal e catálogo do WhatsApp
Nesta página
  • Listar os pares
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar ou atualizar um par
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um par
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar um par (PUT)
  • Exemplo de requisição
  • Resposta
  • Apagar um par
  • Exemplo de requisição
  • Resposta
  • Erros
  • Testar uma frase
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections?source=manual" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "misspelling": "adidaz",
  "canonical": "Adidas"
}'
bash
curl -X PATCH "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections/$CORRECTION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "canonical": "Adidas Originals"
}'
bash
curl -X PUT "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections/$CORRECTION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "weight": 150
}'
bash
curl -X DELETE "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections/$CORRECTION_ID" \
  -H "Authorization: Bearer $TOKEN"
bash
curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "quero um tenis adidaz 42"
}'
json
{
  "entries": [
    {
      "id": "d1e2f3a4-0000-4000-8000-0000000000a1",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "misspelling": "adidaz",
      "canonical": "Adidas",
      "weight": 100,
      "source": "manual",
      "use_count": 3,
      "last_used_at": "2026-10-10T20:15:00Z",
      "created_at": "2026-10-02T13:00:00Z",
      "updated_at": "2026-10-02T13:00:00Z"
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}
json
{
  "id": "d1e2f3a4-0000-4000-8000-0000000000a1",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "misspelling": "adidaz",
  "canonical": "Adidas",
  "weight": 100,
  "source": "manual",
  "use_count": 0,
  "created_at": "2026-10-11T15:20:00Z",
  "updated_at": "2026-10-11T15:20:00Z"
}
json
{ "status": "updated", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }
json
{ "status": "updated", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }
json
{ "status": "deleted", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }
json
{
  "original_query": "quero um tenis adidaz 42",
  "corrected_query": "quero um tenis Adidas 42",
  "corrections": [{ "from": "adidaz", "to": "Adidas" }],
  "intent": {
    "intent": "product_lookup",
    "confidence": 0.9,
    "brand": "Adidas",
    "category": "tênis",
    "keywords": ["tenis", "42"]
  },
  "products": [
    {
      "id": "c3f92551-9dda-4fc7-b518-353d1c4e4035",
      "name": "Tênis Adidas Run 42",
      "price": 29990,
      "quantity": 8,
      "image_url": "https://minhaloja.io.venddor.com.br/uploads/tenis-run.jpg"
    }
  ],
  "duration_ms": 640
}