Best Practices

These are the rules that separate integrations that run for years from integrations that page their developers at month-end. Each one is a lesson learned from production EFRIS deployments.

Critical rules

1. Always register first: never fiscalise a sale with an itemCode that hasn't been registered.
2. No auto-retry on invoices: if fiscalisation times out, check whether the invoice was already fiscalised with POST /invoice-details before trying again. Duplicate fiscalisation means double tax. EFRIS can also be asked to reject duplicates of your referenceNo.
3. Stock before sale: make sure stock is increased before selling, or allow negative stock in your URA portal settings.
4. Packaging consistency: if a good was registered with piece packaging, keep the packaging details and quantities on your invoices consistent with that registration so URA's stock decrements correctly.
5. Exact field names: send field names exactly as documented - invoiceNo, buyerTin, goodsCode, sourceBranchId, deemedFlag, vatProjectId, totalWeight, hsCode.
6. Amount consistency: the tax lines and totals on an invoice must add up. An invoice whose figures don't reconcile will not be accepted.

Recommended integration checklist

• Cache the system dictionary and commodity categories locally, and refresh them periodically.
• Store invoiceId, invoiceNo (FDN), antifakeCode, and qrCode against every ERP invoice record - see Invoice Response.
• Log the full request and response of every API call. When URA support asks "what did you send?", you want an answer.
• Treat a rejection from URA as a business issue to show the user, not as a temporary failure to retry.
• Run a daily reconciliation: compare your ERP's fiscalised invoices against POST /query-invoices for the same date range.