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

bash

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

Resposta

200Pares devolvidos

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
}

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

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; falta o privilégio	veja Entradas
404	Usuário sem cadastro de seller	`{"error":"vendor profile not found","code":"vendor_profile_not_found"}`
500	Falha 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

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"
}'

Resposta

201Par gravado

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"
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	Falta `misspelling`	`{"error":"whatsapp brand_correction: misspelling required"}`
400	Falta `canonical`	`{"error":"whatsapp brand_correction: canonical required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas

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

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"
}'

Resposta

200Par atualizado

json

{ "status": "updated", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }

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

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	`canonical` enviado vazio	`{"error":"whatsapp brand_correction: canonical cannot be empty"}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas
404	Par 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

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
}'

Resposta

200Par atualizado

json

{ "status": "updated", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }

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

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections/$CORRECTION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Par apagado

json

{ "status": "deleted", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou privilégio	veja Entradas
404	Par inexistente, já apagado ou de outro seller	`{"error":"Brand correction not found"}`
500	Falha 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

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"
}'

Resposta

200Resultado da busca

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
}

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	Falha na busca	`{"error":"..."}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas

Veja também

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.

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

bash

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

Resposta

200Pares devolvidos

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
}

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

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; falta o privilégio	veja Entradas
404	Usuário sem cadastro de seller	`{"error":"vendor profile not found","code":"vendor_profile_not_found"}`
500	Falha 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

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"
}'

Resposta

201Par gravado

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"
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	Falta `misspelling`	`{"error":"whatsapp brand_correction: misspelling required"}`
400	Falta `canonical`	`{"error":"whatsapp brand_correction: canonical required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas

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

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"
}'

Resposta

200Par atualizado

json

{ "status": "updated", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }

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

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	`canonical` enviado vazio	`{"error":"whatsapp brand_correction: canonical cannot be empty"}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas
404	Par 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

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
}'

Resposta

200Par atualizado

json

{ "status": "updated", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }

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

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/whatsapp/brand-corrections/$CORRECTION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Par apagado

json

{ "status": "deleted", "id": "d1e2f3a4-0000-4000-8000-0000000000a1" }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou privilégio	veja Entradas
404	Par inexistente, já apagado ou de outro seller	`{"error":"Brand correction not found"}`
500	Falha 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

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

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"
}'

Resposta

200Resultado da busca

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
}

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

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	Falha na busca	`{"error":"..."}`
401 / 403	Autenticação, módulo ou privilégio	veja Entradas