Documentação para desenvolvedores

Primeiros passos

Crie um token de API no seu painel em Tokens de API e webhooks. Escolha as read e/ou write habilidades e copie o token — ele é exibido apenas uma vez.

Uma verificação rápida de que seu token funciona:

curl https://mail.menubarcode.com/api/v1/restaurants \
  -H "Authorization: Bearer YOUR_TOKEN"

Autenticação

Envie seu token como um cabeçalho Bearer em cada requisição:

Authorization: Bearer YOUR_TOKEN

Para testes rápidos, você pode passar ?api_token=YOUR_TOKEN como parâmetro de consulta, mas o cabeçalho é fortemente preferido para que os tokens nunca vazem nos logs.

Tokens com escopo

Além do escopo amplo read/write, um token pode ser limitado a recursos específicos com resource:action habilidades. Recursos: restaurants, menu, orders, customers, analytics, drivers, webhooks; Ações read, write. Selecione-os ao criar o token no painel.

Regras de cobertura: * concede tudo; um :write escopo também concede seu :read; amplo read/write comportam-se como *:read / *:write. Uma requisição sem o escopo necessário retorna 403. Legado read/write os tokens não são afetados.

Os tokens são armazenados com hash (SHA-256) e podem ter uma expiração opcional. Revogue qualquer token instantaneamente pelo painel.

Limites de taxa

A API permite 120 requisições por minuto por token. Exceder esse limite retorna 429 Too Many Requests com um Retry-After cabeçalho. Cabeçalhos padrão de limite de taxa são incluídos em cada resposta:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118

Erros

Todo erro em uma /api/v1 rota retorna códigos de status HTTP convencionais e um único envelope JSON — um message, um estável, legível por máquina code, e (na validação) um por campo errors Mapa

{ "message": "Invalid or expired token.", "code": "unauthenticated" }

{ "message": "The given data was invalid.",
  "code": "validation_failed",
  "errors": { "title": ["The title field is required."] } }

Paginação

Os endpoints de listagem retornam envelopes paginados no estilo Laravel. Use o ?page= parâmetro de consulta para navegar pelas páginas.

{
  "data": [ ... ],
  "current_page": 1,
  "last_page": 3,
  "per_page": 20,
  "total": 47
}

Ler restaurantes e menu

Lista os restaurantes pertencentes ao token, paginados (20 por página).

{
  "data": [
    { "id": 12, "title": "Nova Bistro", "slug": "nova-bistro",
      "url": "https://.../nova-bistro", "template": "linen",
      "created_at": "2026-06-01T10:22:00+00:00" }
  ],
  "current_page": 1, "last_page": 1, "total": 1
}

Um único restaurante com suas categorias de menu e contagem de itens.

O menu ativo completo agrupado por categoria.

[
  { "id": 3, "name": "Starters",
    "items": [
      { "id": 88, "name": "Bruschetta", "price": 6.50,
        "is_sold_out": false, "is_popular": true, "is_vegan": true,
        "is_halal": true, "calories": 210 }
    ]
  }
]

Gerenciar Menu Escrever

CRUD completo para categorias e itens — tudo o que um app de lojista precisa para gerenciar o menu. Todos os endpoints de escrita exigem um write token e têm escopo limitado a um restaurante que você possui. Uploads de imagem estão fora do escopo do JSON; passe uma URL já hospedada em image.

curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/menu/items \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "category_id": 3, "name": "Margherita", "price": 11.00,
    "description": "San Marzano, mozzarella, basil",
    "is_vegan": true, "is_halal": true, "calories": 850
  }'

Alternador "86" rápido. Envie {"is_sold_out": true}, ou omita o corpo para alternar.

Pedidos

Pedidos, mais recentes primeiro, paginados (30/página). Filtre com ?status=.

Detalhe completo do pedido com itens, adicionais, entregador e linha do tempo da entrega.

Cria um pedido — é assim que um app do cliente envia um carrinho (o backend do lojista guarda o token). Cada item é validado contra o menu ativo do restaurante; itens esgotados ou de outro restaurante rejeitam o pedido inteiro (422). Dispara order.created e retorna o pedido completo, incluindo seu track_token.

curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/orders \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "delivery",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "address": "9 Cedar Road",
    "tip_amount": 3.00,
    "note": "Ring the bell",
    "source": "customer_app",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12], "note": "no onion" },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Pedido type é um de on-table, takeaway, delivery. para on-table passe table_number; para delivery passe address.

Idempotência. Envie um Idempotency-Key cabeçalho (ou um corpo client_uuid) em qualquer chamada de criação de pedido. Repetir com a mesma chave retorna o pedido original e nunca cria uma duplicata — seguro para respostas perdidas e reenvio offline. As chaves têm escopo por restaurante.

Atualiza o status da cozinha (new|preparing|ready|delivered|completed|cancelled). Dispara order.status_changed.

API da vitrine (token por restaurante)

Uma API pública separada, autenticada por um token de vitrine por restaurante enviado como X-Storefront-Token (não o token Bearer do proprietário). Emita-os pelo seu painel; cada token só pode acessar seu próprio restaurante. O escopo de leitura é menu:read; fazer pedidos exige o order:write Escopo

Menu completo do restaurante do token (variantes, adicionais, grupos, galeria).

Informações básicas do restaurante do token.

Envia um carrinho em nome de um cliente. Precificado no servidor e não pago (o cliente paga na chegada); takeaway ou on-table apenas. Cada item é validado contra o menu ativo — itens esgotados ou de outro restaurante rejeitam o pedido inteiro (422). Limites: 40 itens/pedido, 30 de quantidade/linha. Opcional coupon_code aplica um desconto do proprietário no servidor. Dispara order.created e retorna track_token + continue_url.

curl -X POST https://mail.menubarcode.com/api/v1/storefront/orders \
  -H "X-Storefront-Token: YOUR_STOREFRONT_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "type": "takeaway",
    "customer_name": "A. Idriss",
    "phone": "+15551234567",
    "coupon_code": "WELCOME10",
    "items": [
      { "item_id": 88, "quantity": 2, "variation": 5, "extras": [12] },
      { "item_id": 91, "quantity": 1 }
    ]
  }'

Analytics e clientes

Resumo de vendas em um intervalo de datas (?from=YYYY-MM-DD&to=YYYY-MM-DD, padrão: últimos 30 dias): contagem de pedidos por status/tipo, receita bruta e paga, valor médio do pedido e itens mais vendidos.

{
  "range": { "from": "2026-06-02", "to": "2026-07-02" },
  "orders": { "total": 214, "paid": 198, "by_status": {...}, "by_type": {...} },
  "revenue": { "gross": 8420.50, "paid": 7990.00, "avg_order_value": 39.35 },
  "top_items": [ { "item_id": 88, "name": "Margherita", "quantity": 143 } ]
}

A lista de clientes do restaurante (CRM), paginada. Filtre com ?search=.

Gerenciar entregadores Escrever

Os entregadores pertencem a você e (opcionalmente) a um restaurante. Criar ou rotacionar um entregador retorna um token de entregador exatamente uma vez — entregue-o ao app do entregador; eles se autenticam com ele (veja abaixo).

curl -X POST https://mail.menubarcode.com/api/v1/drivers \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Alex","phone":"+15550001111","restaurant_id":12}'

# → { "id": 7, "name": "Alex", ..., "token": "RAW_DRIVER_TOKEN_SHOWN_ONCE" }

Invalida o token antigo e retorna um novo.

Atribuir e rastrear uma entrega

Pedidos de entrega, filtráveis por ?delivery_status= e ?driver_id=.

Atribuir um entregador {"driver_id": 7}. Define delivery_status=assigned e dispara order.driver_assigned.

Substitua a etapa da entrega: pending | assigned | picked_up | out_for_delivery | delivered | failed.

API do app do entregador

O app do entregador se autentica com um Token de entregador (não um token de proprietário) emitido acima. Caminho base https://mail.menubarcode.com/api/v1/driver. Cada resposta tem escopo limitado a esse único entregador.

Authorization: Bearer RAW_DRIVER_TOKEN

O perfil do entregador autenticado.

Pedidos atribuídos a este entregador. Adicione ?active=1 para ocultar entregues/falhados.

