API atual/Referência completa/Venddor Intelligence: automações e canais

SAC resolutivo

Liga o atendimento pós-venda feito pela VI, consulta o que ela fez em cada conversa e a assume ou devolve a um humano.

O SAC resolutivo faz a VI responder as mensagens de pós-venda que o cliente envia na central de mensagens da loja: acompanhar um pedido, pedir devolução, segunda via de nota fiscal, reagendar a entrega. Ações que alteram algo (devolução, reagendamento) só saem depois que o cliente confirma na conversa. Quando a VI não resolve, ela passa a conversa para um humano (handoff). Cada ação fica registrada num histórico por conversa.

Ler o SAC

Devolve os três interruptores e as métricas. Os três nascem false.

GET/api/v1/admin/intelligence/sac/settingsAdmin

Ler o SAC

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/sac/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração do SAC

json

{
  "enabled": true,
  "allow_returns": true,
  "allow_reschedule": false,
  "metrics": { "resolved_rate": 0.72, "handoff_count": 14, "avg_response_ms": 0 }
}

Campos da resposta

enabledboolean

A VI responde as conversas de pós-venda.

allow_returnsboolean

Permite abrir devolução quando o cliente confirma.

allow_rescheduleboolean

Permite reagendar entrega quando o cliente confirma.

metricsobject

Só na leitura. resolved_rate (0 a 1, resolvidas sobre todas as ações registradas), handoff_count (conversas passadas a humano) e avg_response_ms (hoje sempre 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":["manage_settings","intelligence_use_chat"]}`

Alterar o SAC

Grava os três interruptores. Devolve o mesmo objeto da leitura, já atualizado. O campo metrics do corpo é ignorado.

PUT/api/v1/admin/intelligence/sac/settingsAdmin

Alterar o SAC

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

enabledbooleanobrigatório

Liga ou desliga o SAC.

allow_returnsbooleanobrigatório

Permite devoluções.

allow_reschedulebooleanobrigatório

Permite reagendamentos.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/sac/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "allow_returns": true,
    "allow_reschedule": false
  }'

Resposta

200SAC atualizado

json

