Crie uma app
Os apps estendem a conta de um restaurante por meio de acesso OAuth com escopo e revogável. Seu código roda nos seus servidores; a plataforma mantém o registro, o histórico de instalações e a infraestrutura de cobrança. Este guia leva você do zero a um app instalado e com medição.
1. Registre seu app
Crie um app no painel de parceiros: nome, categoria, os escopos de que você precisa, uma URL de webhook opcional e seu modelo de cobrança. O envio cria um cliente OAuth (client id + secret) e coloca o app em revisão. Assim que um admin o aprova, ele aparece na App Store e pode ser instalado.
2. Seja instalado
Um dono de restaurante instala seu app pela página de detalhes na App Store, concedendo os escopos solicitados. A instalação cria uma AppInstallation e (para apps pagos) cobra o primeiro período pela carteira dele.
3. Chame a API
Troque um token OAuth pela conta que fez a instalação e depois chame a REST API com ele. Reporte uso, receba webhooks ou incorpore uma página no painel dele — abordado abaixo.
OAuth e tokens
Os apps se autenticam com OAuth 2.0 (Laravel Passport). Suas credenciais de cliente vêm do painel de parceiros. Use o fluxo padrão de código de autorização; o token concedido carrega os escopos que o proprietário aprovou na instalação.
# Exchange an authorization code for an access token
curl -X POST https://www.menubarcode.comoauth/token \
-d grant_type=authorization_code \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d redirect_uri=YOUR_REDIRECT \
-d code=AUTH_CODE
# Call the API with the returned bearer token
curl https://www.menubarcode.com/api/v1/restaurants \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json"Os tokens têm escopo: uma chamada que precisa de orders:read falha, a menos que o proprietário a tenha concedido. Solicite o conjunto mínimo — os revisores verificam isso.
Tokens de sessão
Para chamadas de curta duração de servidor para conteúdo incorporado, crie um token de sessão a partir de uma instalação ativa. Os tokens expiram após 60 segundos.
GET https://www.menubarcode.comapps/{appId}/session-token
# → { "token": "…", "expires_in": 60 }Apps incorporados
Se o seu app declara uma embed_url, a plataforma o hospeda em um iframe dentro do painel do proprietário em /apps/{appId}/embed. Combine-o com um token de sessão (acima) para autenticar a página incorporada sem um ciclo OAuth completo.
Webhooks
Inscreva-se em eventos no webhook_url. As entregas são enfileiradas, reenviadas e assinadas com o esquema Standard Webhooks usando o segredo de assinatura do seu app. Seu endpoint deve ser uma URL HTTPS pública (sem hosts privados/loopback/metadata) e retornar 2xx rapidamente.
# A delivery your endpoint receives
POST https://your-app.com/webhooks
webhook-id: msg_...
webhook-timestamp: 1710000000
webhook-signature: v1,BASE64_HMAC
Content-Type: application/json
{ "type": "order.paid", "data": { "order_id": 123, ... } }Verifique a assinatura contra seu segredo antes de confiar em um payload. Veja a lista de eventos.
Cobrança por uso
Apps cobrados por uso medem o consumo reportando unidades. Cada relatório é cobrado da carteira do proprietário pelo seu preço por unidade. Passe um ref único para tornar um relatório idempotente (uma repetição com o mesmo ref é ignorada).
curl -X POST https://www.menubarcode.com/api/app/usage \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
-d quantity=1 \
-d ref=unique-key-per-event| Campo | Tipo | Observações |
|---|---|---|
quantity | número > 0 | obrigatório — unidades consumidas |
ref | string ≤ 120 | chave de idempotência opcional |
O endpoint retorna 403 se o token não pertence a um app registrado ou o app não está instalado para a conta.
Guias práticos
Escolha um tipo de cobrança
- Grátis — sem cobrança na instalação.
- Recorrente — um preço fixo cobrado a cada período de cobrança (padrão 30 dias) da carteira do proprietário.
- Por utilização — um preço por unidade cobrado conforme você reporta o uso.
Solicite escopos com responsabilidade
Solicite apenas os escopos que seu app usa. Alterar escopos em uma listagem ativa envia o app de volta para revisão. Veja a referência de escopos.
Limpe na desinstalação
Quando um proprietário desinstala, a plataforma revoga os tokens do app e dispara um app/uninstalled evento. Interrompa o trabalho em segundo plano e exclua os dados armazenados dessa conta quando o receber.
referência de escopos
Refletido a partir do registro de escopos OAuth da plataforma.
| Escopo | Concessões |
|---|---|
menu:read | Read menus, categories and items |
menu:write | Create and update menu items |
orders:read | Read orders and their status |
orders:write | Create and update orders |
analytics:read | Read scan and sales analytics |
restaurant:read | Read restaurant profile and settings |
Eventos de webhook
Eventos aos quais você pode se inscrever hoje:
| Evento |
|---|
order.created |
order.status_changed |
order.paid |
refund.completed |
reservation.created |
reservation.cancelled |
customer.created |
shift.opened |
shift.closed |
menu.updated |
entitlement.changed |
subscription.paused |
subscription.resumed |
subscription.renewed |
subscription.expired |
subscription.plan_changed |
subscription.past_due |
subscription.expiring |
subscription.trial_ending |
app.uninstalled |
Requisitos de listagem e revisão
Antes de um admin aprovar seu app, ele deve:
- Solicitar apenas os escopos que usa, cada um justificado na descrição.
- Fornecer um endpoint de webhook funcional (HTTPS público) se ele se inscrever em eventos.
- Declarar preços precisos — a tabela de preços na sua página de detalhes é gerada a partir deles.
- Incluir um slogan claro, descrição, categoria e pelo menos uma captura de tela.
- Lidar com a desinstalação de forma limpa (revogar acesso, parar cobrança, excluir dados da conta).
Edições de metadados (slogan, descrição, capturas de tela, links) entram no ar imediatamente; mudanças de preço ou escopo recolocam na fila de revisão.