Avance a entrega: {"delivery_status":"out_for_delivery"} depois "delivered" ou "picked_up" / "failed", opcional note). Dispara os mesmos webhooks que o endpoint do proprietário.

Envie a posição em tempo real: {"lat":25.2048,"lng":55.2708}. Exibida na tela de rastreamento do cliente enquanto está em rota de entrega.

Contas de clientes

A app de cliente independente autentica seus próprios usuários com um token por cliente (estilo Sanctum: vários dispositivos, revogáveis individualmente). Nenhum token de proprietário está envolvido. Os clientes têm escopo por restaurante, então a autenticação fica em /restaurants/{id}/customer/…. Explore o menu primeiro com o endpoint público:

Menu ativo agrupado por categoria (itens esgotados omitidos). Sem autenticação.

Registrar / entrar

curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/customer/login \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","password":"secret123","device":"iPhone 15"}'

# → { "token": "RAW_CUSTOMER_TOKEN", "customer": { "id": 42, "name": "Sam", ... } }

Sem senha (SMS OTP)

Solicite um código para um número de telefone e depois verifique-o. A verificação encontra ou cria o cliente e retorna um token. Os endpoints de autenticação têm limite de taxa (login/registro 10/min, solicitação de OTP 6/min).

API do app do cliente

Autentique com o token do cliente. Caminho base https://mail.menubarcode.com/api/v1/customer. Tudo tem escopo limitado ao cliente autenticado — o corpo do pedido nunca pode falsificar o id de outro cliente.

Authorization: Bearer RAW_CUSTOMER_TOKEN

Leitura / atualização de perfil (nome, e-mail, telefone, aniversário, consentimentos).

Faça um pedido como este cliente (mesmo formato de item do endpoint de criação do lojista; a identidade vem do token). Retorna o pedido com seu track_token.

O histórico de pedidos do próprio cliente, paginado.

Endereços de entrega salvos (o primeiro se torna padrão; suporta lat/lng).

Revoga o token usado na requisição (apenas esse dispositivo).

Rastreamento de pedidos Público

Sem autenticação — o acesso é controlado pelo imprevisível track_token (retornado quando o pedido é criado). Isso alimenta uma app do cliente tela de rastreamento ao vivo.

{
  "id": 5501, "status": "preparing", "delivery_status": "out_for_delivery",
  "is_paid": true, "total": 42.00,
  "timeline": { "preparing_at": "...", "out_for_delivery_at": "..." },
  "items": [ { "name": "Margherita", "quantity": 2 } ],
  "driver": { "name": "Alex", "lat": 25.2, "lng": 55.27, "location_updated_at": "..." }
}

O bloco do entregador (com coordenadas em tempo real) só aparece depois que o pedido é retirado / sai para entrega.

Login da equipe

A app da equipe (POS / KDS / garçom) autentica cada membro da equipe com um token por funcionário. Dois caminhos espelham o painel: e-mail + senha, ou um PIN numérico rápido para tablets compartilhados da cozinha. A equipe tem escopo por restaurante.

curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/staff/pin \
  -H "Content-Type: application/json" -d '{"pin":"4321","device":"Kitchen iPad"}'

# → { "token": "RAW_STAFF_TOKEN",
#     "staff": { "id": 3, "role": "kitchen", "permissions": ["kds"] } }

A resposta lista as permissões efetivas do membro da equipe Permissões — um subconjunto de orders, menu_edit, coupons, analytics, kds, customers derivadas de sua função (gerente / caixa / cozinha / garçom) mais quaisquer substituições por funcionário. Os endpoints são controlados por permissão (403 caso contrário).

API do app da equipe

Autentique com o token da equipe. Caminho base https://mail.menubarcode.com/api/v1/staff. Todas as ações têm escopo limitado ao restaurante do membro da equipe.

Authorization: Bearer RAW_STAFF_TOKEN

Perfil com lista de função e permissões.

Liste pedidos e atualize o status da cozinha. Requer a orders permissão.

Comandas de cozinha ao vivo agrupadas por pedido, filtradas pela estação do membro da equipe (ou ?station_id=). Mostra apenas itens ainda queued|preparing|ready.

Avance (queued → preparing → ready → served) ou retroceda um status KDS. O status do pedido pai é ressincronizado automaticamente.

