VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Venddor Intelligence

Listas de opções

Responde a uma lista de opções que a VI mostrou na conversa, busca dentro dela e consulta o estado.

Quando o pedido é ambíguo ("aumente o preço do mouse" e existem sete mouses), a VI não chuta: mostra uma lista de opções na conversa e espera o clique. Cada lista tem um selection_id e uma ou mais posições (slot), por exemplo "qual produto". Estas três rotas deixam uma interface própria renderizar a lista e devolver a escolha. O ciclo de vida da lista é pending (esperando), answered (respondida) ou expired (venceu).

Responder a uma lista

Envia a escolha do seller. Depois de aceita, a VI retoma a ação que estava esperando e grava a continuação na conversa. Se a ação for destrutiva, a resposta pede aprovação (requires_approval) em vez de executar.

POST/api/v1/vendor/intelligence/sessions/{id}/selectionSeller

Responder a uma lista de opções

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id da sessão.

Corpo da requisição

selection_idstringobrigatório
Id da lista, vindo no bloco da mensagem.
choicesobject
Escolha única por posição: {"slot": "id-do-registro"}.
multi_choicesobject
Escolha múltipla por posição: {"slot": ["id1", "id2"]}. No máximo 200 ids por envio.

Exemplo de requisição

Resposta

200Escolha aceita

Campos da resposta

statusstring
Estado da lista após o envio.
messagesarray
Mensagens novas gravadas na conversa (role, content, created_at, id).
selectionobject
Resumo: selection_id, status, chosen (uma escolha por posição) e chosen_multi.
requires_approvalboolean
true quando falta o "sim" de uma ação destrutiva.
approval_tokenstring
Token da ação que aguarda aprovação, quando requires_approval é true. Esta API do seller não tem rota de confirmação.
duplicateboolean
Só aparece no corpo do 409 de uma lista já respondida: vem true, junto de selection e result (o resultado da primeira resposta, que rodou uma única vez).
continue_in_chatstring
Texto que a interface deve enviar como próxima mensagem para continuar o assunto.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
404Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).{"error":"não encontrei essa lista de opções..."} (devolvido em português)
400Escolha incompleta, posição desconhecida, mais de 200 ids, corpo ilegível ou id que não está mais na lista.{"error":"escolha incompleta: falta escolher o produto"} (devolvido em português)
409Lista já respondida, vencida ou ação recusada por regra de dados (cupom em uso, valor acima do teto, sem permissão).{"error":"...","status":"answered"} ou {"error":"...","status":"expired"}
502A ação retomada falhou; a lista volta a pending e o clique pode ser repetido.{"error":"não consegui aplicar a ação agora..."}
Limites

O corpo aceita até 256 KB. Os erros dessas rotas chegam em português, ou em inglês quando a requisição pede inglês (cabeçalho X-Venddor-Locale, parâmetro ?lang= ou Accept-Language, nessa ordem de prioridade). Nos exemplos de erro desta página, o texto em português é o padrão.

Buscar dentro da lista

Quando a lista mostra poucas opções (6 por página), esta rota busca outras dentro da mesma posição, com paginação, ordenação e filtros. Só uma busca por lista pode estar em andamento.

POST/api/v1/vendor/intelligence/sessions/{id}/selection/searchSeller

Buscar dentro de uma lista de opções

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id da sessão.

Corpo da requisição

selection_idstringobrigatório
Id da lista.
slotstringobrigatório
Posição onde buscar.
querystringobrigatório
Texto da busca.
offsetintegerpadrão: 0
Deslocamento para paginar.
limitinteger
Itens por página.
orderstring
Ordenação, quando a posição oferece.
include_inactivebooleanpadrão: false
Inclui registros inativos.
filtersarray
Filtros: objetos {"field", "op", "value", "value2"}. op é um de eq, ne, gt, gte, lt, lte, between, is_null, not_null, zero, contains.

Exemplo de requisição

Resposta

200Candidatos

Campos da resposta

