NRS API Through Your Domain

Your approved domain is an authenticated NRS API entry point for the operations listed on this page. For a supported direct NRS operation, replace the NRS origin with your Gateway origin and keep its documented HTTP method, path, and NRS request body.

NRS path:     /api/v1/invoice/resources/tax-categories
Gateway URL:  https://acme.invoice.tryduplo.com/api/v1/invoice/resources/tax-categories

Send the API key generated in Duplo Dashboard as x-api-key on every request, as shown in the examples below.

Use only the Gateway headers documented for each operation. Gateway applies the approved business, state, and route rules before forwarding an eligible NRS request. A valid hostname and API key do not authorize an arbitrary URL path.

If you send x-request-id, Gateway treats it only as optional caller correlation metadata. It does not become the trusted Gateway or support identifier. Capture the Gateway-generated X-Request-ID on every response; for a Problem Details error, it equals body requestId.

X-Duplo-Gateway-Hop is a reserved loop-detection header. Do not send it or copy it from an internal request. A non-zero value on an inbound request is rejected with 508 GW_ROUTING_LOOP_DETECTED and requires an operator to correct routing.

How routing works

The supported surface has distinct handling rules:

• POST /api/v1/invoice/sign is intercepted for mode handling, tenant checks, billing, and recovery.
• POST /api/v1/invoice/validate, GET /api/v1/invoice/transmit/lookup/{irn}, and POST /api/v1/invoice/transmit/{irn} are represented-business-bound Pass-through routes.
• The resource, recipient, health, entity, and NRS-login operations listed below are bounded direct NRS routes. Inbound download and acknowledgement are recognized but blocked as described below.
• Every unlisted method/path combination, including another shape under /api/v1/invoice/transmit, is rejected instead of being forwarded.
• /sub-businesses, /invoices, /health, and platform webhook/administration paths belong to Duplo, not NRS.

Gateway matches the same canonical path for authorization, billing classification, and forwarding. Query parameters are rejected on direct NRS relay routes. Gateway-owned collection reads accept only their explicitly documented query fields; for example, GET /sub-businesses accepts page and limit. Do not send encoded path separators, dot segments, backslashes, fragments, duplicate separators, malformed percent escapes, oversized paths, unknown or repeated query fields, or duplicate security-sensitive headers. Those values are rejected; Gateway does not normalize one target for authorization and forward a different target.

Requests with a JSON body must send Content-Type: application/json; unsupported or missing media types are rejected with GW_REQUEST_MEDIA_TYPE_UNSUPPORTED before a body is forwarded.

Header requirements by route

Pass-through sign also accepts a positive x-attempt-number, which defaults to 1. Keep it stable with the idempotency key for one logical attempt; read Billing and safe retries before creating a later attempt.

NRS may impose additional fields or semantics on an ordinary proxied route. Follow the official NRS e-Invoicing documentation, version 1.1.6 for the regulator-owned contract.

NRS contract compatibility

Gateway uses an explicit NRS adapter selected independently for TEST and LIVE. The current Gateway adapter version is v1; it is a Duplo integration-contract version and is distinct from the version label in NRS's public documentation.

For an ordinary successful relay, Gateway preserves the NRS 2xx status and body bytes after filtering response headers. Unknown additive response fields therefore remain compatible. Gateway performs stricter runtime validation only when its own safety decision depends on the response, including onboarding authentication/entity selection, represented-business identity, sign success, and IRN ownership.

Gateway never treats an unfamiliar sign envelope as success merely because its HTTP status is 2xx. Signing requires HTTP 2xx plus body code: 201 and data.ok: true; malformed JSON, 202, empty 204, a renamed field, or another unknown result is GW_SIGN_OUTCOME_UNCONFIRMED after debit. Deployment-owned NRS credential rejections are mapped to an operator dependency failure rather than an invoice or customer-credential rejection.

Credential rotation may stage a current and next credential, but Gateway does not retry an uncertain mutation with another credential. Identity drift is also explicit: changed name, template, or active status can be reviewed, while business-ID or TIN drift requires an audited migration. Never silently replace the stored NRS identity or stop accepting a previously published identifier alias.

Supported NRS endpoints

This table is the complete NRS route allowlist exposed through the Gateway for the current release. It is still not a replacement for the NRS payload reference: response fields and regulator-owned resource values can change independently of Gateway. However, a new NRS route, resource endpoint, method, or query option remains unavailable until both the Gateway and this table are released with support for it.

Retrieve the stored represented-business identity

Successful Gateway onboarding returns gatewaySubBusinessId, the backward-compatible firsBusinessId, and the complete durable nrsIdentity object. At onboarding, the immutable Gateway identity is allocated from the selected NRS business.id, so the values initially match:

gatewaySubBusinessId == firsBusinessId == nrsIdentity.nrsBusinessId

After an audited identity migration, gatewaySubBusinessId stays unchanged while firsBusinessId and nrsIdentity.nrsBusinessId advance together to the current NRS mapping. Always use gatewaySubBusinessId in x-sub-business-id and represented-business paths; use the current nrsIdentity.nrsBusinessId as business_id in Pass-through invoice bodies. The identity object also contains the NRS entity ID, nullable reference, registered business name, TIN, and IRN template. Treat every identifier as an opaque string, not a UUID.

