System Architecture
Heirs Technologies acts as a System Integrator and Access Point Provider to the FIRS MBS (Management and Business Solutions), facilitating seamless invoice transmission between businesses and the tax authority.
The platform is a multi-tenant SaaS middleware — each tenant is fully isolated with their own credentials, invoice data, ERP configuration, and team members.
System Actors
| Actor | Role |
|---|---|
| Supplier | External entity submitting invoices to businesses through the HT platform (via mobile or web application) |
| Business User | Client organisation employee who creates, manages, and approves invoices within their ERP system |
| HT Admin | Heirs Tech administrator managing system configuration, monitoring operations, and handling support escalations |
Platform Component Overview
Data Flow Architecture
| Flow | Path |
|---|---|
| Outbound | Client ERP → HT Transform → HT Validate → HT Integration → FIRS MBS |
| Inbound | FIRS MBS → Webhook → HT Integration → HT Transform → Client ERP |
| Monitoring | All services → Database → HT Monitoring Dashboard |
Invoice Workflow Sequence
Invoice Status Lifecycle
Each invoice moves through these statuses as it progresses through the pipeline:
| Status | Meaning |
|---|---|
submitted | Invoice received from ERP, queued for processing |
transforming | Converting from ERP format to FIRS UBL 2.1 |
validated | Passed FIRS schema and business rule checks |
signed | PEM digital signature applied |
transmitted | Signed invoice sent to FIRS MBS |
received | FIRS has confirmed receipt |
acknowledged | FIRS has issued the IRN — invoice is compliant |
failed | A pipeline stage encountered an error |
The status lifecycle above is derived from the API event system. Verify the exact state names against your Heirs Technologies internal architecture reference for any platform-specific additions.
Key Components
API Gateway
Handles all inbound API requests. Validates the x-api-key header, enforces rate limits per tenant, and routes requests to the appropriate service. Admin requests require x-admin-key.
Event Router
The configurable pipeline engine. Routes invoice events (submitted, validated, signed, etc.) to the correct sequence of processing actions. Each tenant has a custom routing configuration.
Processing Engine
Executes the pipeline stages in order:
- Transform — converts ERP-native format to FIRS UBL 2.1 via
POST /transform/to-firs; converts FIRS responses back viaPOST /transform/from-firs - Validate — enforces FIRS schema and business rules
- Sign — applies PEM-based digital signature
- Generate IRN — creates the FIRS Invoice Reference Number
- Transmit — sends signed invoice to FIRS MBS
HT Integration Layer
Manages direct communication with FIRS MBS. Handles outbound invoice transmission and receives inbound FIRS webhooks (POST /webhooks/firs/invoice-received). Confirms invoices via POST /invoices/{id}/confirm.
Tenant Data Store
Fully isolated per tenant. Stores invoices, event logs, ERP config, FIRS credentials, team members, and API keys.
Webhook Dispatcher
Sends HTTP POST notifications to the tenant's registered webhookUrl when invoice events occur.
HT Monitoring Dashboard
Aggregates data from all platform services. Accessible via GET /dashboard/status. Used by HT Admins to oversee operations and support escalations.
API Integration Endpoints
| Endpoint | Direction | Purpose |
|---|---|---|
POST /webhooks/firs/invoice-received | Inbound | FIRS notifies HT of received invoice |
POST /invoices/{id}/confirm | Internal | Confirm invoice state after FIRS ack |
GET /dashboard/status | Internal | HT Admin monitoring dashboard |
POST /transform/to-firs | Outbound | Transform ERP invoice to FIRS UBL 2.1 |
POST /transform/from-firs | Inbound | Transform FIRS response back to ERP format |
Environments
| Environment | Base URL | Purpose |
|---|---|---|
| Staging | https://e-invoicing-staging.vercel.app/v1 | Integration testing and validation |
| Sandbox | POST /v1/admin/sandbox/test-full | Development and ERP integration testing |
Supported ERP Systems
| ERP | Type Code |
|---|---|
| SAP | SAP |
| Oracle | ORACLE |
| Zoho | ZOHO |
| QuickBooks | QUICKBOOKS |
| Xero | XERO |
| Sage | SAGE |
| Microsoft Dynamics | DYNAMICS |
| NetSuite | NETSUITE |
| Odoo | ODOO |
| FreshBooks | FRESHBOOKS |
| Wave | WAVE |
| FIRS UBL (native) | FIRS_UBL |
| Peppol BIS | PEPPOL_BIS |
| UBL 2.1 (generic) | UBL_2_1 |
| Custom | CUSTOM |