Frihet POS
Frihet POS es la app vertical de punto de venta de Frihet ERP. Está pensada para restauración y retail, con tarifa plana mensual por terminal, sin comisiones sobre transacciones y cumplimiento fiscal nativo desde el primer ticket: IVA o IGIC según tu zona fiscal, con VeriFactu. VeriFactu también se aplica a los contribuyentes con domicilio fiscal en Canarias: la AEAT los incluye en el ámbito del RD 1007/2023 y entiende hechas al IGIC las referencias al IVA (preguntas frecuentes de la AEAT). Con la zona fiscal Canarias, el envío de los registros a la AEAT no está disponible en Frihet.
Cómo funciona
Cada terminal POS es un dispositivo activo en tu cuenta — tablet, ordenador o lector Stripe Terminal — desde el que vendes a clientes presenciales. El flujo es directo: el cajero selecciona productos del catálogo, aplica descuentos o cupones si procede, cobra al cliente (efectivo, tarjeta, transferencia) y emite el ticket o factura simplificada en el acto.
La facturación viaja por el motor fiscal del ERP. Cada venta genera un documento conforme a la normativa aplicable: ticket simplificado con NIF opcional o factura completa si el cliente lo pide, con IGIC en Canarias. El registro VeriFactu de la venta se envía automáticamente a la AEAT si activas Envío automático a AEAT y tienes un certificado digital válido configurado en Finanzas → Fiscal → Cumplimiento. Con Modo pruebas (sandbox) activo, el envío va al entorno de pruebas de la AEAT. El tratamiento del IVA/IGIC se aplica según la zona fiscal de tu negocio sin configuración extra.
Las sesiones de caja agrupan ventas, devoluciones y movimientos en efectivo por turno. Cada venta o devolución registra su factura o factura rectificativa canónica en el libro fiscal del ERP, mientras que al cerrar el turno la sesión de caja ejecuta una conciliación atómica en servidor (posCashSessionClose / POST /v1/pos/cash-sessions/:id/close), emite el informe Z fiscal (fp_z_reports), libera el bloqueo de la terminal (fp_cash_session_locks) y deja rastro en audit_log (pos_cash_session_close). Las devoluciones quedan trazadas con el ticket original para auditoría.
Si conectas un lector Stripe Terminal compatible, el POS lo usa para cobros con tarjeta presencial sin necesidad de hardware propietario. El catálogo de productos es el mismo del ERP — añades, editas o quitas referencias desde Ventas → Catálogo y se reflejan al instante en el TPV.
Configuración
Activa la app desde Ajustes → Frihet Apps (tarjeta POS) en tu cuenta Frihet ERP. La activación incluye un periodo de prueba antes de pasar al plan suscrito. La tarifa es plana por terminal activa al mes, sin comisión adicional sobre transacciones.
Cada terminal se vincula desde el dispositivo final iniciando sesión con la cuenta del cajero correspondiente. Los cajeros se gestionan como miembros del equipo desde Invitar miembros con el rol adecuado para POS.
Para hostelería, normalmente activarás Frihet Kitchen junto al POS para orquestar pedidos y estaciones de cocina.
Recorrido operativo: de abrir turno a cobrar, devolver y cuadrar el cierre Z
Este recorrido cubre un turno completo de mostrador en Frihet POS: verificar la preparación fiscal y la terminal, abrir sesión de caja con fondo inicial, cobrar una venta presencial, registrar una devolución parcial con factura rectificativa canónica y ejecutar el arqueo y cierre Z en el servidor.
| Requisito o control | Detalle verificado en la aplicación |
|---|---|
| Plan y suscripción | Plan Pro o superior + app Frihet POS activa o en periodo de prueba (30 días, 25 €/mes por terminal activa, 1 terminal incluida en la base). |
| Roles de POS | owner, manager, cashier, read_only. |
| Permisos del módulo | sales.read, sales.write, products.read, products.write, terminals.manage. |
Preparación fiscal (usePosFiscalReadiness) | Perfil fiscal completo en Ajustes → Perfil Fiscal (NIF/CIF, razón social y dirección fiscal) y serie de facturación activa; si falta algún dato, el aviso PosFiscalReadinessNotice impide abrir sesión (fiscal-profile-incomplete). |
| Rutas operativas del módulo | /pos/sales (mostrador), /pos/sales-history (historial y devoluciones), /pos/cash-sessions (turnos e informe Z), /pos/products (catálogo POS) y /pos/terminals (terminales y lectores). |
Todos los identificadores siguientes son sintéticos para pruebas de documentación:
- Negocio:
Cafetería Puerto Norte S.L.— NIFB12345674(sintácticamente válido según el algoritmo oficial; el formato válido no acredita existencia en el censo de la AEAT) y correocaja@example.com(dominio reservado por IANA según RFC 6761 para documentación; no es un buzón de QA controlado ni una garantía de impedir envíos). - Terminal:
Caja Principal Barra(term_barra_01, ubicaciónBarra Planta Baja, estadoactive). - Producto 1:
Café especialidad doble(SKU: CAF-001, precio3,50 €con IVA 10 % incluido). - Producto 2:
Tostada ibérica(SKU: TOS-002, precio6,50 €con IVA 10 % incluido). - Fondo inicial de caja (
openingFloat):150,00 €(15000céntimos).
Paso 1: Verificar terminal, catálogo y abrir sesión de caja
- En
/pos/terminals(permisoterminals.manage), comprueba que la terminalCaja Principal Barra(term_barra_01, ubicaciónBarra Planta Baja) aparece en estadoactive. Si utilizas un lector físico de Stripe Terminal, vincúlalo a la ubicación mediante Descubrir lectores; si cobras con un datáfono bancario independiente del TPV, operarás con el métodocard_external. - En
/pos/products(permisosproducts.read/products.write), verifica queCafé especialidad doble(SKU: CAF-001,3,50 €, IVA 10 %) yTostada ibérica(SKU: TOS-002,6,50 €, IVA 10 %) tienen precio e impuesto asignados enfs_pos_products(con unicidad de código/SKU protegida porfs_pos_productIdentityClaims). - En
/pos/cash-sessions(permisosales.write), selecciona la terminalCaja Principal Barra — Barra Planta Baja, introduce el Fondo inicial (€)150,00(openingFloat:15000céntimos) y pulsa Abrir turno (posCashSessionOpen). - Resultado verificable: el servidor crea la sesión en estado
openy adquiere el candado exclusivo de la terminal enfp_cash_session_locks/term_barra_01, impidiendo que otro navegador o cajero abra un segundo turno simultáneo sobre la misma caja.
Paso 2: Registrar venta presencial y emitir ticket o factura completa
- En
/pos/sales, pulsa sobreCafé especialidad dobledos veces (2 × 3,50 € = 7,00 €) y sobreTostada ibéricauna vez (1 × 6,50 € = 6,50 €). El carrito muestra un total de13,50 €(1350céntimos, base imponible12,27 €+ IVA 10 %1,23 €). - Tipo de documento fiscal:
- Factura simplificada (
F2): modalidad por defecto en ventas de mostrador. - Factura completa (
F1, art. 6.1 RD 1619/2012): cuando el cliente solicita factura nominativa o la operación supera el umbral reglamentario de factura simplificada, el servidor exige informar los tres datos del destinatario (customerNif,customerNameycustomerAddress); si falta cualquiera de ellos, rechaza la emisión conrecipient-required.
- Factura simplificada (
- Método de cobro en
posSaleCreate(POST /v1/pos/sales):cash: efectivo en cajón; requiere indicar el importe entregado (cashTendered, por ejemplo20,00 €) y calcula el cambio a devolver (6,50 €).card/stripe_terminal: cobro integrado mediante lector Stripe Terminal conectado a la sesión.card_external: datáfono bancario externo; exige confirmación expresa del operador (externalCardAttestation: { approved: true, approvalCode }) y registra el cobro en las ventas con tarjeta sin sumar ni restar efectivo del cajón.mixed: cobro combinado indicando la parte en efectivo (mixedCashCents) y el resto en tarjeta.transfer: transferencia bancaria confirmada.
- Selecciona
cash, introduce13,50 €(o20,00 €entregados) y confirma el cobro. - Qué comprobar tras cobrar: el recibo emitido muestra el número secuencial correlativo (
saleNumber), la huella encadenada VeriFactu (fiscalHash), el código QR tributario verificable (qrUrl) y el formato de impresión térmica seleccionable (58mmu80mm).
Equivalencia por API REST v1 y servidor MCP:
- API REST v1: consulta terminales con
GET /v1/pos/terminals, lista ventas conGET /v1/pos/salesy registra ventas conPOST /v1/pos/salesenviando obligatoriamente la cabeceraIdempotency-Keycon el mismo valor queclientReferenceIden el cuerpo JSON. - Servidor
@frihet/mcp-server1.17.0: las herramientas MCPlist_terminals,list_salesyget_sale(api_dependent) permiten inspeccionar terminales activas y auditar el detalle de cada ticket emitido.
Paso 3: Devolución trazada, arqueo intermedio y cierre de turno con informe Z
- Devolución parcial o total (
posSaleRefund/POST /v1/pos/sales/:id/refund):- Abre
/pos/sales-history, localiza la venta de13,50 €y solicita la devolución de1 × Café especialidad doble(3,50 €,350céntimos) en efectivo. - El servidor emite la factura rectificativa canónica vinculada al ticket original (
creditNoteId,creditNoteHash), actualiza el estado de la venta apartially_refunded(orefundedsi se devuelve el total) e incrementa el acumuladorefundsCentsde la sesión (350céntimos). - Si la venta original se cobró con
card_external, la devolución exigerefundMethod: 'card_external'yexternalCardAttestation, acumulándose encardRefundsCentssin alterar el efectivo esperado del cajón. - Desde agentes conectados a
@frihet/mcp-server1.17.0, esta operación corresponde a la herramienta MCPrefund_sale(api_dependent).
- Abre
- Arqueo intermedio (
posCashSessionAuditEntry):- Con el turno abierto en
/pos/cash-sessions, el encargado puede registrar un recuento parcial de efectivo (countedCashCents) con nota de supervisión sin cerrar la sesión ni liberar la terminal.
- Con el turno abierto en
- Cierre de turno e informe Z (
closeCashSessionCore/posCashSessionClose/POST /v1/pos/cash-sessions/:id/close):- En
/pos/cash-sessions, introduce el efectivo contado directamente en la fila de la sesión activa o abre el modal de Arqueo ciego por denominaciones (BlindCashCountModal) para contar monedas y billetes antes de ver el saldo teórico. - El motor ejecuta una transacción atómica en servidor aplicando las fórmulas exactas de cuadre:
- Efectivo esperado (
computedCashCents) = Fondo inicial (openingFloatCents) + Ventas en efectivo (cashSalesCents) − Devoluciones en efectivo (refundsCents). - Con los datos del recorrido:
150,00 € + 13,50 € - 3,50 € = 160,00 €(16000céntimos). - Descuadre de efectivo (
deltaCents) = Efectivo declarado (declaredCashCents) − Efectivo esperado (computedCashCents). Si declaras160,00 €,deltaCents = 0. - Tarjeta neta esperada (
computedCardCents) = Ventas con tarjeta (cardSalesCents) − Devoluciones en datáfono externo (cardRefundsCents).
- Efectivo esperado (
- En la misma transacción, el servidor persiste el informe Z inmutable en
fp_z_reports(zReportId), cambia la sesión aclosed, elimina el bloqueofp_cash_session_locks/term_barra_01y escribe el eventopos_cash_session_closeenaudit_log.
- En
Recuperación ante errores y descuadres frecuentes en POS
| Código / estado devuelto | Causa en el motor POS (pos.ts / httpsErrorToI18nKey) | Acción de recuperación verificada |
|---|---|---|
fiscal-profile-incomplete (409 FISCAL_PROFILE_INCOMPLETE) | Falta NIF/CIF, razón social, dirección fiscal o serie de facturación activa. | Completa los datos en Ajustes → Perfil Fiscal y verifica las series en Ajustes → Facturación → Series de Facturación antes de abrir turno o cobrar. |
fiscal-chain-blocked (409 FISCAL_CHAIN_BLOCKED) / numbering-conflict (409 NUMBERING_CONFLICT) | El último registro VeriFactu pertenece a un NIF emisor distinto o el correlativo ya existe; el motor opera en modo fail-closed sin numerar ni cobrar. | Revisa el NIF del emisor, la serie activa y el certificado en Finanzas → Fiscal → Cumplimiento antes de repetir el cobro. |
recipient-required (400 RECIPIENT_REQUIRED) | Venta marcada como factura completa (F1) sin customerNif, customerName o customerAddress. | Completa los tres campos obligatorios del destinatario conforme al art. 6.1 del RD 1619/2012 o cambia a factura simplificada (F2) si la operación lo permite. |
MISSING_IDEMPOTENCY_KEY / IDEMPOTENCY_KEY_MISMATCH (400) o pos-outcome-unknown | Llamada REST sin cabecera Idempotency-Key coincidente con clientReferenceId, o corte de red durante el cobro/cierre. | En REST envía siempre Idempotency-Key === clientReferenceId. En la interfaz web, el cliente reconcilia mediante lectura (reconcilePosSale, reconcilePosRefund, reconcilePosClose) sin duplicar el cobro. |
deltaCents !== 0 en el informe Z o malformed-session (409 MALFORMED_SESSION) | Diferencia entre declaredCashCents y computedCashCents, o cobros en datáfono externo registrados por error como cash. | Audita en /pos/sales-history qué tickets se emitieron como cash frente a card_external y revisa la traza pos_cash_session_close en audit_log junto con el documento de fp_z_reports. |