Saltar al contenido principal

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 controlDetalle verificado en la aplicación
Plan y suscripciónPlan 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 POSowner, manager, cashier, read_only.
Permisos del módulosales.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).
Dataset sintético determinista para el recorrido

Todos los identificadores siguientes son sintéticos para pruebas de documentación:

  • Negocio: Cafetería Puerto Norte S.L. — NIF B12345674 (sintácticamente válido según el algoritmo oficial; el formato válido no acredita existencia en el censo de la AEAT) y correo caja@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ón Barra Planta Baja, estado active).
  • Producto 1: Café especialidad doble (SKU: CAF-001, precio 3,50 € con IVA 10 % incluido).
  • Producto 2: Tostada ibérica (SKU: TOS-002, precio 6,50 € con IVA 10 % incluido).
  • Fondo inicial de caja (openingFloat): 150,00 € (15000 céntimos).

Paso 1: Verificar terminal, catálogo y abrir sesión de caja​

  1. En /pos/terminals (permiso terminals.manage), comprueba que la terminal Caja Principal Barra (term_barra_01, ubicación Barra Planta Baja) aparece en estado active. 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étodo card_external.
  2. En /pos/products (permisos products.read / products.write), verifica que Café especialidad doble (SKU: CAF-001, 3,50 €, IVA 10 %) y Tostada ibérica (SKU: TOS-002, 6,50 €, IVA 10 %) tienen precio e impuesto asignados en fs_pos_products (con unicidad de código/SKU protegida por fs_pos_productIdentityClaims).
  3. En /pos/cash-sessions (permiso sales.write), selecciona la terminal Caja Principal Barra — Barra Planta Baja, introduce el Fondo inicial (€) 150,00 (openingFloat: 15000 céntimos) y pulsa Abrir turno (posCashSessionOpen).
  4. Resultado verificable: el servidor crea la sesión en estado open y adquiere el candado exclusivo de la terminal en fp_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​

  1. En /pos/sales, pulsa sobre Café especialidad doble dos veces (2 × 3,50 € = 7,00 €) y sobre Tostada ibérica una vez (1 × 6,50 € = 6,50 €). El carrito muestra un total de 13,50 € (1350 céntimos, base imponible 12,27 € + IVA 10 % 1,23 €).
  2. 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, customerName y customerAddress); si falta cualquiera de ellos, rechaza la emisión con recipient-required.
  3. Método de cobro en posSaleCreate (POST /v1/pos/sales):
    • cash: efectivo en cajón; requiere indicar el importe entregado (cashTendered, por ejemplo 20,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.
  4. Selecciona cash, introduce 13,50 € (o 20,00 € entregados) y confirma el cobro.
  5. 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 (58mm u 80mm).

Equivalencia por API REST v1 y servidor MCP:

  • API REST v1: consulta terminales con GET /v1/pos/terminals, lista ventas con GET /v1/pos/sales y registra ventas con POST /v1/pos/sales enviando obligatoriamente la cabecera Idempotency-Key con el mismo valor que clientReferenceId en el cuerpo JSON.
  • Servidor @frihet/mcp-server 1.17.0: las herramientas MCP list_terminals, list_sales y get_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​

  1. Devolución parcial o total (posSaleRefund / POST /v1/pos/sales/:id/refund):
    • Abre /pos/sales-history, localiza la venta de 13,50 € y solicita la devolución de 1 × Café especialidad doble (3,50 €, 350 céntimos) en efectivo.
    • El servidor emite la factura rectificativa canónica vinculada al ticket original (creditNoteId, creditNoteHash), actualiza el estado de la venta a partially_refunded (o refunded si se devuelve el total) e incrementa el acumulado refundsCents de la sesión (350 céntimos).
    • Si la venta original se cobró con card_external, la devolución exige refundMethod: 'card_external' y externalCardAttestation, acumulándose en cardRefundsCents sin alterar el efectivo esperado del cajón.
    • Desde agentes conectados a @frihet/mcp-server 1.17.0, esta operación corresponde a la herramienta MCP refund_sale (api_dependent).
  2. 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.
  3. 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 € (16000 céntimos).
      • Descuadre de efectivo (deltaCents) = Efectivo declarado (declaredCashCents) − Efectivo esperado (computedCashCents). Si declaras 160,00 €, deltaCents = 0.
      • Tarjeta neta esperada (computedCardCents) = Ventas con tarjeta (cardSalesCents) − Devoluciones en datáfono externo (cardRefundsCents).
    • En la misma transacción, el servidor persiste el informe Z inmutable en fp_z_reports (zReportId), cambia la sesión a closed, elimina el bloqueo fp_cash_session_locks/term_barra_01 y escribe el evento pos_cash_session_close en audit_log.

Recuperación ante errores y descuadres frecuentes en POS​

Código / estado devueltoCausa 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-unknownLlamada 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.

Ver también​