NRS E-Invoice API Documentation

The Wragby NRS API acts as a secure proxy between your application and the NRS 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 NRS 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	NRS business-rule validation failed or invoice state is invalid.
500	Unexpected server-side error.
503	NRS 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": "TOSV00121855-56F38F0D-20260205",
    "issue_date": "2026-02-05",
    "invoice_type_code": "381",
    "document_currency_code": "NGN",
    "tax_currency_code": "NGN",
    "accounting_supplier_party": {
      "party_name": "Perferendis facere",
      "tin": "71687109-1946",
      "email": "Adejoke@workmenandtalents.com",
      "postal_address": {
        "street_name": "21A Olubunmi Rotimi Street.",
        "city_name": "Gemeente Groningen",
        "postal_zone": "7667",
        "country": "NG"
      }
    },
    "legal_monetary_total": {
      "line_extension_amount": 817.10,
      "tax_exclusive_amount": 817.10,
      "tax_inclusive_amount": 817.10,
      "payable_amount": 817.10
    },
    "invoice_line": [
      {
        "hsn_code": "8517.11",
        "product_category": "Line telephone sets with cordless handsets",
        "invoiced_quantity": 6.00,
        "line_extension_amount": 712.80,
        "item": {
          "name": "Line Telephone",
          "description": "Line Telephone"
        },
        "price": {
          "price_amount": 118.80,
          "base_quantity": 6.00,
          "price_unit": "NGN per 1"
        }
      },
      {
        "hsn_code": "8518.10",
        "product_category": "Microphones and stands therefor",
        "invoiced_quantity": 7.00,
        "line_extension_amount": 104.30,
        "item": {
          "name": "Microphone",
          "description": "Microphone"
        },
        "price": {
          "price_amount": 14.90,
          "base_quantity": 7.00,
          "price_unit": "NGN per 1"
        }
      }
    ],
    "tax_total": [
      {
        "tax_amount": 61.28,
        "tax_subtotal": [
          {
            "taxable_amount": 712.80,
            "tax_amount": 53.46,
            "tax_category": {
              "id": "STANDARD_VAT",
              "percent": 7.5
            }
          },
          {
            "taxable_amount": 104.30,
            "tax_amount": 7.82,
            "tax_category": {
              "id": "STANDARD_VAT",
              "percent": 7.5
            }
          }
        ]
      }
    ],
    "accounting_customer_party": {
      "party_name": "Wragby business solutions",
      "tin": "71687109-1946",
      "email": "info@wragbysolutions.com",
      "postal_address": {
        "street_name": "Way Street",
        "city_name": "Lagos",
        "postal_zone": "100632",
        "country": "NG"
      }
    }
  }'

Validate Invoice

POST/validate-invoice

Validates an invoice against NRS EIVC platform rules before signing.

Required fields

Field	Type	Description
business_id	string	Unique business identifier registered on the NRS 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

Field	Type	Description
due_date	string	Payment due date in YYYY-MM-DD format when supplied.
issue_time	string	Invoice issue time.
payment_status	string	Current payment status for the invoice.
note	string	Additional free-text invoice note.
tax_point_date	string	Tax point date in YYYY-MM-DD format when supplied.
accounting_cost	string	Accounting cost reference.
buyer_reference	string	Buyer-side reference identifier.
order_reference	string	Related order reference.
invoice_delivery_period	InvoiceDeliveryPeriod	Optional delivery period object.
billing_reference	DocumentReference[]	Related billing document references.
dispatch_document_reference	DocumentReference	Related dispatch document reference.
receipt_document_reference	DocumentReference	Related receipt document reference.
originator_document_reference	DocumentReference	Related originator document reference.
contract_document_reference	DocumentReference	Related contract document reference.
_document_reference	DocumentReference[]	Additional document references.
accounting_customer_party	Party	Buyer or customer party details.
payee_party	Party	Optional payee party details.
tax_representative_party	Party	Optional tax representative party details.
actual_delivery_date	string	Actual delivery date in YYYY-MM-DD format when supplied.
payment_means	PaymentMeans[]	Payment means entries for the invoice.
payment_terms_note	string	Payment terms note.
allowance_charge	AllowanceCharge[]	Optional allowances or charges applied to the invoice.

Example response

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

Sign Invoice

POST/sign-invoice

Submits an invoice to the NRS 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 NRS 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 NRS 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 NRS 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 NRS. Use hscode values in invoice line item hsn_code.

Get Product Services

GET/get-product-services

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

Get Tax Categories

GET/get-tax-categories

Returns tax categories defined on the NRS 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.