API atual/Referência completa/Venddor Intelligence na vitrine

Cartões de escolha

Envia a escolha do cliente em um cartão do assistente, busca dentro dele e lê o seu estado.

Às vezes o assistente não pode adivinhar: "adicione a camiseta" pode ser dez camisetas. Nesse caso ele mostra um cartão de escolha com as opções, o cliente clica e o assistente continua. Na resposta de Conversar o cartão vem como um bloco de código Markdown com linguagem sf:choice, cujo conteúdo é um JSON.

json

{
  "selection_id": "sel_01",
  "session_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "title": "Qual camiseta?",
  "submit_label": "Adicionar",
  "destructive": false,
  "slots": [
    {
      "key": "produto",
      "entity": "product",
      "label": "Camiseta",
      "query": "camiseta",
      "multi": false,
      "total_found": 12,
      "page_size": 6,
      "candidates": [
        { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul", "sublabel": "R$ 59,90", "score": 0.92 }
      ],
      "chosen": null
    }
  ]
}

Os campos principais: selection_id (use nas três rotas), status (pending aceita clique; answered e expired não), slots (as listas de escolha, cada uma com key, multi e candidates de id, label e sublabel).

Enviar a escolha

POST/api/v1/storefront/intelligence/sessions/{id}/selectionAutenticada

Envia a escolha de um cartão

Registra o que o cliente escolheu em um cartão. A escolha é conferida contra as opções que o cartão ofereceu: um id forjado ou antigo é recusado. A resposta traz as mensagens geradas pelo passo seguinte (a ação executada).

Parâmetros de caminho

iduuidobrigatório

O session_id da conversa que mostrou o cartão.

Corpo da requisição

selection_idstringobrigatório

Id do cartão, o campo selection_id do bloco sf:choice.

choicesobject

Escolha de uma opção por lista: a chave é o key da lista (slots[].key) e o valor é o id do candidato escolhido.

multi_choicesobject

Para listas de escolha múltipla (multi: true): a chave é o key da lista e o valor é um array de ids.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/sessions/11111111-1111-4111-8111-111111111111/selection" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "selection_id": "sel_01",
  "choices": {
    "produto": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"
  }
}'

Resposta

200Escolha aplicada

json

