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

Pedido montado na conversa

Consulta, cancela e alimenta o pedido que a VI está montando passo a passo dentro de uma sessão.

O administrador pode pedir "crie um pedido para a Maria com dois mouses". A VI conduz uma máquina de estados: coleta itens, confirma o carrinho, pede endereço, frete e pagamento, e só então cria o pedido. O estado vive na sessão. Estas rotas deixam uma interface mostrar o andamento e intervir. Ligar ou desligar o recurso é a chave enable_conversational_order_creation em Configurações.

Estados

`state`	Significado
`idle`	Nenhum pedido em andamento
`collecting_items`	Reunindo os itens
`confirming_cart`	Esperando o "sim" para o carrinho
`collecting_address`	Pedindo o endereço de entrega
`selecting_shipping`	Escolhendo o frete
`selecting_payment`	Escolhendo a forma de pagamento
`confirming_order`	Esperando o "sim" final
`placed`	Pedido criado
`cancelled`	Pedido cancelado

Consultar o estado

Devolve o estado atual e os dados já coletados (itens, endereço, frete, pagamento).

GET/api/v1/admin/intelligence/sessions/{id}/fsmAdmin

Estado do pedido em montagem

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

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

Resposta

200Estado

json

{ "state": "idle", "data": {} }

Campos da resposta

statestring

Um dos estados da tabela acima.

dataobject

Dados coletados até aqui. Formato livre, vazio em idle.

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"]}`
404	Sessão inexistente.	`{"error":"session not found"}`

Cancelar a montagem

Descarta o pedido que está sendo montado e leva o estado para cancelled. Não cancela um pedido que já foi criado (placed): isso é feito na API de pedidos.

POST/api/v1/admin/intelligence/sessions/{id}/fsm/cancelAdmin

Cancelar o pedido em montagem

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/fsm/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cancelado

json

{
  "state": "cancelled",
  "next_prompt": "Pedido cancelado. Quando quiser recomeçar, é só me dizer o que você gostaria de comprar.",
  "data": {}
}

Campos da resposta

statestring

Novo estado.

next_promptstring

Frase que a VI diria em seguida (em português).

dataobject

Dados restantes.

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_create_orders","manage_settings"]}`
403	Criação de pedido por conversa desligada na loja.	`{"error":"conversational order creation disabled"}`
404	Sessão inexistente.	`{"error":"session not found"}`

Adicionar um item

Acrescenta um produto ao pedido em montagem sem passar pelo texto da conversa. Útil para o botão "adicionar" de uma lista de produtos.

POST/api/v1/admin/intelligence/sessions/{id}/order/add-itemAdmin

Adicionar um item ao pedido em montagem

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 sessão.

Corpo da requisição

product_iduuidobrigatório

Produto a adicionar.

product_namestring

Nome do produto, para exibição na conversa.

quantityintegerpadrão: 1

Quantidade. Zero, negativo ou omitido vira 1.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/order/add-item" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
    "product_name": "Mouse Gamer Titan",
    "quantity": 2
  }'

Resposta

200Item adicionado

json

{ "state": "collecting_items", "next_prompt": "Adicionei 2 x Mouse Gamer Titan. Mais algum item?", "data": { } }

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_create_orders","manage_settings"]}`
400	`product_id` ausente ou corpo ilegível.	`{"error":"product_id required"}`
403	Criação de pedido por conversa desligada na loja.	`{"error":"conversational order creation disabled"}`
404	Sessão inexistente.	`{"error":"session not found"}`

Veja também

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

Pedido montado na conversa

Consulta, cancela e alimenta o pedido que a VI está montando passo a passo dentro de uma sessão.

Estados

`state`	Significado
`idle`	Nenhum pedido em andamento
`collecting_items`	Reunindo os itens
`confirming_cart`	Esperando o "sim" para o carrinho
`collecting_address`	Pedindo o endereço de entrega
`selecting_shipping`	Escolhendo o frete
`selecting_payment`	Escolhendo a forma de pagamento
`confirming_order`	Esperando o "sim" final
`placed`	Pedido criado
`cancelled`	Pedido cancelado

Consultar o estado

Devolve o estado atual e os dados já coletados (itens, endereço, frete, pagamento).

GET/api/v1/admin/intelligence/sessions/{id}/fsmAdmin

Estado do pedido em montagem

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

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

Resposta

200Estado

json

{ "state": "idle", "data": {} }

Campos da resposta

statestring

Um dos estados da tabela acima.

dataobject

Dados coletados até aqui. Formato livre, vazio em idle.

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"]}`
404	Sessão inexistente.	`{"error":"session not found"}`

Cancelar a montagem

Descarta o pedido que está sendo montado e leva o estado para cancelled. Não cancela um pedido que já foi criado (placed): isso é feito na API de pedidos.

POST/api/v1/admin/intelligence/sessions/{id}/fsm/cancelAdmin

Cancelar o pedido em montagem

Cabeçalhos

Authorizationstringobrigatório

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

Parâmetros de caminho

iduuidobrigatório

Id da sessão.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/fsm/cancel" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Cancelado

json

{
  "state": "cancelled",
  "next_prompt": "Pedido cancelado. Quando quiser recomeçar, é só me dizer o que você gostaria de comprar.",
  "data": {}
}

Campos da resposta

statestring

Novo estado.

next_promptstring

Frase que a VI diria em seguida (em português).

dataobject

Dados restantes.

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_create_orders","manage_settings"]}`
403	Criação de pedido por conversa desligada na loja.	`{"error":"conversational order creation disabled"}`
404	Sessão inexistente.	`{"error":"session not found"}`

Adicionar um item

Acrescenta um produto ao pedido em montagem sem passar pelo texto da conversa. Útil para o botão "adicionar" de uma lista de produtos.

POST/api/v1/admin/intelligence/sessions/{id}/order/add-itemAdmin

Adicionar um item ao pedido em montagem

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 sessão.

Corpo da requisição

product_iduuidobrigatório

Produto a adicionar.

product_namestring

Nome do produto, para exibição na conversa.

quantityintegerpadrão: 1

Quantidade. Zero, negativo ou omitido vira 1.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/intelligence/sessions/$SESSION_ID/order/add-item" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "7bc1d5e9-a9a4-457b-866f-bbb3879d258d",
    "product_name": "Mouse Gamer Titan",
    "quantity": 2
  }'

Resposta

200Item adicionado

json

{ "state": "collecting_items", "next_prompt": "Adicionei 2 x Mouse Gamer Titan. Mais algum item?", "data": { } }

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_create_orders","manage_settings"]}`
400	`product_id` ausente ou corpo ilegível.	`{"error":"product_id required"}`
403	Criação de pedido por conversa desligada na loja.	`{"error":"conversational order creation disabled"}`
404	Sessão inexistente.	`{"error":"session not found"}`