API atual/Referência completa/Venddor Intelligence

Sessões de conversa

Abre, lista, busca, lê e arquiva as conversas do seller com a Venddor Intelligence.

Uma sessão é uma conversa: um título, o contexto da tela e a lista de mensagens. Você cria a sessão antes da primeira mensagem e a reutiliza enquanto o assunto for o mesmo. Arquivar tira a conversa da lista, mas não apaga as mensagens. Todas as sessões pertencem ao usuário do token; as respostas da VI nelas só falam do seu seller, nunca do marketplace inteiro.

Abrir uma conversa

Cria uma sessão ativa para o seller do token. O corpo é opcional: sem corpo, a sessão nasce sem título.

POST/api/v1/vendor/intelligence/sessionsSeller

Abrir uma conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

titlestring

Título da conversa. Opcional.

contextobject

Contexto livre, gravado como está. Opcional.

page_contextobject

Tela atual, no formato de Tela atual. Quando enviado, vence o campo page de context. Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Promoções de outubro"
  }'

Resposta

201Sessão criada

json

{
  "id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "title": "Promoções de outubro",
  "context": {},
  "state": "active",
  "started_at": "2026-10-11T21:07:28.629207Z",
  "message_count": 0,
  "created_at": "2026-10-11T21:07:28.629207Z",
  "updated_at": "2026-10-11T21:07:28.629207Z"
}

Campos da resposta

iduuid

Id da sessão.

user_iduuid

Seller dono da conversa.

titlestring

Título. Vazio se nunca foi definido; na listagem, quando vazio, vem o início da primeira mensagem do usuário (até 60 caracteres).

contextobject

Contexto livre da sessão. Contém page quando a tela atual foi informada (Tela atual).

statestring

activearchived

Estado da sessão.

started_atstring

RFC 3339. Início da conversa.

last_message_atstring

RFC 3339. Última mensagem. Ausente se ainda não houve mensagens.

message_countinteger

Quantidade de mensagens gravadas.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

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

Listar conversas

Devolve as conversas ativas do seller do token, da mais recente para a mais antiga. Entram só conversas em que o usuário escreveu pelo menos uma mensagem: sessões abertas e nunca usadas não aparecem.

GET/api/v1/vendor/intelligence/sessionsSeller

Listar as conversas de quem chama

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade máxima. Padrão 50, teto 200. Valores inválidos ou menores que 1 caem no padrão.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/sessions?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Lista de sessões

json

