FIRS E-Invoice API Documentation

The Wragby NRS API acts as a secure proxy between your application and the FIRS Electronic Invoice Validation and Compliance (EIVC) platform. It exposes endpoints for invoice validation, signing, IRN lookup, invoice transmission, VAT/NRS reporting, and reference data retrieval.

Overview

Base URL

https://nrsmockapi.azurewebsites.net

Authentication

No authentication headers are required from API consumers. The Wragby NRS API server injects the required upstream x-api-key and x-api-secret credentials when communicating with the FIRS platform.

Response format

Successful requests return:

{
  "message": "Request completed successfully.",
  "data": {}
}

Errors return:

{
  "code": 400,
  "message": "error has occurred",
  "error": {
    "id": "bec38e04-7558-4fa2-a1b3-d96e554f433f",
    "handler": "invoice_actions",
    "details": "invoicerequest.invoice.taxcurrencycode is required",
    "public_message": "validation failed: unable to process your request"
  }
}

Code	Meaning
200	Request processed successfully.
400	Missing required fields or invalid values.
401	Server-side upstream credentials are invalid.
404	Requested IRN or resource was not found.
422	FIRS business-rule validation failed or invoice state is invalid.
500	Unexpected server-side error.
503	FIRS platform could not be reached.
504	Upstream request timed out.

Quickstart

Validate an invoice, sign the same payload, then transmit or confirm by IRN.

curl https://nrsmockapi.azurewebsites.net/validate-invoice \
  -H "Content-Type: application/json" \
  -d '{
    "business_id": "fd1267b0-8f0d-4809-bb1f-e99fe0025c43",
    "irn": "TOSV00180-56F38F0D-20260205",
    "issue_date": "2026-02-05",
    "invoice_type_code": "381",
    "document_currency_code": "NGN",
    "tax_currency_code": "NGN",
    "accounting_supplier_party": {
      "party_name": "Sample Supplier",
      "tin": "71687109-1946",
      "email": "supplier@example.com",
      "postal_address": {
        "street_name": "21A Example Street",
        "city_name": "Lagos",
        "postal_zone": "100001",
        "country": "NG"
      }
    },
    "legal_monetary_total": {
      "line_extension_amount": 817.10,
      "tax_exclusive_amount": 817.10,
      "tax_inclusive_amount": 878.38,
      "payable_amount": 878.38
    },
    "invoice_line": [],
    "tax_total": []
  }'

Validate Invoice

POST/validate-invoice

Validates an invoice against FIRS EIVC platform rules before signing.

Required fields

Field	Type	Description
business_id	string	Unique business identifier registered on the FIRS platform.
irn	string	Invoice Reference Number, for example TOSV00180-56F38F0D-20260205.
issue_date	string	Invoice issue date in YYYY-MM-DD format.
invoice_type_code	string	UBL invoice type code, for example 381 or 396.
document_currency_code	string	ISO 4217 document currency code, for example NGN.
tax_currency_code	string	ISO 4217 tax currency code.
accounting_supplier_party	Party	Seller or supplier object.
legal_monetary_total	LegalMonetaryTotal	Invoice monetary totals.
invoice_line	InvoiceLine[]	One or more invoice line items.
tax_total	TaxTotal[]	Tax total breakdown with subtotals.

Optional fields

due_date, issue_time, payment_status, note, tax_point_date, accounting_cost, buyer_reference, order_reference, invoice_delivery_period, billing_reference, dispatch_document_reference, receipt_document_reference, originator_document_reference, contract_document_reference, _document_reference, accounting_customer_party, payee_party, tax_representative_party, actual_delivery_date, payment_means, payment_terms_note, and allowance_charge.

Example response

{
  "message": "Request completed successfully.",
  "data": {
    "ok": true
  }
}

Sign Invoice

POST/sign-invoice

Submits an invoice to the FIRS platform for cryptographic signing and official registration. The signed invoice receives a QR code and digital signature that can be used for compliance verification.

Use the same invoice payload structure documented under Validate Invoice.

{
  "message": "Request completed successfully.",
  "data": {
    "irn": "TOSV00180-56F38F0D-20260205",
    "signed": true
  }
}

Transmit Invoice

POST/transmit-invoice/{irn}

Transmits a signed invoice to the recipient through the FIRS platform. The IRN must already be signed before transmission.

