How It Works
The Heirs E-Invoicing platform connects your ERP system to Nigeria's National Revenue Service (NRS/FIRS), handling the full compliance pipeline automatically — from ERP event detection through NRS acknowledgement and IRN issuance.
The Invoice Pipeline
Step-by-Step Breakdown
1. ERP Webhook Received
Your ERP sends a POST request to the platform's webhook URL whenever an invoice event occurs. The webhook URL and webhook secret are generated by the platform — you copy them from the Webhooks settings page and register them in your ERP's outbound webhook configuration.
The ERP includes the event type in the request headers (e.g. X-Event-Type: invoice.created). The platform authenticates the request using the webhook secret, reads the event type from the header, and looks up the matching workflow actions from the Event Routing configuration. The invoice payload in the request body is stored, with the invoiceIdKey used to extract and record the unique invoice identifier.
2. Transform
The platform maps your ERP's invoice fields to the NRS-required schema using the NRS Dictionary — a centrally managed field mapping table maintained by the Super Admin. Field mapping is configured once and applied automatically on every submission.
3. Validate
The transformed invoice is validated against NRS schema rules — mandatory fields, data types, value ranges, and business logic constraints. Validation errors are returned immediately with specific field-level details.
4. Sign
The validated invoice is digitally signed using the tenant's NRS-issued certificate and private key, uploaded during onboarding. This cryptographic signature is required by NRS to authenticate the invoice origin.
5. Generate IRN
An Invoice Reference Number (IRN) is issued by NRS/FIRS for each accepted invoice. The IRN is the government's proof that the invoice has been received and validated. It must be stored by the tenant for audit purposes.
6. Transmit
The signed, IRN-stamped invoice is transmitted to FIRS MBS over a secure channel.
7. Acknowledge
NRS/FIRS returns an acknowledgement confirming receipt. The platform updates the invoice status to acknowledged and notifies your ERP via webhook (if configured).
Webhook Event Routing
Event Routing is the configuration that maps the event type sent in the ERP's webhook request headers to one or more workflow actions. It is configured per tenant from the Event Routing section under Webhooks in the admin settings.
When the platform receives an incoming webhook from the ERP, it reads the event type from the header and executes the corresponding workflow actions automatically:
| ERP Event | Event ID | Workflow Action |
|---|---|---|
| ERP Invoice Submitted | erp.invoice.submitted | complete_outbound |
| ERP Invoice Updated | erp.invoice.updated | complete_outbound |
| ERP Payment Received | erp.payment.received | update_payment_status |
| ERP Credit Note Issued | erp.creditnote.issued | process_credit_note |
| ERP Debit Note Issued | erp.debitnote.issued | process_credit_note |
| Invoice Delivered | invoice.delivered | sync_erp |
No manual intervention is required — the platform routes and processes the invoice end-to-end based on this configuration. See Messaging and Routing Protocols for the full list of event IDs and workflow action IDs.
ERP Sync
ERP Sync is the configuration for the return path — sending the finished invoice back to your ERP once FIRS has delivered and acknowledged it. It is implemented as the sync_erp workflow action, which pushes the completed invoice record (including the IRN and QR code stamp) to your ERP via a configured sync endpoint and request body template.
ERP Sync covers the outbound direction only (platform → ERP) and is a separate configuration menu from Event Routing. The typical trigger is the invoice.delivered event, with sync_erp as the assigned action.
Event-Driven Architecture
Each stage of the pipeline fires an event that can be observed and routed. The key outbound lifecycle events are:
| Event ID | Fires when |
|---|---|
invoice.created | Invoice received and created in the system |
invoice.validated | Invoice passes NRS schema and business rule validation |
invoice.signed | Invoice is digitally signed |
invoice.transmitted | Invoice sent to FIRS |
invoice.delivered | Invoice acknowledged by FIRS — IRN issued |
invoice.failed | Processing failed at any stage |
invoice.rejected | Invoice rejected by FIRS or the receiving party |
invoice.paid | Payment confirmed |
See Messaging and Routing Protocols for the full event catalogue and all workflow action IDs.
Onboarding Flow
Before invoices can be processed, a tenant must complete three onboarding steps:
| Stage | Description |
|---|---|
| NRS/FIRS OAuth | Tenant authenticates with NRS/FIRS to authorise the platform to submit on their behalf |
| NRS Credentials | Tenant uploads their NRS-issued certificate file and private key |
| Webhook URL Setup | Platform generates a unique webhook URL; tenant registers it in their ERP system |
| Sandbox Testing | Tenant runs test invoices in the sandbox environment |
| Go Live | Platform admin activates the tenant for production NRS submission |
| Rejected | Onboarding rejected by platform admin |
| Suspended | Active tenant suspended by platform admin |