Matt O'Bell NRS System Integrator

API & Technical Integration Documentation

1. Document Purpose

This document provides the technical description of the Matt O'Bell NRS e-Invoicing System Integrator implemented for Odoo 18 Enterprise. It is intended to support technical review, onboarding and operational understanding of the integration.

2. Solution Overview

The solution integrates Odoo 18 Enterprise with the NRS e-Invoicing platform. Invoices are prepared in Odoo, classified using NRS-synchronised resources, assigned an IRN, validated through the NRS validation API, submitted for signing, and provided with a cryptographic QR payload for presentation on the Odoo invoice and PDF.

2.1 High-Level Architecture

Odoo 18 Enterprise
        |
        v
Matt O'Bell NRS Integration Module
        |
        | HTTPS / JSON REST API
        v
NRS e-Invoicing Platform

2.2 Main Components

Component	Purpose
Odoo 18 Enterprise	ERP, accounting and invoice source system.
Matt O'Bell NRS SI Module	Invoice mapping, resource classification, IRN workflow, API communication and audit trail.
PostgreSQL	Odoo transactional database.
Nginx	Web/reverse-proxy layer where deployed.
OpenSSL	Public-key encryption used for the NRS QR payload.
QR Generation	Creates a PNG QR code from the encrypted Base64 payload.

3. API Authentication

The integration authenticates NRS API requests using the API key and secret key supplied by the NRS environment. Credentials are transmitted in HTTPS request headers.

x-api-key: <NRS API Key>
x-api-secret: <NRS API Secret>

The implementation does not place credentials in the invoice payload. Operational logs record credential presence and length for diagnostics, rather than logging the actual secrets.

4. NRS API Endpoints Used

The integration uses HTTPS REST endpoints supplied by the NRS environment. The validated Sandbox endpoint observed during implementation is:

POST https://eivc-k6z6d.ondigitalocean.app/api/v1/invoice/validate

The integration also performs the NRS invoice signing request and consumes the NRS resource endpoints supplied for invoice classification. Endpoint paths are environment-configurable and should be taken from the NRS environment configuration rather than hard-coded for production.

4.1 NRS Resource Synchronisation

Resource	NRS Endpoint
Invoice Types	/api/v1/invoice/resources/invoice-types
Tax Categories	/api/v1/invoice/resources/tax-categories
Currencies	/api/v1/invoice/resources/currencies
Quantity Codes	/api/v1/invoice/resources/invoice-quantity-codes
HSN Codes	/api/v1/invoice/resources/hs-codes
Service / ISIC Codes	/api/v1/invoice/resources/services-codes
Payment Means	/api/v1/invoice/resources/payment_means

During Sandbox testing, service, HSN, tax category, invoice type, quantity code and currency resources were successfully synchronised. The payment_means resource returned HTTP 404 in the tested environment.

5. IRN Generation

The implementation generates the Invoice Reference Number using the invoice number, NRS-assigned Service ID and invoice issue date in the documented format:

INVOICE_NUMBER-SERVICE_ID-YYYYMMDD

The Odoo invoice number is normalised by removing characters that are not permitted by the IRN generation rules before constructing the IRN.

Example: INV202600002-4894B3BA-20260813

6. Invoice JSON Payload

The integration sends JSON based on the NRS invoice schema and maps Odoo invoice data to the NRS-required UBL-aligned fields.

6.1 Representative Service Invoice

{
  "document_currency_code": "NGN",
  "invoice_type_code": "381",
  "irn": "INV202600002-4894B3BA-20260813",
  "invoice_line": [{
    "invoiced_quantity": 1,
    "line_extension_amount": 90000,
    "isic_code": "7020",
    "service_category": "Management consultancy activities",
    "hsn_code": "",
    "product_category": "",
    "item": {
      "name": "Odoo Implementation & Configuration",
      "description": "Odoo Implementation & Configuration",
      "sellers_item_identification": ""
    },
    "price": {
      "price_amount": 90000,
      "base_quantity": 1,
      "price_unit": "XBG"
    }
  }],
  "tax_total": [{
    "tax_amount": 6750,
    "tax_subtotal": [{
      "taxable_amount": 90000,
      "tax_amount": 6750,
      "tax_category": {
        "id": "STANDARD_VAT",
        "percent": 7.5
      }
    }]
  }]
}