Edite o menu a partir do salão (gerentes). Mesmos payloads dos endpoints de menu do lojista, com escopo limitado ao restaurante do membro da equipe.

Resumo de vendas do restaurante do membro da equipe (mesmo formato do endpoint de analytics do lojista; ?from=&to=).

Revoga o token deste dispositivo.

Webhooks — configuração

Registre endpoints pelo painel em Tokens de API e webhooks. Escolha quais eventos cada endpoint recebe. Ao salvar, você recebe um por endpoint Segredo de assinatura; Use o Testar botão para enviar um ping. Pause um endpoint para interromper a entrega sem perder seu segredo.

Seu endpoint deve responder com um 2xx status rapidamente (em até 10s). Qualquer outro status — ou um tempo esgotado — é tratado como falha e reenviado.

Os endpoints também podem ser gerenciados programaticamente (para REST-Hooks do Zapier/Make) com um webhooks:write token:

GET    /api/v1/webhook-endpoints            # list your endpoints
POST   /api/v1/webhook-endpoints            # {"url":"https://…","events":["order.created"]} → 201 {id, secret, …}
DELETE /api/v1/webhook-endpoints/{id}       # unsubscribe → 204

O secret é retornado apenas na criação — guarde-o para verificar a assinatura. url deve ser um endpoint HTTPS público (protegido contra SSRF); events deve ser da lista abaixo (ou *).

Eventos de webhook

Falhou uma entrega enquanto seu endpoint estava fora do ar? Use Reenviar em qualquer linha do registro de Entregas recentes do painel para recolocá-la na fila com um novo webhook-id.

Payload do webhook

Cada entrega é um POST com este envelope JSON e estes cabeçalhos:

POST /your-endpoint HTTP/1.1
Content-Type: application/json
webhook-id: msg_a1b2c3d4e5f6g7h8i9j0k1l2
webhook-timestamp: 1751472240
webhook-signature: v1,K5f...base64...==
X-Webhook-Event: order.created          (legacy)
X-Webhook-Signature: 9a3f...hex...      (legacy, HMAC of body only)

{
  "id": "msg_a1b2c3d4e5f6g7h8i9j0k1l2",
  "event": "order.created",
  "created_at": "2026-07-02T18:04:00+00:00",
  "data": { "order_id": 5501, "total": "42.00" }
}

O id é único por entrega. Como as novas tentativas reutilizam o mesmo id, use-o para tornar seu handler idempotente.

Verificando a assinatura

O webhook-signature cabeçalho é um HMAC-SHA256, codificado em base64, calculado sobre {id}.{timestamp}.{body} usando o segredo de assinatura do seu endpoint. Vincular o id e o carimbo de data/hora à assinatura é o que torna uma requisição capturada segura contra reenvio. Rejeite qualquer requisição cujo webhook-timestamp tenha mais de ~5 minutos.

PHP

$secret  = 'whsec_from_dashboard';
$id      = $_SERVER['HTTP_WEBHOOK_ID'];
$ts      = $_SERVER['HTTP_WEBHOOK_TIMESTAMP'];
$body    = file_get_contents('php://input');
$sent    = explode(',', $_SERVER['HTTP_WEBHOOK_SIGNATURE'])[1] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = base64_encode(hash_hmac('sha256', "$id.$ts.$body", $secret, true));
if (!hash_equals($expected, $sent)) { http_response_code(401); exit; }

// verified — process $body
http_response_code(200);

Node.js

const crypto = require('crypto');

