API do Copilot — Sessão

Documentação dos endpoints de abertura e encerramento de sessão do Copilot (Mini Maggu).

Base URL: https://api.localhost (local) ou a URL de API configurada no ambiente.

Autenticação: Token de configuração da loja via Authorization: Token <token>.

---

Abrir ou restaurar sessão

POST /copilot/sessoes

Cria uma nova sessão ou restaura uma sessão existente. Retorna a URL da Mini Maggu para ser aberta no PDV.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
sessaoId	UUID	Não	ID de uma sessão existente. Se fornecido e válido, a sessão é restaurada.
deviceId	string	Não	Identificador do dispositivo (PDV/terminal). Máx. 256 caracteres.
versaoErp	string	Não	Versão do ERP/PDV que está abrindo o copilot. Máx. 64 caracteres.
metadados	object	Não	Metadados livres do dispositivo (ex: {"so": "windows"}).

Exemplo — nova sessão:

{
  "deviceId": "POS-001",
  "versaoErp": "1.2.3",
  "metadados": { "so": "windows" }
}

Exemplo — restaurar sessão:

{
  "sessaoId": "550e8400-e29b-41d4-a716-446655440000"
}

Respostas

200 — Loja apta:

{
  "ativo": true,
  "sessaoId": "550e8400-e29b-41d4-a716-446655440000",
  "url": "http://copilot.localhost/mini-maggu/v1/?token=abc&sala_id=550e8400-e29b-41d4-a716-446655440000"
}

Abrir url no iframe/webview do PDV inicia a interface do Mini Maggu. Guardar sessaoId para encerrar a sessão depois.

200 — Loja inapta:

{
  "ativo": false,
  "status": "BLOQUEADO"
}

Quando ativo é false, a url não é retornada e o copilot não deve ser exibido. Valores possíveis de status:

Valor	Causa
BLOQUEADO	Loja bloqueada
CHURN_VOLUNTARIO	Loja cancelou o serviço
DISPOSITIVO_DESATIVADO	O deviceId enviado está desativado nas configurações da loja

---

Encerrar sessão enviando a pré-venda

POST /copilot/sessoes/{sessaoId}/encerrar

Encerra a sessão do copilot e registra a pré-venda completa. Deve ser chamado quando o vendedor finaliza o atendimento no PDV.

Parâmetro de rota

Parâmetro	Tipo	Descrição
sessaoId	UUID	ID da sessão retornado na abertura (sessaoId do POST).

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
codigoExternoUsuario	string	Sim	Código do vendedor no ERP. Máx. 256 caracteres.
codigoExternoPreVenda	string	Sim	Código da pré-venda no ERP. Máx. 256 caracteres.
cpfCnpjDoCliente	string	Não	CPF ou CNPJ do cliente (apenas dígitos).
itens	array	Sim	Lista de itens da pré-venda. Máx. 500 itens.
itens[].ean	string	Sim	EAN do produto.
itens[].quantidade	integer	Sim	Quantidade do produto.
itens[].codigoExternoUsuario	string	Não	Código do vendedor responsável por este item no ERP.

Exemplo:

{
  "codigoExternoUsuario": "VENDEDOR-1",
  "codigoExternoPreVenda": "PV-123",
  "cpfCnpjDoCliente": "30769867081",
  "itens": [
    {
      "ean": "7896000000000",
      "quantidade": 2,
      "codigoExternoUsuario": "VENDEDOR-1"
    },
    {
      "ean": "7891234567890",
      "quantidade": 1
    }
  ]
}

Respostas

Status	Descrição
201	Pré-venda registrada com sucesso. Sessão encerrada.
400	Dados inválidos. O corpo da resposta detalha os campos com erro.
403	Token inválido ou sem permissão.

---

Fluxo completo

PDV                                      API Copilot
 |                                            |
 |-- POST /copilot/sessoes -----------------> |
 |                                            | verifica elegibilidade da loja
 |                                            | verifica se device_id está ativo
 |<-- 200 { ativo: true, sessaoId, url } ---- |
 |                                            |
 | [abre url no iframe/webview]               |
 | [vendedor usa o Mini Maggu]                |
 |                                            |
 |-- POST /copilot/sessoes/{sessaoId}/encerrar|
 |   { itens, codigoExternoPreVenda, ... } -> |
 |                                            | registra pré-venda
 |<-- 201 ----------------------------------- |
 |                                            |
 | [fecha o iframe/webview]                   |