Skip to main content

Frihet POS

Frihet POS is the point-of-sale vertical app for Frihet ERP. Designed for hospitality and retail, it offers a flat monthly rate per terminal, zero transaction commissions, and native tax compliance from the very first receipt: VAT or IGIC depending on your fiscal zone, with VeriFactu. VeriFactu also applies to taxpayers with their tax domicile in the Canary Islands: the AEAT includes them in the scope of RD 1007/2023 and reads references to VAT as references to IGIC (AEAT FAQ). With the Canary Islands fiscal zone, submitting the records to the AEAT is not available in Frihet.

How it works​

Each POS terminal is an active device in your account—a tablet, computer, or Stripe Terminal reader—from which you sell to in-person customers. The workflow is straightforward: the cashier selects products from the catalog, applies discounts or coupons if applicable, collects payment (cash, card, bank transfer), and issues the simplified receipt or full invoice on the spot.

Invoicing runs through the ERP's tax engine. Every sale generates a compliant tax document: a simplified receipt with an optional tax ID (NIF) or a full invoice if requested by the customer, with IGIC in the Canary Islands. The VeriFactu record of the sale is submitted to the AEAT automatically if you enable Auto-submit to AEAT and have a valid digital certificate configured in Finance → Taxes → Compliance. With Test mode (sandbox) on, the submission goes to the AEAT test environment. VAT/IGIC treatment is applied automatically based on your business's tax zone with no extra configuration required.

Cash register sessions group sales, refunds, and cash movements by shift. Every sale or refund records its canonical invoice or credit note in the ERP fiscal ledger, while closing the shift runs an atomic server-side reconciliation (posCashSessionClose / POST /v1/pos/cash-sessions/:id/close), issues the fiscal Z report (fp_z_reports), releases the terminal lock (fp_cash_session_locks), and writes a trace in audit_log (pos_cash_session_close). Refunds remain linked to the original receipt for auditing.

If you connect a compatible Stripe Terminal reader, the POS uses it for in-person card payments without requiring proprietary POS hardware. The product catalog is shared directly with the ERP—any items you add, edit, or remove in Sales → Products are reflected immediately at the point of sale.

Configuration​

Activate the app from Settings → Frihet Apps (POS card) in your Frihet ERP account. Activation includes a trial period before switching to the paid subscription. Pricing is a flat monthly fee per active terminal, with no additional commission on transactions.

Each terminal is paired from the end device by signing in with the corresponding cashier's account. Cashiers are managed as team members under Invite members with the appropriate POS role.

For restaurants and cafés, you will typically activate Frihet Kitchen alongside POS to orchestrate orders and kitchen stations.

Operational walkthrough: from opening a shift to charging, refunding, and reconciling the Z close​

This walkthrough covers a complete counter shift in Frihet POS: verifying fiscal readiness and the terminal, opening a cash session with an opening float, charging an in-person sale, recording a partial refund with a canonical credit note, and executing the server-side cash count and Z report close.

Requirement or controlVerified behavior in the application
Plan and subscriptionPro plan or higher + Frihet POS app active or in trial (30 days, 25 €/mes / €25/month per active terminal, 1 base terminal included).
POS rolesowner, manager, cashier, read_only.
Module permissionssales.read, sales.write, products.read, products.write, terminals.manage.
Fiscal readiness (usePosFiscalReadiness)Complete tax profile under Settings → Tax Profile (tax ID/NIF, legal name, and fiscal address) and an active invoice series; if missing, the PosFiscalReadinessNotice banner prevents opening a session (fiscal-profile-incomplete).
Operational module routes/pos/sales (counter), /pos/sales-history (history and refunds), /pos/cash-sessions (shifts and Z reports), /pos/products (POS catalog), and /pos/terminals (terminals and readers).
Deterministic synthetic dataset for this walkthrough

