API atual/Referência completa/Venddor Intelligence: insights e dicas

Analisar um registro

Devolve sugestões de melhoria para um produto, pedido ou cliente.

É a pergunta "o que dá para melhorar neste registro?" sem abrir uma conversa. A VI inspeciona o produto, o pedido ou o cliente e devolve sugestões: produto sem foto, sem descrição, com margem negativa ou estoque zerado; pedido parado; cliente que não compra há tempo. As sugestões vêm de regras fixas (source: rule) e, quando há previsões para o registro, de previsões (source: prediction).

Por URL (GET)

Aceita os dois parâmetros na URL. A versão POST abaixo faz o mesmo com os parâmetros no corpo JSON.

GET/api/v1/admin/intelligence/analyze-entityAdmin

Analisar um registro (GET)

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

entity_typestringobrigatório

productorderuser

Tipo do registro. Aceita também os apelidos products, produto, produtos, orders, pedido, pedidos, users, customer, customers, cliente, clientes.

entity_iduuidobrigatório

Id do registro.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/analyze-entity?entity_type=product&entity_id=7bc1d5e9-a9a4-457b-866f-bbb3879d258d" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sugestões

json

{
  "entity_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "entity_type": "product",
  "suggestions": [
    {
      "title": "Sem foto",
      "body": "Este produto não tem nenhuma imagem. Produtos sem foto convertem muito menos e perdem destaque nas vitrines.",
      "severity": "warning",
      "source": "rule"
    },
    {
      "title": "Sem SKU",
      "body": "Defina um SKU. Sem código interno fica difícil controlar estoque e integrar com ERP.",
      "severity": "info",
      "source": "rule"
    }
  ],
  "total": 2
}

Campos da resposta

entity_typestring

Tipo normalizado: product, order ou user. Vazio quando o tipo enviado não é reconhecido.

entity_idstring

Id recebido.

suggestionsarray

Sugestões. Podem vir vazias.

suggestions[].titlestring

Título curto.

suggestions[].bodystring

Explicação e o que fazer.

suggestions[].severitystring

Gravidade (por exemplo info ou warning).

suggestions[].sourcestring

ruleprediction

Origem da sugestão.

totalinteger

Quantidade de sugestões.

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","view_reports"]}`
400	`entity_type` ou `entity_id` ausente.	`{"error":"entity_type and entity_id are required"}`

Por corpo (POST)

Mesma análise, com os parâmetros no corpo JSON (ou, se faltarem no corpo, na URL).

POST/api/v1/admin/intelligence/analyze-entityAdmin

Analisar um registro (POST)

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

entity_typestringobrigatório

productorderuser

Tipo do registro, como no GET.

entity_iduuidobrigatório

Id do registro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/analyze-entity" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "order",
    "entity_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722"
  }'

Resposta

200Sugestões

json

{
  "entity_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "entity_type": "order",
  "suggestions": [],
  "total": 0
}

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","view_reports"]}`
400	Corpo ilegível, ou `entity_type`/`entity_id` ausente.	`{"error":"invalid request body"}` ou `{"error":"entity_type and entity_id are required"}`

Veja também

API atual/Referência completa/Venddor Intelligence: insights e dicas

Analisar um registro

Devolve sugestões de melhoria para um produto, pedido ou cliente.

Por URL (GET)

Aceita os dois parâmetros na URL. A versão POST abaixo faz o mesmo com os parâmetros no corpo JSON.

GET/api/v1/admin/intelligence/analyze-entityAdmin

Analisar um registro (GET)

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

entity_typestringobrigatório

productorderuser

Tipo do registro. Aceita também os apelidos products, produto, produtos, orders, pedido, pedidos, users, customer, customers, cliente, clientes.

entity_iduuidobrigatório

Id do registro.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/analyze-entity?entity_type=product&entity_id=7bc1d5e9-a9a4-457b-866f-bbb3879d258d" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Sugestões

json

{
  "entity_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
  "entity_type": "product",
  "suggestions": [
    {
      "title": "Sem foto",
      "body": "Este produto não tem nenhuma imagem. Produtos sem foto convertem muito menos e perdem destaque nas vitrines.",
      "severity": "warning",
      "source": "rule"
    },
    {
      "title": "Sem SKU",
      "body": "Defina um SKU. Sem código interno fica difícil controlar estoque e integrar com ERP.",
      "severity": "info",
      "source": "rule"
    }
  ],
  "total": 2
}

Campos da resposta

entity_typestring

Tipo normalizado: product, order ou user. Vazio quando o tipo enviado não é reconhecido.

entity_idstring

Id recebido.

suggestionsarray

Sugestões. Podem vir vazias.

suggestions[].titlestring

Título curto.

suggestions[].bodystring

Explicação e o que fazer.

suggestions[].severitystring

Gravidade (por exemplo info ou warning).

suggestions[].sourcestring

ruleprediction

Origem da sugestão.

totalinteger

Quantidade de sugestões.

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","view_reports"]}`
400	`entity_type` ou `entity_id` ausente.	`{"error":"entity_type and entity_id are required"}`

Por corpo (POST)

Mesma análise, com os parâmetros no corpo JSON (ou, se faltarem no corpo, na URL).

POST/api/v1/admin/intelligence/analyze-entityAdmin

Analisar um registro (POST)

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

entity_typestringobrigatório

productorderuser

Tipo do registro, como no GET.

entity_iduuidobrigatório

Id do registro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/analyze-entity" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_type": "order",
    "entity_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722"
  }'

Resposta

200Sugestões

json

{
  "entity_id": "a8a3c7a3-5f15-45a8-a385-4f20fbf8b722",
  "entity_type": "order",
  "suggestions": [],
  "total": 0
}

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","view_reports"]}`
400	Corpo ilegível, ou `entity_type`/`entity_id` ausente.	`{"error":"invalid request body"}` ou `{"error":"entity_type and entity_id are required"}`