Parameter	Type	Required	Description
irn	string	Yes	Invoice Reference Number.

Pull Invoice

GET/transmit/pull

Returns a paginated list of invoices that have been transmitted to the customer or receiving party.

Query parameter	Type	Required	Description
page	integer	No	Page number to retrieve. Defaults to 1.
size	integer	No	Number of items per page. Defaults to 10.

{
  "message": "Request completed successfully.",
  "data": {
    "items": [
      {
        "irn": "TOSV00180-56F38F0D-20260205",
        "pushed_at": "2026-04-08T01:48:57.812317Z",
        "confirmed_at": "2026-04-08T01:55:46.409796Z"
      }
    ],
    "page": {
      "page": 1,
      "size": 10,
      "hasNextPage": false,
      "hasPreviousPage": false,
      "totalCount": 5
    },
    "attributes": null
  }
}

Confirm Receipt

PATCH/confirm-receipt/{irn}

Confirms receipt of a transmitted invoice on the FIRS platform. This acknowledges to the sender that the invoice has been received.

Confirm Invoice

GET/confirm-invoice/{irn}

Confirms an invoice by IRN and returns status and compliance metadata.

{
  "message": "Request completed successfully.",
  "data": {
    "issue_date": "2026-02-05",
    "due_date": "",
    "sync_date": "2026-04-08",
    "payment_status": "PENDING",
    "entry_status": "TRANSMITTED",
    "transmitted": true,
    "delivered": true
  }
}

Report E-Invoice

POST/report-einvoice

Reports invoices to the NRS e-invoice team for financial actions and forwards payment data to the NRS VAT post-payment endpoint.

Field	Type	Description
agent_tin	string	Accounting supplier party TIN.
base_amount	string	Amount to be taxed.
beneficiary_tin	string	Accounting buyer party TIN.
currency	string	Document currency code, for example NGN.
item_description	string	Invoice line item description.
irn	string	Invoice Reference Number.
other_taxes	string	Sum of tax amounts outside VAT.
total_amount	string	Payable amount.
transaction_date	string	Issue date in YYYY-MM-DD format.
vat_calculated	string	VAT tax amount.
integrator_service_id	string	Service ID of the Access Point Provider.
vat_rate	string	VAT percentage, for example 7.5.
vat_status	string	VAT category, for example STANDARD_VAT.

Reference Data

Get Countries

GET/get-countries

Returns the list of countries supported by FIRS EIVC. Use returned alpha_2 values in postal address country fields.

Get Product Codes

GET/get-product-codes

Returns Harmonized System product codes recognised by FIRS. Use hscode values in invoice line item hsn_code.

Get Product Services

GET/get-product-services

Returns service codes supported by FIRS. Use these for service-based invoice line items.

Get Tax Categories

GET/get-tax-categories

Returns tax categories defined on the FIRS platform. Use code values in tax_category.id.

Object Reference

Party

Field	Type	Required	Description
party_name	string	Yes	Legal name of the party.
tin	string	Yes	Tax Identification Number.
email	string	Yes	Contact email address.
postal_address	Address	Yes	Physical address.
telephone	string	No	Contact phone number.
business_description	string	No	Brief description of business activities.

Address

Field	Type	Required	Description
street_name	string	Yes	Street name and number.
city_name	string	Yes	City or locality name.
postal_zone	string	Yes	Postal or ZIP code.
country	string	Yes	ISO 3166-1 alpha-2 country code, for example NG.

LegalMonetaryTotal

Field	Type	Required	Description
line_extension_amount	number	Yes	Sum of invoice line extension amounts before tax.
tax_exclusive_amount	number	Yes	Amount excluding tax.
tax_inclusive_amount	number	Yes	Amount including tax.
payable_amount	number	Yes	Final amount payable.

InvoiceLine

Field	Type	Required	Description
hsn_code	string	Yes	Product or service code.
product_category	string	Yes	Product or service category description.
invoiced_quantity	number	Yes	Quantity invoiced.
line_extension_amount	number	Yes	Line total before tax.
item	Item	Yes	Item name and description.
price	Price	Yes	Price amount, base quantity, and price unit.

TaxTotal

Field	Type	Required	Description
tax_amount	number	Yes	Total tax amount.
tax_subtotal	TaxSubtotal[]	Yes	Tax breakdown by category.