All identifiers below are synthetic examples for documentation testing:

  • Business: Cafetería Puerto Norte S.L. — NIF B12345674 (syntactically valid under the official check-digit algorithm; a valid format does not prove existence in the AEAT census) and email caja@example.com (domain reserved by IANA under RFC 6761 for documentation; not a controlled QA mailbox or a guarantee that prevents email delivery).
  • Terminal: Caja Principal Barra (term_barra_01, location Barra Planta Baja, status active).
  • Product 1: Café especialidad doble (SKU: CAF-001, price 3,50 € / €3.50 including 10% VAT).
  • Product 2: Tostada ibérica (SKU: TOS-002, price 6,50 € / €6.50 including 10% VAT).
  • Opening cash float (openingFloat): 150,00 € / €150.00 (15000 cents).

Step 1: Verify terminal, catalog, and open a cash session​

  1. In /pos/terminals (terminals.manage permission), verify that terminal Caja Principal Barra (term_barra_01, location Barra Planta Baja) is listed with status active. If you use a physical Stripe Terminal reader, link it to the location via Discover readers (Descubrir lectores); if you charge through a standalone bank card terminal, use the card_external payment method.
  2. In /pos/products (products.read / products.write permissions), confirm that Café especialidad doble (SKU: CAF-001, 3,50 €, 10% VAT) and Tostada ibérica (SKU: TOS-002, 6,50 €, 10% VAT) have their price and tax rate configured in fs_pos_products (with code/SKU uniqueness enforced by fs_pos_productIdentityClaims).
  3. In /pos/cash-sessions (sales.write permission), select Caja Principal Barra — Barra Planta Baja, enter the Opening float (€) (Fondo inicial (€)) 150,00 (openingFloat: 15000 cents), and click Open shift (Abrir turno, posCashSessionOpen).
  4. Verifiable outcome: the server creates the session in open status and acquires the exclusive terminal lock at fp_cash_session_locks/term_barra_01, preventing another browser tab or cashier from opening a concurrent shift on the same register.

Step 2: Record an in-person sale and issue a simplified receipt or full invoice​

  1. In /pos/sales, tap Café especialidad doble twice (2 × 3,50 € = 7,00 €) and Tostada ibérica once (1 × 6,50 € = 6,50 €). The cart total is 13,50 € (1350 cents: taxable base 12,27 € + 10% VAT 1,23 €).
  2. Fiscal document type:
    • Simplified invoice (F2): default counter receipt mode.
    • Full invoice (F1, Art. 6.1 RD 1619/2012): when the customer requests a full invoice or the sale exceeds the regulatory simplified-invoice threshold, the server requires all three recipient fields (customerNif, customerName, and customerAddress); if any is missing, issuance is rejected with recipient-required.
  3. Supported payment methods in posSaleCreate (POST /v1/pos/sales):
    • cash: physical drawer cash; requires the tendered amount (cashTendered, e.g. 20,00 €) and computes the change due (6,50 €).
    • card / stripe_terminal: integrated card payment via a paired Stripe Terminal reader.
    • card_external: standalone bank card terminal; requires explicit operator confirmation (externalCardAttestation: { approved: true, approvalCode }) and records the card sale without adding to or subtracting from drawer cash.
    • mixed: split payment specifying the cash portion (mixedCashCents) and charging the remainder to card.
    • transfer: confirmed bank transfer.
  4. Select cash, enter 13,50 € (or 20,00 € tendered), and confirm the sale.
  5. What to verify after charging: the issued receipt displays the sequential sale number (saleNumber), the chained VeriFactu fingerprint (fiscalHash), the verifiable tax QR code (qrUrl), and the thermal print layout (58mm or 80mm).

REST API v1 and MCP server equivalence:

  • REST API v1: query terminals via GET /v1/pos/terminals, list sales via GET /v1/pos/sales, and create sales via POST /v1/pos/sales by passing the mandatory Idempotency-Key header matching clientReferenceId in the JSON body.
  • @frihet/mcp-server 1.17.0: the MCP tools list_terminals, list_sales, and get_sale (api_dependent) let agents inspect active terminals and audit issued receipts.

