API
El pos-backend (Express + TypeScript, puerto 3005) es la API central del ecosistema. La especificación completa vive en docs/api/openapi.yaml (OpenAPI 3.0.3, v2.0.0) y se sirve de forma interactiva con Swagger UI.
Swagger UI (interactivo)
https://api.ifondita.com/api-docs/
La UI es pública (sin auth, es documentación de desarrollo), lista todos los endpoints reales del pos-backend y permite probarlos. Se genera leyendo docs/api/openapi.yaml, que a su vez se regeneró desde el código real de los routers (src/routes/*) y su montaje en src/index.ts, post-Bloque B.
- 262 paths · 312 operaciones
- Cada operación anota su auth real (
requireRestaurant,requireRole(...),hasPermission(...),requireFogonAuth,requireAdvertiser,requirePlatformAdmin,requireAprovechoAuth). - Endpoints stubbeados (501) o diferidos a Nivel 2 (webhooks delivery, device-pairing) marcados como
deprecated.
Convenciones
- Rutas protegidas exigen
Authorization: Bearer <JWT>. - El
pos-backendconecta a Supabase comoservice_role(bypassa RLS) y aísla porrestaurant_idextraído del JWT. - Contrato del dinero: el cobro escribe
orders.payment_details(jsonb) conlines[]de métodos-hoja (cash | card | transfer | online);mixedsólo es etiqueta top-level. Ver Arquitectura y Base de datos. - IVA incluido en los precios del menú.
Superficies principales (tags)
| Área | Prefijo | Auth |
|---|---|---|
| POS · Órdenes | /api/orders | requireRestaurant + requireRole(duena,mesero,cocina,caja) |
| POS · Cobro (método único) | /api/orders/{orderId}/pay · /api/payments | requireRestaurant + requireRole(duena,caja,mesero) |
| POS · Pago mixto | /api/payments/mixed | requireRestaurant + requireRole(duena,caja) |
| POS · Caja | /api/cash | requireRestaurant + requireRole(duena,caja) |
| POS · Cocina (KDS) | /api/orders/kitchen | requireRestaurant + requireRole(duena,cocina) |
| Menú / Modificadores | /api/menu | requireRestaurant + requireRole(duena,mesero) |
| Auth · Owner (Supabase) | /api/restaurant/auth | Mixto (login/setup públicos) |
| Fogón (BI interno) | /api/fogon/* | requireFogonAuth |
| Anunciantes | /api/advertisers · /api/anunciantes | requireAdvertiser |
| Aprovecho (comensal) | /api/aprovecho | Mixto (requireAprovechoAuth) |
Para el detalle de request/response de cada endpoint, usa el Swagger UI enlazado arriba — es la referencia viva.