7. Invoice Validation

Before signing, the prepared invoice is submitted to the NRS validation endpoint. The validation layer checks the invoice content against the NRS invoice schema.

Successful Sandbox validation observed:

{ "code": 200, "data": { "ok": true } }

The implementation records the NRS response and associates it with the Odoo NRS transaction for auditability.

8. Invoice Signing Request

After successful validation, the integration submits the invoice for NRS signing. The successful Sandbox test returned HTTP 201.

{ "code": 201, "data": { "ok": true } }

The successful test produced the NRS request identifier: dc45d573-28f3-4161-901d-c605429c8ec7.

9. Cryptographic QR Generation

The NRS cryptographic QR workflow uses the crypto_keys.txt material provided through the NRS dashboard. The module extracts the public key and certificate and does not require or store a private key.

9.1 QR Payload Construction

The IRN is combined with a current Unix timestamp using a period separator:

IRN.UNIX_TIMESTAMP

The IRN/timestamp value and NRS certificate are packaged as JSON, encrypted using the NRS public key, Base64 encoded and rendered as a PNG QR code.

9.2 QR Output

The generated QR is stored against the NRS transaction and displayed on the Odoo invoice form. The customer invoice PDF also displays the NRS IRN, NRS state and generated QR code.

10. End-to-End Transaction Workflow

1. Odoo invoice is posted/finalised.
2. NRS preparation validates that a final invoice number exists.
3. NRS resources are used for invoice classification.
4. IRN is generated.
5. Invoice JSON payload is constructed.
6. Invoice is validated through NRS.
7. Validated invoice is submitted for signing.
8. NRS crypto keys are loaded where required for QR generation.
9. IRN + timestamp + certificate are encrypted with the NRS public key.
10. QR code is generated and stored.
11. NRS information is presented on the Odoo invoice and customer PDF.

11. Security Controls

• HTTPS/TLS for API communication.
• API key and secret key supplied through HTTP headers.
• API credentials are not included in invoice JSON payloads.
• Diagnostic logs record credential presence/length, not secret values.
• NRS public key and certificate are stored for QR processing; no private key is required or stored by the module.
• Odoo access controls govern configuration and transaction actions.
• Transaction requests, payload hashes, states and responses are retained for audit/troubleshooting purposes.

12. Error Handling and Audit Trail

NRS HTTP status codes and response bodies are captured against the NRS transaction. Validation failures are surfaced to the Odoo user while retaining NRS response details for troubleshooting.

The implementation also protects the transaction lifecycle against duplicate IRNs and requires a finalised Odoo invoice before NRS preparation.

13. Environments and Deployment

The integration supports separate NRS configuration for Sandbox and production environments. API base URLs and credentials are maintained through the NRS configuration rather than embedded in invoice records.

The tested Sandbox environment successfully completed invoice validation, signing request and QR generation.

14. Verified Integration Result

Test Item	Result
Odoo Invoice	INV/2026/00002
NRS IRN	INV202600002-4894B3BA-20260813
Service	Odoo Implementation & Configuration
ISIC	7020
NRS Service Category	Management consultancy activities
Invoice Validation	HTTP 200 — ok: true
Signing Request	HTTP 201 — ok: true
QR Generation	Successful
Customer Invoice PDF	NRS IRN, Accepted state and QR displayed

15. Implementation Notes

This document describes the implementation and successful Sandbox testing performed for the Matt O'Bell NRS System Integrator. NRS production endpoint paths, credentials, taxpayer-specific identifiers and production certificates must be supplied/configured in accordance with NRS onboarding requirements.

Where this document describes NRS field formats or cryptographic workflow, the terminology follows the NRS System Integrator documentation supplied for this implementation.