API atual/Referência completa/Venddor Intelligence: conversas

Confirmar ações da VI

Lista as ações que a VI executou ou deixou de executar e confirma ou recusa uma ação pendente.

É a trava de segurança da VI. Quando ela quer alterar algo, propõe e espera. A alteração só acontece quando um administrador chama POST /agent-actions/confirm com o token do bloco vi:confirm. A ação executada é exatamente a que foi mostrada, com as credenciais de quem clicou. GET /agent-actions é o registro: toda alteração (nunca as leituras) fica lá, executada ou não.

Listar ações

Devolve a auditoria das alterações pedidas à VI, da mais recente para a mais antiga. São duas abas: as executadas e as não executadas (recusadas pelo administrador, recusadas pela API ou sem credencial). A lista cobre a loja inteira, não só o usuário do token.

GET/api/v1/admin/intelligence/agent-actionsAdmin

Listar ações executadas e não executadas

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

statusstringpadrão: E

EN

Aba. Qualquer valor diferente de N devolve as executadas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página. Padrão 50; valores acima de 200 ou abaixo de 1 voltam para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/agent-actions?status=N&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ações

json

{
  "items": [
    {
      "id": "8c5557c3-c732-4b2a-b118-06e698145008",
      "user_id": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "user_name": "Maria Souza",
      "session_id": "70f59718-3e64-4702-8cb9-379e0918e0bf",
      "status": "N",
      "action_type": "U",
      "description": "Ativar idioma inglês na loja",
      "method": "PUT",
      "path": "/settings",
      "http_status": 400,
      "reason": "a API recusou (HTTP 400)",
      "created_at": "2026-09-29T17:04:57.711804Z"
    }
  ],
  "total": 573
}

Campos da resposta

items[].iduuid

Id do registro de auditoria.

items[].user_iduuid

Administrador que pediu a ação.

items[].user_namestring

Nome do administrador. Vazio se o usuário foi excluído.

items[].session_iduuid

Conversa em que a ação nasceu.

items[].statusstring

EN

E executada, N não executada.

items[].action_typestring

UD

U alteração (POST, PUT, PATCH) ou D exclusão (DELETE).

items[].descriptionstring

Frase da VI sobre o que a ação faria. Texto de modelo: confira com method e path.

items[].methodstring

Método HTTP da chamada feita ao painel.

items[].pathstring

Caminho da chamada, relativo à API de administração.

items[].http_statusinteger

Status devolvido pela API. Ausente se a chamada nem saiu.

items[].reasonstring

Por que não foi executada (só em N).

items[].created_atstring

RFC 3339.

totalinteger

