6.1 The Challenge of Data Alignment
The FIRS MBS platform enforces strict validation on invoice payloads. Every header, line item, tax code, and reference must align precisely with regulator specifications.
Field Naming Conflicts
ERP fields named differently from FIRS requirements, causing mapping failures and rejections.
Mandatory vs Optional
Optional fields in ERP that are mandatory for FIRS, creating compliance gaps.
Tax Code Misalignment
Tax code libraries that don't align with regulator codes, causing validation errors.
Business Impact
Failure to map correctly results in rejected invoices, delayed collections, and compliance risk.
6.2 Our Canonical Data Model
To solve this, Softrust and Bluelight enforce a canonical schema within <BluelightSmartAPI>. This schema is stable, versioned, and designed to remain constant even as FIRS updates its rules.
Canonical Model Features
- Header Section – document ID, invoice number, supplier TIN, buyer TIN, company code, issue date, plant, currency, totals.
- Line Items – line number, description, quantity, unit price, tax code, line amount.
- Taxation – VAT, zero-rated, exempt codes, mapped consistently to regulator taxonomy.
Extended Attributes
- References – order numbers, delivery notes, customer IDs.
- Metadata – source system identifier, correlation ID, IDoc number or API request ID.
- Compliance Data – HS codes, service classifications, regulatory flags.
6.3 Mapping from ERP and Billing Systems
SAP ECC
- IDoc INVOIC02 segments (E1EDK01, E1EDK14, E1EDP01, etc.) mapped to canonical fields
- TIN captured from master data and validated against regulator database
- Tax codes mapped using SAP condition records to FIRS equivalents
SAP S4/HANA
- API_BILLINGDOCUMENT_SRV entities mapped directly
- Company codes and plants resolved into canonical invoice header
- Customer master and product master cross-mapped to regulator TIN and HS code libraries
Other ERPs
- Oracle EBS XML nodes, Dynamics OData entities handled by mapping templates
- CSV exports processed through intelligent parsers
- Legacy systems handled through BlueBox capture with rules-based parsing
6.4 Mapping to FIRS MBS Schema
<BluelightSmartAPI> transforms the canonical JSON to FIRS-required schema in real time.
Validation & Enforcement
- Mandatory field enforcement – missing buyer TIN or invoice date rejected at SmartAPI layer before reaching FIRS
- Normalization – formats normalized (e.g., dates converted to ISO 8601)
Quality Assurance
- Validation rules – numeric fields validated, tax codes checked, HS codes cross-referenced
- Error messages – structured error returned to ERP or Email Connector with root cause for correction
6.5 Resource Library and Reference Data
Compliance requires external data sources beyond invoices. Our system includes a comprehensive reference data library:
HS Code Library
Product mapping to correct HS classification with automated validation and updates.
Customer Master
Client-provided mapping of customer IDs to TINs and regulator IDs with validation.
Tax Code Library
Mapping of ERP tax codes to regulator codes with automatic synchronization.
Service Codes
Library maintained and updated centrally, synced with FIRS resources automatically.
This ensures Finance and Compliance teams do not waste time remapping master data repeatedly.
Reference Data Architecture
Intelligent reference data management combining client master data with regulator codes through SmartAPI caching for real-time invoice mapping
6.6 Version Management and Change Absorption
FIRS regularly updates schema specifications. Most vendors pass these changes back to the client ERP, causing expensive rework. Our model avoids this:
Advanced Versioning
- Versioned Schemas – SmartAPI maintains multiple schema versions in parallel
- Feature Flags – changes can be enabled or disabled without disrupting ERP integration
Zero-Impact Updates
- Backward Compatibility – client ERP continues submitting in canonical schema, even as SmartAPI adapts to new FIRS rules
- Hotfix Pipeline – regulatory changes implemented in SmartAPI and deployed rapidly, without ERP modification
6.7 Error Handling and Guided Correction
- Validation rejects returned in structured JSON or as email notifications.
- Errors logged with correlation IDs for quick traceability.
- Finance users guided with reason codes (e.g., "Invalid TIN format," "HS code mismatch").
- Corrected invoices automatically resubmitted through the same pipeline.
6.8 Why This Matters
By insulating client ERPs from schema churn and automating mapping through libraries and canonical modeling, Softrust and Bluelight deliver:
Operational Excellence
- Fewer rejections and faster clearance
- Reduced IT workload during regulatory changes
Strategic Benefits
- Continuous compliance without costly ERP customization
- Confidence for Finance and Compliance that tax codes, HS codes, and TINs are always correctly aligned
Ready for Intelligent Data Mapping?
Experience the power of canonical schema architecture that eliminates mapping complexity and absorbs regulatory changes automatically, keeping your ERP systems stable and compliant.