Crea una app

Las apps amplían la cuenta de un restaurante mediante acceso OAuth limitado y revocable. Tu código se ejecuta en tus servidores; la plataforma mantiene el registro, el libro de instalaciones y los mecanismos de facturación. Esta guía te lleva de cero a una app instalada y con medición.

1. Registra tu app

Crea una app en el panel de partners: nombre, categoría, los ámbitos que necesitas, una URL de webhook opcional y tu modelo de facturación. Al enviarlo se crea un cliente OAuth (client id + secreto) y la app pasa a revisión. Una vez que un administrador la aprueba, aparece en la App Store y se puede instalar.

2. Consigue que se instale

El propietario de un restaurante instala tu app desde su página de detalle en la App Store, concediendo los ámbitos que solicitaste. La instalación crea un AppInstallation y (en apps de pago) cobra el primer periodo a través de su monedero.

3. Llama a la API

Intercambia un token OAuth para la cuenta que instala, luego llama a la REST API con él. Reporta el uso, recibe webhooks o incrusta una página en su panel — cubierto más abajo.

OAuth y tokens

Las apps se autentican con OAuth 2.0 (Laravel Passport). Tus credenciales de cliente provienen del panel de partners. Usa el flujo estándar de código de autorización; el token concedido lleva los ámbitos que el propietario aprobó en la instalación.

# 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"

Los tokens tienen ámbito: una llamada que necesite orders:read falla salvo que el propietario lo haya concedido. Solicita el conjunto mínimo — los revisores lo comprueban.

Tokens de sesión

Para llamadas efímeras de servidor a página embebida, genera un token de sesión desde una instalación activa. Los tokens caducan tras 60 segundos.

GET https://www.menubarcode.comapps/{appId}/session-token
# → { "token": "…", "expires_in": 60 }

Apps embebidas

Si tu app declara una embed_url, la plataforma la aloja en un iframe dentro del panel del propietario en /apps/{appId}/embed. Combínala con un token de sesión (arriba) para autenticar la página embebida sin un ciclo OAuth completo.

Webhooks

Suscríbete a eventos en el de tu app webhook_url. Las entregas se ponen en cola, se reintentan y se firman con el esquema Standard Webhooks usando el secreto de firma de tu app. Tu endpoint debe ser una URL HTTPS pública (sin hosts privados/loopback/metadata) y devolver 2xx rápidamente.

# 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, ... } }

Verifica la firma contra tu secreto antes de confiar en un payload. Consulta la lista de eventos.

Facturación por uso

Las apps facturadas por uso miden el consumo reportando unidades. Cada informe se cobra al monedero del propietario a tu precio por unidad. Pasa un ref único para hacer un informe idempotente (una repetición con la misma ref se ignora).

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

El endpoint devuelve 403 si el token no pertenece a una app registrada o la app no está instalada para la cuenta.

Guías prácticas

Elige un tipo de facturación

• Gratis — sin cargo en la instalación.
• Recurrente — un precio fijo cobrado cada periodo de facturación (por defecto 30 días) del monedero del propietario.
• Según el uso — un precio por unidad facturado a medida que reportas el uso.

Solicita los ámbitos de forma responsable

Solicita solo los ámbitos que usa tu app. Cambiar los ámbitos en un listado activo devuelve la app a revisión. Consulta la referencia de ámbitos.

Limpia al desinstalar

Cuando un propietario desinstala, la plataforma revoca los tokens de la app y dispara un app/uninstalled evento. Detén el trabajo en segundo plano y elimina los datos almacenados de esa cuenta cuando lo recibas.

referencia de ámbitos

Reflejado desde el registro de ámbitos OAuth de la plataforma.

Eventos de webhook

Eventos a los que puedes suscribirte hoy:

Requisitos de listado y revisión

Antes de que un administrador apruebe tu app, esta debe:

• Solicitar solo los ámbitos que usa, cada uno justificado en la descripción.
• Proporcionar un endpoint de webhook funcional (HTTPS público) si se suscribe a eventos.
• Declarar precios exactos — la tabla de precios de tu página de detalle se genera a partir de ellos.
• Incluir un eslogan claro, descripción, categoría y al menos una captura de pantalla.
• Gestionar la desinstalación de forma limpia (revocar acceso, detener facturación, eliminar datos de la cuenta).

Las ediciones de metadatos (eslogan, descripción, capturas, enlaces) se publican de inmediato; los cambios de precio o ámbito vuelven a poner la app en cola de revisión.