Total de linhas da aba escolhida (não só desta página).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`

Confirmar ou recusar

Responde ao bloco vi:confirm. Com approved: true, executa a ação pendente usando o token de acesso desta chamada (portanto, com as permissões de quem clicou). Com approved: false, descarta a ação e registra "não confirmada". A rota responde sempre 200 quando o corpo é válido: o resultado está no campo status do JSON.

POST/api/v1/admin/intelligence/agent-actions/confirmAdmin

Confirmar ou recusar uma ação

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

tokenstringobrigatório

Token do bloco vi:confirm.

approvedbooleanobrigatório

true executa, false descarta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/agent-actions/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "83a02587a9546e662ecac4df02acc928",
    "approved": true
  }'

Resposta

200Ação executada

json

{
  "status": 200,
  "body": { "updated": 1 },
  "conversa": "Pronto, desativei a promoção."
}

200Recusada pelo administrador

json

{ "status": 200 }

200Token vencido ou já usado

json

{
  "status": 410,
  "error": "Não encontrei mais esta confirmação, então não executei nada e a loja está como estava. Me peça a ação de novo aqui na conversa que eu abro uma confirmação nova."
}

Campos da resposta

statusinteger

Resultado da ação: o status HTTP da chamada feita ao painel. 410 token vencido ou já usado; 401 sem credencial utilizável; 502 falha ao chamar o painel.

bodyobject

Corpo devolvido pela rota executada. Formato depende da ação.

errorstring

Motivo, em português, quando status não é de sucesso.

conversastring

Mensagem que o clique gravou na conversa. Mostre-a na hora para não depender de recarregar.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo que não é JSON (ou maior que 64 KB).	`{"error":"corpo inválido"}` (devolvido em português)
400	`token` vazio.	`{"error":"token obrigatório"}` (devolvido em português)

Veja também

API atual/Referência completa/Venddor Intelligence: conversas

Confirmar ações da VI

Lista as ações que a VI executou ou deixou de executar e confirma ou recusa uma ação pendente.

Listar ações

GET/api/v1/admin/intelligence/agent-actionsAdmin

Listar ações executadas e não executadas

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

statusstringpadrão: E

EN

Aba. Qualquer valor diferente de N devolve as executadas.

pageintegerpadrão: 1

Página, a partir de 1.

per_pageintegerpadrão: 50

Itens por página. Padrão 50; valores acima de 200 ou abaixo de 1 voltam para 50.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/agent-actions?status=N&per_page=20" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ações

json

{
  "items": [
    {
      "id": "8c5557c3-c732-4b2a-b118-06e698145008",
      "user_id": "67bf291c-0846-4053-9528-8cfd5ab0ebf1",
      "user_name": "Maria Souza",
      "session_id": "70f59718-3e64-4702-8cb9-379e0918e0bf",
      "status": "N",
      "action_type": "U",
      "description": "Ativar idioma inglês na loja",
      "method": "PUT",
      "path": "/settings",
      "http_status": 400,
      "reason": "a API recusou (HTTP 400)",
      "created_at": "2026-09-29T17:04:57.711804Z"
    }
  ],
  "total": 573
}

Campos da resposta

items[].iduuid

Id do registro de auditoria.

items[].user_iduuid

Administrador que pediu a ação.

items[].user_namestring

Nome do administrador. Vazio se o usuário foi excluído.

items[].session_iduuid

Conversa em que a ação nasceu.

items[].statusstring

EN

E executada, N não executada.

items[].action_typestring

UD

U alteração (POST, PUT, PATCH) ou D exclusão (DELETE).

items[].descriptionstring

Frase da VI sobre o que a ação faria. Texto de modelo: confira com method e path.

items[].methodstring

Método HTTP da chamada feita ao painel.

items[].pathstring

Caminho da chamada, relativo à API de administração.

items[].http_statusinteger

Status devolvido pela API. Ausente se a chamada nem saiu.

items[].reasonstring

Por que não foi executada (só em N).

items[].created_atstring

RFC 3339.

totalinteger

Total de linhas da aba escolhida (não só desta página).

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`

Confirmar ou recusar

POST/api/v1/admin/intelligence/agent-actions/confirmAdmin

Confirmar ou recusar uma ação

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

tokenstringobrigatório

Token do bloco vi:confirm.

approvedbooleanobrigatório

true executa, false descarta.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/agent-actions/confirm" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "83a02587a9546e662ecac4df02acc928",
    "approved": true
  }'

Resposta

200Ação executada

json

{
  "status": 200,
  "body": { "updated": 1 },
  "conversa": "Pronto, desativei a promoção."
}

200Recusada pelo administrador

json

{ "status": 200 }

200Token vencido ou já usado

json

{
  "status": 410,
  "error": "Não encontrei mais esta confirmação, então não executei nada e a loja está como estava. Me peça a ação de novo aqui na conversa que eu abro uma confirmação nova."
}

Campos da resposta

statusinteger

Resultado da ação: o status HTTP da chamada feita ao painel. 410 token vencido ou já usado; 401 sem credencial utilizável; 502 falha ao chamar o painel.

bodyobject

Corpo devolvido pela rota executada. Formato depende da ação.

errorstring

Motivo, em português, quando status não é de sucesso.

conversastring

Mensagem que o clique gravou na conversa. Mostre-a na hora para não depender de recarregar.

Erros

Status	Quando	Corpo
401	Sem token ou token inválido/expirado.	`{"error":"missing authorization header"}` ou `{"error":"invalid or expired token"}`
403	O administrador não tem nenhum dos privilégios exigidos.	`{"error":"insufficient privileges","privilege_required_any":["intelligence_use_chat","manage_settings"]}`
400	Corpo que não é JSON (ou maior que 64 KB).	`{"error":"corpo inválido"}` (devolvido em português)
400	`token` vazio.	`{"error":"token obrigatório"}` (devolvido em português)