{
  "sessions": [
    {
      "id": "a74d1e78-338a-4fe4-80be-660daa47296a",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "title": "Promoções de outubro",
      "context": {},
      "state": "active",
      "started_at": "2026-10-11T21:07:28.629207Z",
      "message_count": 4,
      "created_at": "2026-10-11T21:07:28.629207Z",
      "updated_at": "2026-10-11T21:07:28.629207Z"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Sessões, no formato do objeto de sessão acima.

totalinteger

Quantidade devolvida nesta resposta (não é o total geral).

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

Buscar conversas

Procura um trecho de texto em qualquer mensagem (do usuário ou da VI) das conversas ativas do seller do token. A busca ignora maiúsculas e minúsculas e acha o trecho em qualquer posição.

GET/api/v1/vendor/intelligence/sessions/searchSeller

Buscar conversas pelo texto das mensagens

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

qstringobrigatório

Texto procurado. Vazio devolve lista vazia.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/sessions/search?q=promoções" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversas encontradas

json

{
  "sessions": [
    {
      "id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
      "title": "teste lote por filtro",
      "message_count": 2,
      "last_message_at": "2026-09-15T19:56:29.111469Z",
      "preview": "Montei o lote para adicionar a condição de subtotal mínimo..."
    }
  ],
  "total": 1
}

Campos da resposta

sessions[].iduuid

Id da sessão.

sessions[].titlestring

Título, ou o início da primeira mensagem do usuário.

sessions[].message_countinteger

Mensagens na sessão.

sessions[].last_message_atstring

RFC 3339. Pode ser nulo.

sessions[].previewstring

Até 180 caracteres a partir da primeira mensagem que contém o texto.

totalinteger

Quantidade devolvida. No máximo 30.

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

Ler uma conversa

Devolve os dados de uma sessão (sem as mensagens, que ficam em Mensagens). Funciona também para sessões arquivadas.

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

Ler uma conversa

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sessão

json

{
  "id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "title": "Promoções de outubro",
  "context": {},
  "state": "active",
  "started_at": "2026-10-11T21:07:28.629207Z",
  "message_count": 0,
  "created_at": "2026-10-11T21:07:28.629207Z",
  "updated_at": "2026-10-11T21:07:28.629207Z"
}

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"}`
404	Sessão inexistente.	`{"error":"session not found"}`
500	O `id` não é um UUID válido (a plataforma responde 500 em vez de 400).	`{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}` (devolvido em português)

Arquivar uma conversa

Muda o estado da sessão para archived. Não há corpo e não há rota para desarquivar: para continuar o assunto, abra uma nova sessão.

PATCH/api/v1/vendor/intelligence/sessions/{id}Seller

Arquivar uma conversa

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivada

json

{ "state": "archived" }

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	O `id` não é um UUID válido (a plataforma responde 500 em vez de 400).	`{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}` (devolvido em português)

Veja também

API atual/Referência completa/Venddor Intelligence

Sessões de conversa

Abre, lista, busca, lê e arquiva as conversas do seller com a Venddor Intelligence.

Abrir uma conversa

Cria uma sessão ativa para o seller do token. O corpo é opcional: sem corpo, a sessão nasce sem título.

POST/api/v1/vendor/intelligence/sessionsSeller

Abrir uma conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

titlestring

Título da conversa. Opcional.

contextobject

Contexto livre, gravado como está. Opcional.

page_contextobject

Tela atual, no formato de Tela atual. Quando enviado, vence o campo page de context. Opcional.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/intelligence/sessions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Promoções de outubro"
  }'

Resposta

201Sessão criada

json

{
  "id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "title": "Promoções de outubro",
  "context": {},
  "state": "active",
  "started_at": "2026-10-11T21:07:28.629207Z",
  "message_count": 0,
  "created_at": "2026-10-11T21:07:28.629207Z",
  "updated_at": "2026-10-11T21:07:28.629207Z"
}

Campos da resposta

iduuid

Id da sessão.

user_iduuid

Seller dono da conversa.

titlestring

Título. Vazio se nunca foi definido; na listagem, quando vazio, vem o início da primeira mensagem do usuário (até 60 caracteres).

contextobject

Contexto livre da sessão. Contém page quando a tela atual foi informada (Tela atual).

statestring

activearchived

Estado da sessão.

started_atstring

RFC 3339. Início da conversa.

last_message_atstring

RFC 3339. Última mensagem. Ausente se ainda não houve mensagens.

message_countinteger

Quantidade de mensagens gravadas.

created_atstring

RFC 3339.

updated_atstring

RFC 3339.

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

Listar conversas

GET/api/v1/vendor/intelligence/sessionsSeller

Listar as conversas de quem chama

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

limitintegerpadrão: 50

Quantidade máxima. Padrão 50, teto 200. Valores inválidos ou menores que 1 caem no padrão.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/sessions?limit=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Lista de sessões

json

{
  "sessions": [
    {
      "id": "a74d1e78-338a-4fe4-80be-660daa47296a",
      "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
      "title": "Promoções de outubro",
      "context": {},
      "state": "active",
      "started_at": "2026-10-11T21:07:28.629207Z",
      "message_count": 4,
      "created_at": "2026-10-11T21:07:28.629207Z",
      "updated_at": "2026-10-11T21:07:28.629207Z"
    }
  ],
  "total": 1
}

Campos da resposta

sessionsarray

Sessões, no formato do objeto de sessão acima.

totalinteger

Quantidade devolvida nesta resposta (não é o total geral).

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

Buscar conversas

Procura um trecho de texto em qualquer mensagem (do usuário ou da VI) das conversas ativas do seller do token. A busca ignora maiúsculas e minúsculas e acha o trecho em qualquer posição.

GET/api/v1/vendor/intelligence/sessions/searchSeller

Buscar conversas pelo texto das mensagens

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

qstringobrigatório

Texto procurado. Vazio devolve lista vazia.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/sessions/search?q=promoções" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Conversas encontradas

json

{
  "sessions": [
    {
      "id": "a0cb371d-96ba-4406-afa1-057ba2594bb6",
      "title": "teste lote por filtro",
      "message_count": 2,
      "last_message_at": "2026-09-15T19:56:29.111469Z",
      "preview": "Montei o lote para adicionar a condição de subtotal mínimo..."
    }
  ],
  "total": 1
}

Campos da resposta

sessions[].iduuid

Id da sessão.

sessions[].titlestring

Título, ou o início da primeira mensagem do usuário.

sessions[].message_countinteger

Mensagens na sessão.

sessions[].last_message_atstring

RFC 3339. Pode ser nulo.

sessions[].previewstring

Até 180 caracteres a partir da primeira mensagem que contém o texto.

totalinteger

Quantidade devolvida. No máximo 30.

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

Ler uma conversa

Devolve os dados de uma sessão (sem as mensagens, que ficam em Mensagens). Funciona também para sessões arquivadas.

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

Ler uma conversa

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sessão

json

{
  "id": "a74d1e78-338a-4fe4-80be-660daa47296a",
  "user_id": "d4613dde-ac7a-431c-9232-50d8cd6ad5fc",
  "title": "Promoções de outubro",
  "context": {},
  "state": "active",
  "started_at": "2026-10-11T21:07:28.629207Z",
  "message_count": 0,
  "created_at": "2026-10-11T21:07:28.629207Z",
  "updated_at": "2026-10-11T21:07:28.629207Z"
}

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"}`
404	Sessão inexistente.	`{"error":"session not found"}`
500	O `id` não é um UUID válido (a plataforma responde 500 em vez de 400).	`{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}` (devolvido em português)

Arquivar uma conversa

Muda o estado da sessão para archived. Não há corpo e não há rota para desarquivar: para continuar o assunto, abra uma nova sessão.

PATCH/api/v1/vendor/intelligence/sessions/{id}Seller

Arquivar uma conversa

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/intelligence/sessions/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Arquivada

json

{ "state": "archived" }

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	O `id` não é um UUID válido (a plataforma responde 500 em vez de 400).	`{"error":"o valor \"abc\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie."}` (devolvido em português)