slotstring
Posição pesquisada.
querystring
Texto da busca.
offsetinteger
Deslocamento usado.
page_sizeinteger
Tamanho da página.
candidatesarray
Opções: id, label, sublabel, thumb, badges, score.
total_foundinteger
Total de resultados da busca.
empty_hintstring
Dica quando não houve resultados.
facetsarray
Filtros sugeridos (key, label, options). Devolva a opção escolhida em filters.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
404Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).{"error":"não encontrei essa lista de opções..."} (devolvido em português)
400Busca vazia, entidade desconhecida ou corpo ilegível.{"error":"não entendi a busca enviada"} (devolvido em português)
429Já há uma busca em andamento nesta lista.{"error":"uma busca já está em andamento..."} (devolvido em português)

Ler o estado da lista

Devolve o estado atual da lista. Use ao reabrir uma conversa para saber se um cartão antigo ainda está esperando resposta (interactive: true) ou já foi respondido.

GET/api/v1/vendor/intelligence/sessions/{id}/selection/{selectionId}Seller

Ler o estado de uma lista de opções

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso de um seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id da sessão.
selectionIdstringobrigatório
Id da lista.

Exemplo de requisição

Resposta

200Estado da lista

Campos da resposta

statusstring
pendingansweredexpired
Estado da lista.
interactiveboolean
true só quando status é pending. Só então candidates vem preenchido.
destructiveboolean
A ação que vai retomar é destrutiva.
action_labelstring
Nome da ação em espera.
slotsarray
Posições: key, entity, label, query, multi, total_found, page_size, candidates, chosen.
chosenobject
Escolhas já feitas, por posição.
created_atstring
RFC 3339.
expires_atstring
RFC 3339. Depois disso a lista deixa de aceitar resposta.
answered_atstring
RFC 3339. Só em listas respondidas.

Erros

StatusQuandoCorpo
401Sem token ou token inválido/expirado.{"error":"missing authorization header"} ou {"error":"invalid or expired token"}
403O token não é de um usuário seller (por exemplo, é de um administrador da loja).{"error":"insufficient permissions"}
404Conversa ou lista de opções inexistente (os dois casos são indistinguíveis de propósito).{"error":"não encontrei essa lista de opções..."} (devolvido em português)

Veja também

  • Mensagens
Anterior
Anexos e exportação
Próxima
Pedido montado na conversa
Nesta página
  • Responder a uma lista
  • Exemplo de requisição
  • Resposta
  • Erros
  • Buscar dentro da lista
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ler o estado da lista
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também
bash
curl -X POST "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID/selection" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selection_id": "sel_01",
    "choices": {
      "produto": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d"
    }
  }'
bash
curl -X POST "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID/selection/search" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selection_id": "sel_01",
    "slot": "produto",
    "query": "mouse",
    "offset": 6
  }'
bash
curl "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID/selection/$SELECTION_ID" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "status": "answered",
  "messages": [
    { "role": "assistant", "content": "Preço do Mouse Gamer atualizado.", "created_at": "2026-10-11T21:10:00Z" }
  ],
  "selection": {
    "selection_id": "sel_01",
    "status": "answered",
    "chosen": { "produto": { "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d", "label": "Mouse Gamer Titan" } }
  },
  "requires_approval": false
}
json
{
  "slot": "produto",
  "query": "mouse",
  "offset": 6,
  "page_size": 6,
  "candidates": [
    { "id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d", "label": "Mouse Gamer Titan", "sublabel": "SKU MG-01", "score": 0.91 }
  ],
  "total_found": 7
}
json
{
  "selection_id": "sel_01",
  "session_id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
  "status": "pending",
  "interactive": true,
  "destructive": false,
  "slots": [
    { "key": "produto", "entity": "product", "query": "mouse", "multi": false, "total_found": 7, "page_size": 6, "candidates": [] }
  ],
  "created_at": "2026-10-11T21:09:00Z",
  "expires_at": "2026-10-11T22:09:00Z"
}