function verify(req, secret) {
  const id  = req.headers['webhook-id'];
  const ts  = req.headers['webhook-timestamp'];
  const sig = (req.headers['webhook-signature'] || '').split(',')[1];
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${id}.${ts}.${req.rawBody}`)
    .digest('base64');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig || ''));
}

Novas tentativas e registro de entregas

A entrega é assíncrona e reenviada em caso de falha com backoff exponencial mais jitter: aproximadamente 1m → 5m → 15m → 1h (até 5 tentativas no total). Cada tentativa — sucesso ou falha — é registrada no registro de entregas do seu painel com seu status HTTP, número da tentativa e trecho da resposta.

Servidores MCP

Cinco servidores Model Context Protocol conectam agentes de IA (ChatGPT, Claude, Cursor) à plataforma — escolha o que corresponde ao seu público. Todos falam JSON-RPC 2.0 sobre HTTP e negociam versões de protocolo 2024-11-05 / 2025-03-26 / 2025-06-18.

Início rápido: pular para Admin, Catalog, Customer, ou Dev. O servidor da vitrine compartilha o padrão de conexão do Admin com um X-Storefront-Token cabeçalho em vez de um token Bearer.

Servidor MCP (Admin)

Um cliente de IA compatível com MCP (Claude, ChatGPT, Cursor) pode operar seu restaurante em linguagem natural usando os mesmos tokens de API. Aponte-o para:

Autentique com Authorization: Bearer YOUR_TOKEN. Cada ferramenta declara a habilidade granular de que precisa (resource:action); um legado read token cobre todas as :read ferramentas e write cobre tudo. Todas as chamadas têm escopo limitado aos seus restaurantes e limite de taxa. As ferramentas para as quais você não tem a habilidade ficam ocultas em tools/list.

Conectar (Claude Code)

claude mcp add --transport http platform-admin https://mail.menubarcode.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Listar ferramentas

curl -X POST https://mail.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Chamar uma ferramenta (ex.: adicionar um item de menu)

curl -X POST https://mail.menubarcode.com/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"add_menu_item",
                 "arguments":{"restaurant_id":12,"name":"Latte","price":4.5}}}'

Ferramentas

Catalog MCP (descobrir restaurantes)

Um servidor MCP público e somente leitura que permite a agentes de IA descobrir restaurantes e pratos em toda a plataforma e depois criar deep links para uma loja específica para pedir. Sem autenticação, com limite de taxa.

Conectar (Claude Code)

claude mcp add --transport http platform-catalog https://mail.menubarcode.com/mcp/catalog

Apenas lojas ativas e listadas publicamente aparecem; os proprietários podem desativar nas configurações da loja. Nenhum dado de contato do proprietário é retornado. Para fazer um pedido, use o MCP da vitrine da loja com um token de agente por loja.

MCP de Conta do Cliente

Permite que o assistente de IA de um cliente leia, rastreie e repita seus próprios pedidos. Autenticado por um token por cliente do login OTP existente; a identidade do cliente vem apenas do token — um telefone ou id de cliente nunca é aceito como argumento.

Obter um token (fluxo OTP)

# 1) request a one-time code (sent to the customer's phone)
curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/customer/otp/request \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567"}'

# 2) verify the code → returns a customer bearer token
curl -X POST https://mail.menubarcode.com/api/v1/restaurants/12/customer/otp/verify \
  -H "Content-Type: application/json" -d '{"phone":"+15551234567","code":"123456"}'

Conectar (Claude Code)

claude mcp add --transport http my-orders https://mail.menubarcode.com/mcp/customer \
  --header "Authorization: Bearer CUSTOMER_TOKEN"

curl -X POST https://mail.menubarcode.com/mcp/customer \
  -H "Authorization: Bearer CUSTOMER_TOKEN" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"my_orders","arguments":{"limit":5}}}'

Conecte seu editor de IA

Criando um tema ou uma integração com Claude Code, Cursor ou VS Code? Aponte-o para o servidor MCP Dev — sua ferramenta de IA obtém a documentação ao vivo da plataforma, a whitelist Liquid gerada e a validação de tema no servidor. Nenhum token necessário.

Claude Code

claude mcp add --transport http platform-dev https://mail.menubarcode.com/mcp/dev

Cursor — .cursor/mcp.json

{ "mcpServers": { "platform-dev": { "url": "https://mail.menubarcode.com/mcp/dev" } } }

VS Code — .vscode/mcp.json

{ "servers": { "platform-dev": { "type": "http", "url": "https://mail.menubarcode.com/mcp/dev" } } }

Ferramentas learn_platform (comece aqui), search_docs / fetch_full_doc, get_liquid_reference, get_section_schema, validate_theme, list_webhook_events. Fluxo de trabalho recomendado do agente: aprender → construir → validar → entregar.

Registro de alterações

Voltar para Menubarcode