Invoice Standardization

The platform standardises invoices from any ERP format into the NRS-mandated schema before transmission to FIRS. This section explains how that standardisation works and what it requires from your ERP.

---

The NRS Dictionary

The platform uses an NRS Dictionary — a centrally managed mapping table that defines:

• Every field NRS/FIRS expects in a submitted invoice
• Which fields are mandatory vs. optional
• Data type and format constraints per field
• Which fields require encryption at rest (e.g. payment terms notes, invoice notes)
• How fields in your ERP map to NRS field names

The dictionary is maintained by the Super Admin at the system level (/admin/system/nrs-dictionary) and updated whenever NRS/FIRS releases schema changes. Tenants do not manage it directly — the platform applies it automatically during the Transform stage.

---

Supported Input Formats

The middleware accepts invoices in the native format of your ERP:

ERP	Accepted Format
SAP	IDOC / XML
Oracle	XML
Xero, QuickBooks, Zoho, Wave, FreshBooks	JSON
Odoo	JSON / XML
Sage, Dynamics, NetSuite	XML / JSON
FIRS UBL, Peppol BIS, UBL 2.1	XML (UBL)
Custom	JSON or XML (configured per tenant)

---

Output Format

All invoices are submitted to NRS/FIRS in UBL 2.1 (Universal Business Language) format, digitally signed with the tenant's NRS-issued certificate and private key.

---

The invoiceIdKey

Each tenant must configure an invoiceIdKey — the dot-notation path within their ERP's invoice payload that contains the unique invoice identifier. When the platform receives an invoice via the inbound webhook, it uses this key to extract and store the invoice ID from the payload body.

Examples:

"invoiceNumber"          → looks up payload.invoiceNumber
"invoice.documentId"     → looks up payload.invoice.documentId
"header.ref"             → looks up payload.header.ref

This is configured once during onboarding via:

PUT /v1/tenants/{tenantId}/invoice-id-key

---

Mandatory Fields (NRS/FIRS Requirements)

While the full field list is defined in the NRS Dictionary, the following are always required:

Category	Required
Supplier identity	Business Name, TIN, Business Registration Number
Buyer identity	Name, TIN (where applicable)
Invoice header	Invoice number, issue date, due date, currency
Line items	Description, quantity, unit price, tax rate
Totals	Subtotal, VAT total, grand total

---

Auto-Fix

If features.autoFix is enabled on your tenant, the middleware will attempt to automatically correct minor schema issues (e.g. formatting dates, trimming whitespace, coercing numeric strings) before validation. This reduces failed invoices due to ERP formatting quirks.

Configure via PATCH /v1/tenants/{tenantId}:

{
  "features": {
    "autoFix": true,
    "maxRetries": 3
  }
}