After onboarding, list the current mappings with GET /sub-businesses?page=1&limit=50, or read one with GET /sub-businesses/{gatewaySubBusinessId}. These requests use only the approved host and parent x-api-key; they need no x-sub-business-id, idempotency key, body, or NRS credentials. Both unbilled Gateway-owned reads use stored data and do not call NRS. See List represented businesses and Read a represented business back for complete requests, response contracts, and recovery guidance.

NRS authentication itself contributes only data.entity_id. Gateway then fetches the entity and selects one active business to obtain the remaining stored identity. Provider transaction IDs, status text, messages, and receipt timestamps from the raw authentication envelope are not durable business identity and are not published by onboarding or the read endpoint.

Verify the current identity directly with NRS

The onboarding and represented-business information responses are persisted snapshots, not live NRS reads. When you need to check whether NRS has since changed the entity, registered name, TIN, active state, or IRN template, authenticate the represented business's NRS portal user through this unbilled diagnostic:

curl --request POST \
  --url https://acme.invoice.tryduplo.com/api/v1/utilities/authenticate \
  --header 'content-type: application/json' \
  --header 'x-api-key: pk_test_replace_with_your_key' \
  --data '{
    "email": "nrs-owner@acme.example",
    "password": "replace-with-a-transient-secret"
  }'

A common response is:

{
  "code": 200,
  "data": {
    "entity_id": "entity-demo"
  }
}

Then read the entity:

curl \
  --url https://acme.invoice.tryduplo.com/api/v1/entity/entity-demo \
  --header 'x-api-key: pk_test_replace_with_your_key'

{
  "code": 200,
  "data": {
    "id": "entity-demo",
    "reference": "entity-reference-demo",
    "businesses": [
      {
        "id": "nrs-business-demo",
        "name": "Acme Retail Limited",
        "tin": "12345678-0001",
        "irn_template": "{{invoice_id}}-2A3A045D-{{YYYYMMDD}}",
        "is_active": true
      }
    ]
  }
}

Select only the active business with an exact normalized TIN match. Its id must match the current firsBusinessId and nrsIdentity.nrsBusinessId in the Gateway snapshot; its name, TIN, and IRN template should also match. gatewaySubBusinessId can intentionally remain the original stable routing identity after an audited migration. Remove the NRS password from memory and logs as soon as the diagnostic finishes. Do not call this authentication endpoint for every invoice.

The entity or business reference can be absent and is not an onboarding or invoice requirement. Gateway stores the bounded entity reference first, or the selected-business reference as a fallback, and returns entityReference: null when neither exists. If current NRS identity differs from the stored mapping, stop signing and use the reviewed identity-reverification workflow. Never silently overwrite your mapping or onboard a duplicate.

Recipient lookup and health

Check a receiver before building a transmission workflow:

curl \
  --url https://acme.invoice.tryduplo.com/api/v1/invoice/transmit/lookup/tin/11111111-0001 \
  --header 'x-api-key: pk_test_replace_with_your_key'

{
  "code": 200,
  "data": {
    "up": true,
    "has_webhook_setup": true
  }
}

Check the NRS connection selected for the current domain and state:

curl \
  --url https://acme.invoice.tryduplo.com/api/v1/invoice/transmit/self-health-check \
  --header 'x-api-key: pk_test_replace_with_your_key'

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

These calls say nothing about your wallet balance in Duplo Dashboard or domain approval workflow. A Gateway host health check is separately available at GET /health and returns { "status": "ok" }.

Fetch NRS resources instead of hard-coding them

curl \
  --url https://acme.invoice.tryduplo.com/api/v1/invoice/resources/tax-categories \
  --header 'x-api-key: pk_test_replace_with_your_key'

A resource response can resemble:

{
  "code": 200,
  "data": [
    {
      "code": "STANDARD_VAT",
      "value": "Standard VAT",
      "percent": "7.5"
    }
  ]
}

Treat STANDARD_VAT, 7.5, service code 6201, and quantity code HUR in these guides as snapshots used to explain shape. Fetch the current NRS catalogs, cache them for a bounded period, and refresh them when NRS validation reports an unknown or changed value.

Invoice endpoint responses

Common NRS success bodies seen by the Gateway integration are:

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

{ "code": 201, "data": { "ok": true, "irn": "INV000001-2A3A045D-20260818" } }

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

For signed-IRN lookup, current integration evidence shows party objects such as accounting_supplier_party, accounting_customer_party, bill_party, and ship_party, each with an up flag. The exact lookup schema is not sufficiently stable to use as a generated type; preserve unknown fields and check the current NRS documentation.

Understand response ownership

Your client can encounter three response families:

Use the response Content-Type before selecting a parser. A successful NRS body can use a different schema from a Gateway-owned success. A DNS, TLS, CDN, or load-balancer failure can occur before Gateway and will not have Gateway Problem Details.

Do not assume every successful response uses the same HTTP status. Log the HTTP status, sanitized response body, and Gateway-generated X-Request-ID without logging credentials, query secrets, or full invoice payloads. See the Gateway error code reference for the complete GW_* catalogue and Handle Gateway error responses for safe retry rules.

Continue with the Pass-through guide, Stored guide, or the complete official NRS reference.