{
  "status": "answered",
  "messages": [
    {
      "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
      "role": "assistant",
      "content": "Pronto: adicionei a Camiseta Básica Azul ao carrinho.",
      "created_at": "2026-10-11T14:03:02Z"
    }
  ],
  "selection": {
    "selection_id": "sel_01",
    "status": "answered",
    "chosen": { "produto": { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul" } }
  },
  "requires_approval": false
}

Campos da resposta

statusstring

Estado do cartão depois do envio.

messagesobject[]

Mensagens geradas pelo passo seguinte, no formato id, role, content, created_at. Acrescente-as à conversa.

selectionobject

Resumo do cartão: selection_id, status, chosen (por lista) e chosen_multi.

requires_approvalboolean

true quando a ação é destrutiva e o assistente pede confirmação pelo chat antes de executar. Responda por Conversar.

approval_tokenstring

Presente só quando requires_approval é true. Apenas carregue-o; a confirmação do chat o consome.

continue_in_chatstring

Quando presente, envie este texto como a próxima mensagem de Conversar em vez de mostrar uma resposta pronta.

duplicateboolean

Presente (true) só na resposta 409 de um reenvio.

Erros

Status	Quando	Corpo
400	Corpo inválido, escolha incompleta, lista que não faz parte do cartão, id que não estava entre as opções ou escolhas demais.	`{"error":"escolha incompleta"}`
404	Conversa ou cartão inexistentes, ou de outro cliente.	`{"error":"não encontrei essa lista de opções..."}`
409	Cartão já respondido (reenvio): traz `duplicate` e o resultado da primeira vez. Também: cartão expirado, ação recusada ou retomada impossível.	`{"error":"...","status":"answered","duplicate":true}`
502	A ação escolhida falhou ao ser aplicada.	`{"error":"não consegui aplicar a ação agora..."}`
500	Falha inesperada ao processar a escolha.	`{"error":"não consegui processar a escolha agora"}`
503	Assistente indisponível na plataforma.	`{"error":"assistente indisponível"}`

Os textos das respostas 404, 409 e 500 das rotas do card seguem o idioma do cliente (português, inglês ou espanhol); os demais saem em português.

Buscar dentro do cartão

POST/api/v1/storefront/intelligence/sessions/{id}/selection/searchAutenticada

Busca dentro de uma lista do cartão

Quando as opções iniciais do cartão não incluem o que o cliente quer, ele digita para buscar mais. A busca vale só dentro da lista indicada e devolve uma página de candidatos.

Parâmetros de caminho

iduuidobrigatório

O session_id da conversa.

Corpo da requisição

selection_idstringobrigatório

Id do cartão.

slotstringobrigatório

O key da lista em que buscar.

querystringobrigatório

Texto digitado pelo cliente.

offsetintegerpadrão: 0

Quantos resultados pular, para a próxima página.

limitinteger

Tamanho da página. O servidor limita a um máximo.

orderstring

Ordenação sugerida pelos chips do cartão. Copie do cartão; não invente.

include_inactiveboolean

Inclui registros inativos ou vencidos. Só por escolha do cliente num chip.

filtersobject[]

Filtros vindos dos chips de refinamento do cartão (facets). Copie do cartão; filtros desconhecidos são ignorados.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/sessions/11111111-1111-4111-8111-111111111111/selection/search" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "selection_id": "sel_01",
  "slot": "produto",
  "query": "azul"
}'

Resposta

200Página de candidatos

json

{
  "slot": "produto",
  "query": "azul",
  "offset": 0,
  "page_size": 6,
  "candidates": [
    { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul", "sublabel": "R$ 59,90", "score": 0.92 }
  ],
  "total_found": 1
}

Campos da resposta

slotstring

A lista pesquisada.

querystring

O texto buscado.

offsetinteger

Posição inicial desta página.

page_sizeinteger

Tamanho da página.

candidatesobject[]

Opções: id, label, sublabel, thumb (imagem, opcional), score.

total_foundinteger

Total de resultados da busca.

empty_hintstring

Frase para mostrar no lugar da grade quando nada foi encontrado.

facetsobject[]

Chips de refinamento (key, label, options) que o cartão pode oferecer. Cada opção traz o filtro pronto para devolver em filters.

Erros

Status	Quando	Corpo
400	Corpo inválido, lista desconhecida ou consulta vazia.	`{"error":"..."}`
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
404	Conversa ou cartão inexistentes, ou de outro cliente.	`{"error":"não encontrei essa lista de opções..."}`
429	Já há uma busca em andamento neste cartão.	`{"error":"uma busca já está em andamento..."}`

Ler o estado do cartão

GET/api/v1/storefront/intelligence/sessions/{id}/selection/{selectionId}Autenticada

Estado atual de um cartão

Devolve o estado atual do cartão. Use ao reabrir a página: o servidor diz se ele ainda aceita clique (interactive) ou já foi respondido.

Parâmetros de caminho

iduuidobrigatório

O session_id da conversa.

selectionIdstringobrigatório

Id do cartão.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/intelligence/sessions/11111111-1111-4111-8111-111111111111/selection/sel_01" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Estado do cartão

json

{
  "selection_id": "sel_01",
  "session_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "interactive": true,
  "destructive": false,
  "slots": [
    {
      "key": "produto",
      "entity": "product",
      "query": "camiseta",
      "multi": false,
      "total_found": 12,
      "page_size": 6,
      "candidates": [
        { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul", "score": 0.92 }
      ]
    }
  ]
}

Campos da resposta

selection_idstring

Id do cartão.

session_iduuid

Conversa do cartão.

statusstring

pending, answered ou expired.

interactiveboolean

true quando o servidor ainda aceita a escolha (status é pending). Combine com "é a última mensagem?" do seu front-end para decidir se o cartão é clicável.

destructiveboolean

A ação do cartão é destrutiva e pede confirmação.

slotsobject[]

As listas, com candidates e, depois de respondido, chosen.

chosenobject

Escolhas feitas, por lista. Presente depois de respondido.

Erros

Status	Quando	Corpo
404	Conversa ou cartão inexistentes, ou de outro cliente.	`{"error":"não encontrei essa lista de opções..."}`
409	Cartão expirado.	`{"error":"...","status":"expired"}`

Veja também

API atual/Referência completa/Venddor Intelligence na vitrine

Cartões de escolha

Envia a escolha do cliente em um cartão do assistente, busca dentro dele e lê o seu estado.

json

{
  "selection_id": "sel_01",
  "session_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "title": "Qual camiseta?",
  "submit_label": "Adicionar",
  "destructive": false,
  "slots": [
    {
      "key": "produto",
      "entity": "product",
      "label": "Camiseta",
      "query": "camiseta",
      "multi": false,
      "total_found": 12,
      "page_size": 6,
      "candidates": [
        { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul", "sublabel": "R$ 59,90", "score": 0.92 }
      ],
      "chosen": null
    }
  ]
}

Enviar a escolha

POST/api/v1/storefront/intelligence/sessions/{id}/selectionAutenticada

Envia a escolha de um cartão

Parâmetros de caminho

iduuidobrigatório

O session_id da conversa que mostrou o cartão.

Corpo da requisição

selection_idstringobrigatório

Id do cartão, o campo selection_id do bloco sf:choice.

choicesobject

Escolha de uma opção por lista: a chave é o key da lista (slots[].key) e o valor é o id do candidato escolhido.

multi_choicesobject

Para listas de escolha múltipla (multi: true): a chave é o key da lista e o valor é um array de ids.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/sessions/11111111-1111-4111-8111-111111111111/selection" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "selection_id": "sel_01",
  "choices": {
    "produto": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766"
  }
}'

Resposta

200Escolha aplicada

json

{
  "status": "answered",
  "messages": [
    {
      "id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
      "role": "assistant",
      "content": "Pronto: adicionei a Camiseta Básica Azul ao carrinho.",
      "created_at": "2026-10-11T14:03:02Z"
    }
  ],
  "selection": {
    "selection_id": "sel_01",
    "status": "answered",
    "chosen": { "produto": { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul" } }
  },
  "requires_approval": false
}

Campos da resposta

statusstring

Estado do cartão depois do envio.

messagesobject[]

Mensagens geradas pelo passo seguinte, no formato id, role, content, created_at. Acrescente-as à conversa.

selectionobject

Resumo do cartão: selection_id, status, chosen (por lista) e chosen_multi.

requires_approvalboolean

true quando a ação é destrutiva e o assistente pede confirmação pelo chat antes de executar. Responda por Conversar.

approval_tokenstring

Presente só quando requires_approval é true. Apenas carregue-o; a confirmação do chat o consome.

continue_in_chatstring

Quando presente, envie este texto como a próxima mensagem de Conversar em vez de mostrar uma resposta pronta.

duplicateboolean

Presente (true) só na resposta 409 de um reenvio.

Erros

Status	Quando	Corpo
400	Corpo inválido, escolha incompleta, lista que não faz parte do cartão, id que não estava entre as opções ou escolhas demais.	`{"error":"escolha incompleta"}`
404	Conversa ou cartão inexistentes, ou de outro cliente.	`{"error":"não encontrei essa lista de opções..."}`
409	Cartão já respondido (reenvio): traz `duplicate` e o resultado da primeira vez. Também: cartão expirado, ação recusada ou retomada impossível.	`{"error":"...","status":"answered","duplicate":true}`
502	A ação escolhida falhou ao ser aplicada.	`{"error":"não consegui aplicar a ação agora..."}`
500	Falha inesperada ao processar a escolha.	`{"error":"não consegui processar a escolha agora"}`
503	Assistente indisponível na plataforma.	`{"error":"assistente indisponível"}`

Os textos das respostas 404, 409 e 500 das rotas do card seguem o idioma do cliente (português, inglês ou espanhol); os demais saem em português.

Buscar dentro do cartão

POST/api/v1/storefront/intelligence/sessions/{id}/selection/searchAutenticada

Busca dentro de uma lista do cartão

Quando as opções iniciais do cartão não incluem o que o cliente quer, ele digita para buscar mais. A busca vale só dentro da lista indicada e devolve uma página de candidatos.

Parâmetros de caminho

iduuidobrigatório

O session_id da conversa.

Corpo da requisição

selection_idstringobrigatório

Id do cartão.

slotstringobrigatório

O key da lista em que buscar.

querystringobrigatório

Texto digitado pelo cliente.

offsetintegerpadrão: 0

Quantos resultados pular, para a próxima página.

limitinteger

Tamanho da página. O servidor limita a um máximo.

orderstring

Ordenação sugerida pelos chips do cartão. Copie do cartão; não invente.

include_inactiveboolean

Inclui registros inativos ou vencidos. Só por escolha do cliente num chip.

filtersobject[]

Filtros vindos dos chips de refinamento do cartão (facets). Copie do cartão; filtros desconhecidos são ignorados.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/storefront/intelligence/sessions/11111111-1111-4111-8111-111111111111/selection/search" \
  -H "X-Session-ID: $SESSION_ID" \
  -H "Content-Type: application/json" \
  -d '{
  "selection_id": "sel_01",
  "slot": "produto",
  "query": "azul"
}'

Resposta

200Página de candidatos

json

{
  "slot": "produto",
  "query": "azul",
  "offset": 0,
  "page_size": 6,
  "candidates": [
    { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul", "sublabel": "R$ 59,90", "score": 0.92 }
  ],
  "total_found": 1
}

Campos da resposta

slotstring

A lista pesquisada.

querystring

O texto buscado.

offsetinteger

Posição inicial desta página.

page_sizeinteger

Tamanho da página.

candidatesobject[]

Opções: id, label, sublabel, thumb (imagem, opcional), score.

total_foundinteger

Total de resultados da busca.

empty_hintstring

Frase para mostrar no lugar da grade quando nada foi encontrado.

facetsobject[]

Chips de refinamento (key, label, options) que o cartão pode oferecer. Cada opção traz o filtro pronto para devolver em filters.

Erros

Status	Quando	Corpo
400	Corpo inválido, lista desconhecida ou consulta vazia.	`{"error":"..."}`
401	Loja que exige login para navegar e chamada sem token.	`{"error":"shopping_requires_login","message":"this storefront requires login to browse"}`
404	Conversa ou cartão inexistentes, ou de outro cliente.	`{"error":"não encontrei essa lista de opções..."}`
429	Já há uma busca em andamento neste cartão.	`{"error":"uma busca já está em andamento..."}`

Ler o estado do cartão

GET/api/v1/storefront/intelligence/sessions/{id}/selection/{selectionId}Autenticada

Estado atual de um cartão

Devolve o estado atual do cartão. Use ao reabrir a página: o servidor diz se ele ainda aceita clique (interactive) ou já foi respondido.

Parâmetros de caminho

iduuidobrigatório

O session_id da conversa.

selectionIdstringobrigatório

Id do cartão.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/storefront/intelligence/sessions/11111111-1111-4111-8111-111111111111/selection/sel_01" \
  -H "X-Session-ID: $SESSION_ID"

Resposta

200Estado do cartão

json

{
  "selection_id": "sel_01",
  "session_id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "interactive": true,
  "destructive": false,
  "slots": [
    {
      "key": "produto",
      "entity": "product",
      "query": "camiseta",
      "multi": false,
      "total_found": 12,
      "page_size": 6,
      "candidates": [
        { "id": "22fbd12a-1b6e-41ea-a84f-4d9cf06c8766", "label": "Camiseta Básica Azul", "score": 0.92 }
      ]
    }
  ]
}

Campos da resposta

selection_idstring

Id do cartão.

session_iduuid

Conversa do cartão.

statusstring

pending, answered ou expired.

interactiveboolean

true quando o servidor ainda aceita a escolha (status é pending). Combine com "é a última mensagem?" do seu front-end para decidir se o cartão é clicável.

destructiveboolean

A ação do cartão é destrutiva e pede confirmação.

slotsobject[]

As listas, com candidates e, depois de respondido, chosen.

chosenobject

Escolhas feitas, por lista. Presente depois de respondido.

Erros

Status	Quando	Corpo
404	Conversa ou cartão inexistentes, ou de outro cliente.	`{"error":"não encontrei essa lista de opções..."}`
409	Cartão expirado.	`{"error":"...","status":"expired"}`