zrsPOSTroubleshooting
A sale was made but no document appeared. Check the zrsPOS tile's subtitle and Queue & errors. If the sale is queued, wait or press Process all. If it says the store is not configured, finish steps 4 and 5. If you are not live yet, sales are ignored by design.
The receipt did not print. Open the zrsPOS tile → Printer. If it says "to configure", pick this till's printer. For pull printers, the printer's page in the app shows the last contact time; no contact means the printer lost power or network. For direct printers, use Print test and check the router rule.
The print app says "No connection to zrsPOS". The POS device has no internet, or the printer was deleted in the admin (the app then says it was revoked). Check Wi-Fi first; the app retries by itself. See The print app.
Printing stops when the POS device's screen goes off. Open zrsPOS Print and press Allow running in the background (battery), then allow it. Android otherwise stops the app.
The Epson printer has no Server Direct Print option. Check for an Epson firmware update for that model. Otherwise connect the printer by USB to the POS device and use the print app, or switch the printer to Direct. See Step 7 — Printers.
"Store not configured" on a sale. The store's série, document types, warehouse or final-consumer PartyID are missing. Open step 4 and complete them; run Audit SAGE in step 5.
The wrong document type was used for a return. Step 4 lets you choose NC or NRE per store. Change it; future returns use the new choice.
An order was edited after invoicing. zrsPOS raises an alert on Documents and on the order. Correct in SAGE (credit note and new invoice as your accountant advises), then mark the alert handled.
The NIF was rejected. Portuguese NIFs are checked for a valid checksum. For foreign tax numbers, switch on Foreign tax number on the NIF tile.
SAGE is unreachable. Documents queue and retry automatically. Test the connection in step 2; check the firewall allows zrsPOS's address and that the SAGE API service is running.
When SAGE refuses a sale
A sale that SAGE refused shows on the Documents page under Needs attention, with a likely cause and View details — the exact document we sent and SAGE's answer. The causes zrsPOS recognises, and what to do:
"O código do imposto 'NS' utilizado no documento não é válido" (tax code not valid) — on a Tax Free sale. The VAT-exempt group chosen in step 5 (Tax Free → exemption group) resolves, inside your SAGE company, to a tax code and exemption reason that SAGE will not accept on a certified document. The group's name can look right ("Isento Taxfree") while the rule behind it is not. Open the group in SAGE (Tabelas → Impostos → Grupos de IVA) and check which line of the tax table it uses: the combination proven to work on tax-free invoices is code NS with exemption reason M05 (Isento Artigo 14.º do CIVA). If your company only has ISE / M05, use that. After the change, zrsPOS retries the sale by itself within minutes; you can also press Retry now. The deposit item (caução) uses its own group — check it points at the same rule.
"O cliente tem o crédito cancelado" (customer credit cancelled). SAGE refuses every document for a customer whose credit limit type is "cancelled" — a default some SAGE versions apply to customers created from outside. Open the customer in SAGE and set a credit limit by value. The sale retries by itself.
"Série não existe / não válida" (series does not exist). The série configured for the store in step 4 does not exist in SAGE for this document type, or is closed. Check the store's série in step 4 against SAGE's Séries table.
"Artigo não existe" (item does not exist). One of the item codes in step 5 (shipping, generic refund, deposit) is not in SAGE. Run Audit SAGE in step 5; it names the missing one.
"Timed out" — SAGE did not answer in time. SAGE can be slow. The document may have been issued anyway: a retry looks for it before issuing another, so there is no duplicate risk. If it keeps happening, the SAGE server or its network is overloaded.
"Unreachable" — zrsPOS cannot reach SAGE. The SmartAPI service is stopped, or the address or port in step 2 is no longer correct (a router change, a new public IP). Test the connection in step 2.