API atual/Referência completa/Venddor Intelligence

Pedido montado na conversa

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

O seller 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/vendor/intelligence/sessions/{id}/fsmSeller

Estado do pedido em montagem

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

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/vendor/intelligence/sessions/{id}/order/add-itemSeller

Adicionar um item ao pedido em montagem

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (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. Padrão 1; zero ou negativo vira 1.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/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": { } }

Campos da resposta

statestring

Estado do pedido depois de incluir o item (tabela de estados acima).

next_promptstring

Próxima frase sugerida para a conversa. Ausente quando vazia.

dataobject

Dados coletados até agora. O carrinho fica em data.cart[], com product_id, quantity, name e unit_price_centavos (centavos, apenas indicativo: o preço é recalculado ao criar o pedido).

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

Mensagens

API atual/Referência completa/Venddor Intelligence

Pedido montado na conversa

Consulta 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/vendor/intelligence/sessions/{id}/fsmSeller

Estado do pedido em montagem

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

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/vendor/intelligence/sessions/{id}/order/add-itemSeller

Adicionar um item ao pedido em montagem

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso de um seller (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. Padrão 1; zero ou negativo vira 1.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/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": { } }

Campos da resposta

statestring

Estado do pedido depois de incluir o item (tabela de estados acima).

next_promptstring

Próxima frase sugerida para a conversa. Ausente quando vazia.

dataobject

Dados coletados até agora. O carrinho fica em data.cart[], com product_id, quantity, name e unit_price_centavos (centavos, apenas indicativo: o preço é recalculado ao criar o pedido).

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

Mensagens