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 control | Verified behavior in the application |
|---|---|
| Plan and subscription | Pro plan or higher + Frihet POS app active or in trial (30 days, 25 €/mes / €25/month per active terminal, 1 base terminal included). |
| POS roles | owner, manager, cashier, read_only. |
| Module permissions | sales.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). |
All identifiers below are synthetic examples for documentation testing:
- Business:
Cafetería Puerto Norte S.L.— NIFB12345674(syntactically valid under the official check-digit algorithm; a valid format does not prove existence in the AEAT census) and emailcaja@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, locationBarra Planta Baja, statusactive). - Product 1:
Café especialidad doble(SKU: CAF-001, price3,50 €/€3.50including 10% VAT). - Product 2:
Tostada ibérica(SKU: TOS-002, price6,50 €/€6.50including 10% VAT). - Opening cash float (
openingFloat):150,00 €/€150.00(15000cents).
Step 1: Verify terminal, catalog, and open a cash session
- In
/pos/terminals(terminals.managepermission), verify that terminalCaja Principal Barra(term_barra_01, locationBarra Planta Baja) is listed with statusactive. 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 thecard_externalpayment method. - In
/pos/products(products.read/products.writepermissions), confirm thatCafé especialidad doble(SKU: CAF-001,3,50 €, 10% VAT) andTostada ibérica(SKU: TOS-002,6,50 €, 10% VAT) have their price and tax rate configured infs_pos_products(with code/SKU uniqueness enforced byfs_pos_productIdentityClaims). - In
/pos/cash-sessions(sales.writepermission), selectCaja Principal Barra — Barra Planta Baja, enter the Opening float (€) (Fondo inicial (€))150,00(openingFloat:15000cents), and click Open shift (Abrir turno,posCashSessionOpen). - Verifiable outcome: the server creates the session in
openstatus and acquires the exclusive terminal lock atfp_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
- In
/pos/sales, tapCafé especialidad dobletwice (2 × 3,50 € = 7,00 €) andTostada ibéricaonce (1 × 6,50 € = 6,50 €). The cart total is13,50 €(1350cents: taxable base12,27 €+ 10% VAT1,23 €). - 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, andcustomerAddress); if any is missing, issuance is rejected withrecipient-required.
- Simplified invoice (
- 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.
- Select
cash, enter13,50 €(or20,00 €tendered), and confirm the sale. - 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 (58mmor80mm).
REST API v1 and MCP server equivalence:
- REST API v1: query terminals via
GET /v1/pos/terminals, list sales viaGET /v1/pos/sales, and create sales viaPOST /v1/pos/salesby passing the mandatoryIdempotency-Keyheader matchingclientReferenceIdin the JSON body. @frihet/mcp-server1.17.0: the MCP toolslist_terminals,list_sales, andget_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
- Partial or full refund (
posSaleRefund/POST /v1/pos/sales/:id/refund):- Open
/pos/sales-history, locate the13,50 €sale, and refund1 × Café especialidad doble(3,50 €,350cents) in cash. - The server generates the canonical credit note linked to the original receipt (
creditNoteId,creditNoteHash), updates the sale status topartially_refunded(orrefundedfor a full refund), and increments the session'srefundsCentscounter (350cents). - If the original sale was paid via
card_external, the refund requiresrefundMethod: 'card_external'andexternalCardAttestation, recording the amount undercardRefundsCentswithout touching drawer cash. - For agents connected to
@frihet/mcp-server1.17.0, the equivalent operation is the MCP toolrefund_sale(api_dependent).
- Open
- 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.
- While the shift remains open in
- 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 €(16000cents). - Cash discrepancy (
deltaCents) = Declared cash (declaredCashCents) − Expected cash (computedCashCents). Declaring160,00 €yieldsdeltaCents = 0. - Expected net card (
computedCardCents) = Card sales (cardSalesCents) − External card terminal refunds (cardRefundsCents).
- Expected cash (
- Within the same transaction, the server writes the immutable Z report to
fp_z_reports(zReportId), transitions the session toclosed, deletes the lockfp_cash_session_locks/term_barra_01, and appends thepos_cash_session_closeentry toaudit_log.
- In
Error recovery and frequent cash discrepancies in POS
| Returned code / state | Cause 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-unknown | REST 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. |