API v3 — Copiloto (Terminal → Maggu)

Introdução

O ERP chama um endpoint de configuração da Copiloto antes de abrir o WebView. A Maggu retorna se aquele terminal está habilitado e a URL a carregar.

Fluxo Geral

Se habilitado for false, o ERP não exibe o WebView. Nenhuma configuração local é necessária — a ativação acontece remotamente no painel da Maggu.

POST /v3/copiloto/configuracao

Retorna se a Copiloto está habilitada para o terminal informado e, quando habilitada, a URL do WebView.

Request

POST /v3/copiloto/configuracao
Authorization: Token <token_da_loja>
Content-Type: application/json

{
    "terminal": "caixa-03",
    "sessao_id": null | "<uuid>" // se nulo cria sessão
}

Campo	Tipo	Obrigatório	Descrição
terminal	string	Sim	Identificador do terminal no ERP.

Response — 200 OK

{
  "habilitado": true,
  "url": "https://copilot.maggu.ai/mini-maggu/v1"
}

Campo	Tipo	Descrição
habilitado	boolean	true se o WebView deve ser exibido neste terminal; false caso contrário.
url	string	URL base do WebView da Copiloto. Presente apenas quando habilitado: true.

Quando habilitado é false, o campo url é omitido.

Response — 401 Unauthorized

Token inválido ou ausente.

Response — 400 Bad Request

Parâmetro terminal ausente ou inválido.

Comportamento por Terminal

Habilitação remota

Fluxo de ativação:

Não é necessário comunicar nada ao time de ERP ou visitar a loja — a mudança se propaga no próximo ciclo de consulta do terminal.

Recomendações para o ERP

Quando consultar: Chame o endpoint ao iniciar cada atendimento (ou sessão de caixa). Não consulte a cada transação — use um cache.

Consulta na inicialização: Chame o endpoint também na inicialização do ERP para preparar o estado antes do primeiro atendimento.

Falha na consulta: Em caso de erro HTTP ou timeout, assuma habilitado: false e tente novamente no próximo ciclo. Nunca bloqueie o fluxo de venda por indisponibilidade da Maggu.

Exemplos HTTP

### Variáveis
# @token = SEU_TOKEN_AQUI
# @base_url = https://api.maggu.ai

# ===============================================
# 1. Consultar configuração — terminal habilitado
# ===============================================

POST {{base_url}}/v3/copiloto/configuracao
Authorization: Token {{token}}
Content-Type: application/json

{ "terminal": "caixa-03" }

### Exemplo de resposta (habilitado):
# HTTP/1.1 200 OK
# {
#   "habilitado": true,
#   "url": "https://copilot.maggu.ai/mini-maggu/v1",
# }

###

# =================================================
# 2. Consultar configuração — terminal desabilitado
# =================================================

POST {{base_url}}/v3/copiloto/configuracao
Authorization: Token {{token}}
Content-Type: application/json

{ "terminal": "balcao-01" }

### Exemplo de resposta (desabilitado):
# HTTP/1.1 200 OK
# {
#   "habilitado": false,
# }