{
  "enabled": true,
  "allow_returns": true,
  "allow_reschedule": false,
  "metrics": { "resolved_rate": 0.72, "handoff_count": 14, "avg_response_ms": 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":["manage_settings","intelligence_use_chat"]}`
400	Corpo ilegível.	`{"error":"invalid request body"}`

Ações numa conversa

Lista, da mais nova para a mais antiga, o que a VI fez numa conversa da central de mensagens.

GET/api/v1/admin/intelligence/sac/actionsAdmin

Ações do SAC numa conversa

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

thread_iduuidobrigatório

Id da conversa da central de mensagens.

limitintegerpadrão: 50

Quantidade. 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/sac/actions?thread_id=$THREAD_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ações

json

{
  "actions": [
    {
      "id": "c41d6e7f-8a9b-4c0d-a1e2-f3a4b5c6d7e8",
      "thread_id": "5d0a9b1e-2f3c-4a5b-8c7d-9e0f1a2b3c4d",
      "message_id": "e1f2a3b4-c5d6-4789-a0b1-c2d3e4f5a6b7",
      "tool": "handoff",
      "payload": {},
      "result": "handoff",
      "created_at": "2026-10-11T13:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

actions[].iduuid

Id do registro.

actions[].thread_iduuid

Conversa.

actions[].message_iduuid

Mensagem do cliente que originou a ação. Pode ser nulo.

actions[].toolstring

Identificador da ação executada (por exemplo handoff).

actions[].payloadobject

Dados usados pela ação.

actions[].resultstring

resolvedfailedhandoffconfirmed_write

Resultado.

actions[].detailobject

Detalhes adicionais, quando existem.

actions[].created_atstring

RFC 3339.

totalinteger

Quantidade devolvida.

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":["manage_settings","intelligence_use_chat"]}`
400	`thread_id` ausente.	`{"error":"thread_id required"}`
500	`thread_id` que não é um UUID.	`{"error":"o valor \"x\" não é um uuid válido. ..."}` (devolvido em português)

Controlar a VI numa conversa

Define se a VI atende aquela conversa. Use handoff quando um humano assumir e active para devolver a conversa à VI; off a desliga naquela conversa.

PUT/api/v1/admin/intelligence/sac/threads/{id}/agentAdmin

Controlar a VI numa conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da conversa da central de mensagens.

Corpo da requisição

agent_statusstringobrigatório

activehandoffoff

Estado desejado.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/sac/threads/$THREAD_ID/agent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_status": "handoff"
  }'

Resposta

200Atualizado

json

{ "ok": true, "agent_status": "handoff" }

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":["manage_settings","intelligence_use_chat"]}`
400	`agent_status` fora dos três valores, ou corpo ilegível.	`{"error":"invalid agent_status"}`
500	`id` inválido.	`{"error":"..."}`

Veja também

API atual/Referência completa/Venddor Intelligence: automações e canais

SAC resolutivo

Liga o atendimento pós-venda feito pela VI, consulta o que ela fez em cada conversa e a assume ou devolve a um humano.

Ler o SAC

Devolve os três interruptores e as métricas. Os três nascem false.

GET/api/v1/admin/intelligence/sac/settingsAdmin

Ler o SAC

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/intelligence/sac/settings" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Configuração do SAC

json

{
  "enabled": true,
  "allow_returns": true,
  "allow_reschedule": false,
  "metrics": { "resolved_rate": 0.72, "handoff_count": 14, "avg_response_ms": 0 }
}

Campos da resposta

enabledboolean

A VI responde as conversas de pós-venda.

allow_returnsboolean

Permite abrir devolução quando o cliente confirma.

allow_rescheduleboolean

Permite reagendar entrega quando o cliente confirma.

metricsobject

Só na leitura. resolved_rate (0 a 1, resolvidas sobre todas as ações registradas), handoff_count (conversas passadas a humano) e avg_response_ms (hoje sempre 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":["manage_settings","intelligence_use_chat"]}`

Alterar o SAC

Grava os três interruptores. Devolve o mesmo objeto da leitura, já atualizado. O campo metrics do corpo é ignorado.

PUT/api/v1/admin/intelligence/sac/settingsAdmin

Alterar o SAC

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Corpo da requisição

enabledbooleanobrigatório

Liga ou desliga o SAC.

allow_returnsbooleanobrigatório

Permite devoluções.

allow_reschedulebooleanobrigatório

Permite reagendamentos.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/sac/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "allow_returns": true,
    "allow_reschedule": false
  }'

Resposta

200SAC atualizado

json

{
  "enabled": true,
  "allow_returns": true,
  "allow_reschedule": false,
  "metrics": { "resolved_rate": 0.72, "handoff_count": 14, "avg_response_ms": 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":["manage_settings","intelligence_use_chat"]}`
400	Corpo ilegível.	`{"error":"invalid request body"}`

Ações numa conversa

Lista, da mais nova para a mais antiga, o que a VI fez numa conversa da central de mensagens.

GET/api/v1/admin/intelligence/sac/actionsAdmin

Ações do SAC numa conversa

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de consulta

thread_iduuidobrigatório

Id da conversa da central de mensagens.

limitintegerpadrão: 50

Quantidade. 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/sac/actions?thread_id=$THREAD_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Ações

json

{
  "actions": [
    {
      "id": "c41d6e7f-8a9b-4c0d-a1e2-f3a4b5c6d7e8",
      "thread_id": "5d0a9b1e-2f3c-4a5b-8c7d-9e0f1a2b3c4d",
      "message_id": "e1f2a3b4-c5d6-4789-a0b1-c2d3e4f5a6b7",
      "tool": "handoff",
      "payload": {},
      "result": "handoff",
      "created_at": "2026-10-11T13:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

actions[].iduuid

Id do registro.

actions[].thread_iduuid

Conversa.

actions[].message_iduuid

Mensagem do cliente que originou a ação. Pode ser nulo.

actions[].toolstring

Identificador da ação executada (por exemplo handoff).

actions[].payloadobject

Dados usados pela ação.

actions[].resultstring

resolvedfailedhandoffconfirmed_write

Resultado.

actions[].detailobject

Detalhes adicionais, quando existem.

actions[].created_atstring

RFC 3339.

totalinteger

Quantidade devolvida.

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":["manage_settings","intelligence_use_chat"]}`
400	`thread_id` ausente.	`{"error":"thread_id required"}`
500	`thread_id` que não é um UUID.	`{"error":"o valor \"x\" não é um uuid válido. ..."}` (devolvido em português)

Controlar a VI numa conversa

Define se a VI atende aquela conversa. Use handoff quando um humano assumir e active para devolver a conversa à VI; off a desliga naquela conversa.

PUT/api/v1/admin/intelligence/sac/threads/{id}/agentAdmin

Controlar a VI numa conversa

Cabeçalhos

Authorizationstringobrigatório

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

Content-Typestringobrigatório

application/json.

Parâmetros de caminho

iduuidobrigatório

Id da conversa da central de mensagens.

Corpo da requisição

agent_statusstringobrigatório

activehandoffoff

Estado desejado.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/intelligence/sac/threads/$THREAD_ID/agent" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_status": "handoff"
  }'

Resposta

200Atualizado

json

{ "ok": true, "agent_status": "handoff" }

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":["manage_settings","intelligence_use_chat"]}`
400	`agent_status` fora dos três valores, ou corpo ilegível.	`{"error":"invalid agent_status"}`
500	`id` inválido.	`{"error":"..."}`