Step 3: Tracked refund, mid-shift cash count, and shift close with Z report​

  1. Partial or full refund (posSaleRefund / POST /v1/pos/sales/:id/refund):
    • Open /pos/sales-history, locate the 13,50 € sale, and refund 1 × Café especialidad doble (3,50 €, 350 cents) in cash.
    • The server generates the canonical credit note linked to the original receipt (creditNoteId, creditNoteHash), updates the sale status to partially_refunded (or refunded for a full refund), and increments the session's refundsCents counter (350 cents).
    • If the original sale was paid via card_external, the refund requires refundMethod: 'card_external' and externalCardAttestation, recording the amount under cardRefundsCents without touching drawer cash.
    • For agents connected to @frihet/mcp-server 1.17.0, the equivalent operation is the MCP tool refund_sale (api_dependent).
  2. Mid-shift cash audit (posCashSessionAuditEntry):
    • While the shift remains open in /pos/cash-sessions, a manager can log an intermediate cash count (countedCashCents) with an audit note without closing the session or releasing the terminal lock.
  3. Shift close and Z report (closeCashSessionCore / posCashSessionClose / POST /v1/pos/cash-sessions/:id/close):
    • In /pos/cash-sessions, enter the counted cash directly on the active session row or open the Blind denomination count modal (BlindCashCountModal) to count coins and bills before viewing the expected balance.
    • The engine runs a single atomic server transaction applying the exact reconciliation formulas:
      • Expected cash (computedCashCents) = Opening float (openingFloatCents) + Cash sales (cashSalesCents) − Cash refunds (refundsCents).
      • In our example: 150,00 € + 13,50 € - 3,50 € = 160,00 € (16000 cents).
      • Cash discrepancy (deltaCents) = Declared cash (declaredCashCents) − Expected cash (computedCashCents). Declaring 160,00 € yields deltaCents = 0.
      • Expected net card (computedCardCents) = Card sales (cardSalesCents) − External card terminal refunds (cardRefundsCents).
    • Within the same transaction, the server writes the immutable Z report to fp_z_reports (zReportId), transitions the session to closed, deletes the lock fp_cash_session_locks/term_barra_01, and appends the pos_cash_session_close entry to audit_log.

Error recovery and frequent cash discrepancies in POS​

Returned code / stateCause in the POS engine (pos.ts / httpsErrorToI18nKey)Verified recovery action
fiscal-profile-incomplete (409 FISCAL_PROFILE_INCOMPLETE)Missing tax ID (NIF/CIF), legal name, fiscal address, or active invoice series.Complete the details under Settings → Tax Profile and verify your series under Settings → Billing → Invoice Series before opening a shift or charging.
fiscal-chain-blocked (409 FISCAL_CHAIN_BLOCKED) / numbering-conflict (409 NUMBERING_CONFLICT)The last VeriFactu record belongs to a non-matching issuer NIF or the sequential number already exists; the engine fails closed without numbering or charging.Verify the issuer NIF, active series, and certificate under Finance → Taxes → Compliance before retrying the sale.
recipient-required (400 RECIPIENT_REQUIRED)Sale marked as a full invoice (F1) without customerNif, customerName, or customerAddress.Provide all three mandatory recipient fields under Art. 6.1 RD 1619/2012, or switch to a simplified invoice (F2) when permitted.
MISSING_IDEMPOTENCY_KEY / IDEMPOTENCY_KEY_MISMATCH (400) or pos-outcome-unknownREST request missing an Idempotency-Key header matching clientReferenceId, or network drop during charge/close.In REST requests, always send Idempotency-Key === clientReferenceId. In the web UI, the client reconciles via read queries (reconcilePosSale, reconcilePosRefund, reconcilePosClose) without duplicating the charge.
deltaCents !== 0 in the Z report or malformed-session (409 MALFORMED_SESSION)Difference between declaredCashCents and computedCashCents, or external card terminal sales mistakenly recorded as cash.Audit /pos/sales-history to compare cash vs card_external receipts, and inspect the pos_cash_session_close event in audit_log alongside the fp_z_reports document.

See also​