API atual/Referência completa/Venddor Intelligence

Tela atual e trechos

Informa à VI em que tela do painel o seller está e recolhe trechos interativos já usados.

Quando o seller pergunta "o que é este campo?" ou "edite este produto", a VI precisa saber onde ele está. Você envia a estrutura da tela (títulos, rótulos de campos, colunas, botões), nunca os valores digitados. Dados pessoais (e-mail, telefone, CPF, CNPJ) são removidos no servidor antes de qualquer uso.

Informar a tela atual

Grava a tela atual na sessão (chave page do contexto). Chame sempre que o seller mudar de tela. Um corpo vazio limpa o contexto, o que é o comportamento certo quando o painel lateral é fechado.

PUT/api/v1/vendor/intelligence/sessions/{id}/page-contextSeller

Informar a tela atual

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

urlstring

Caminho da tela, como /vendor/products/abc-123.

entity_kindstring

productordercustomervendor

Tipo do registro aberto. Outro valor descarta entity_kind, entity_id e entity_label.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro (nunca e-mail, telefone ou documento).

titlestring

Título da página.

headingsarray

Títulos de seção visíveis. Lista de strings. Máximo de 14 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

fieldsarray

Rótulos dos campos do formulário, sem valores. Máximo de 35 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

table_columnsarray

Cabeçalhos das colunas das tabelas. Máximo de 24 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

actionsarray

Botões e links de ação principais. Máximo de 16 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

metricsarray

Valores de indicadores visíveis, em texto (Receita: R$ 15.116,00). Máximo de 16 itens; itens repetidos são ignorados e cada item é cortado em 220 caracteres.

tabsarray

Abas da tela. Máximo de 20 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID/page-context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/vendor/products",
    "title": "Produtos",
    "table_columns": [
      "Nome",
      "Preço",
      "Estoque"
    ]
  }'

Resposta

200Gravado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`

Recolher um trecho

Algumas respostas da VI trazem um trecho interativo (por exemplo, um formulário de cadastro aberto dentro da conversa). Depois que o seller salva dentro dele, esta rota reescreve a mensagem gravada para que o trecho apareça recolhido quando a conversa for reaberta.

POST/api/v1/vendor/intelligence/sessions/{id}/snippets/{snippetId}/closeSeller

Recolher um trecho interativo

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.

snippetIdstringobrigatório

Identificador do trecho, o mesmo que veio no bloco da mensagem.

Corpo da requisição

actionstring

O que o seller fez no trecho (por exemplo saved). Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID/snippets/$SNIPPET_ID/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "saved"
  }'

Resposta

200Recolhido

json

{ "ok": true }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
500	Trecho não encontrado na conversa ou falha ao reescrever (a rota não distingue os casos).	`{"error":"could not close snippet"}`

Veja também

Tela atual e trechos

Informa à VI em que tela do painel o seller está e recolhe trechos interativos já usados.

Informar a tela atual

PUT/api/v1/vendor/intelligence/sessions/{id}/page-contextSeller

Informar a tela atual

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

urlstring

Caminho da tela, como /vendor/products/abc-123.

entity_kindstring

productordercustomervendor

Tipo do registro aberto. Outro valor descarta entity_kind, entity_id e entity_label.

entity_idstring

Id do registro aberto.

entity_labelstring

Nome legível do registro (nunca e-mail, telefone ou documento).

titlestring

Título da página.

headingsarray

Títulos de seção visíveis. Lista de strings. Máximo de 14 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

fieldsarray

Rótulos dos campos do formulário, sem valores. Máximo de 35 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

table_columnsarray

Cabeçalhos das colunas das tabelas. Máximo de 24 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

actionsarray

Botões e links de ação principais. Máximo de 16 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

metricsarray

Valores de indicadores visíveis, em texto (Receita: R$ 15.116,00). Máximo de 16 itens; itens repetidos são ignorados e cada item é cortado em 220 caracteres.

tabsarray

Abas da tela. Máximo de 20 itens; itens repetidos são ignorados e cada item é cortado em 80 caracteres.

active_tabstring

Aba aberta.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID/page-context" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "/vendor/products",
    "title": "Produtos",
    "table_columns": [
      "Nome",
      "Preço",
      "Estoque"
    ]
  }'

Resposta

200Gravado

json

{ "status": "ok" }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body"}`

Recolher um trecho

POST/api/v1/vendor/intelligence/sessions/{id}/snippets/{snippetId}/closeSeller

Recolher um trecho interativo

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.

snippetIdstringobrigatório

Identificador do trecho, o mesmo que veio no bloco da mensagem.

Corpo da requisição

actionstring

O que o seller fez no trecho (por exemplo saved). Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID/snippets/$SNIPPET_ID/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "saved"
  }'

Resposta

200Recolhido

json

{ "ok": true }

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O token não é de um usuário seller (por exemplo, é de um administrador da loja).	`{"error":"insufficient permissions"}`
500	Trecho não encontrado na conversa ou falha ao reescrever (a rota não distingue os casos).	`{"error":"could not close snippet"}`