NRS Invoice GatewayNRS Gateway API Overview
Complete public contract for the NRS Invoice Gateway
This reference covers the endpoints the NRS Invoice Gateway owns and implements itself. They are served from your approved domain alongside the NRS routes, but they are Duplo operations, not regulator operations.
Complete public route inventory
The generated reference contains every public operation in the current Gateway release: represented-business and identity management, Stored invoice reads/transmission, compatibility/liveness/readiness health routes, and the finite direct NRS allowlist. It also documents the two recognized inbound NRS routes that deliberately return 503 GW_INVOICE_OPERATION_UNAVAILABLE. Administrator-only cache, identity-migration, dependency-diagnostic, and recovery endpoints are not public and are intentionally absent.
Every documented operation accepts an optional caller X-Request-ID for correlation, but Gateway generates the authoritative response X-Request-ID and propagates that value to dependencies. Responses use Cache-Control: no-store; Problem Details can also include Retry-After. Follow the structured retry object before replaying any mutation.
The approved domain also exposes an explicit allowlist of NRS-owned operations. Only the method and path shapes documented in NRS API through your domain are eligible for relay; the domain is not a catch-all NRS proxy.
Gateway-generated failures use the Gateway Problem Details contract and the stable error code reference. A successful supported direct relay preserves the sanitized NRS-owned 2xx status, content type, and response body. Gateway discards every NRS non-2xx body and maps it to a safe GW_* Problem Details response.
Base URL
Every endpoint below is called on the domain approved for your business, for example https://acme.invoice.tryduplo.com. Use the server selector on each page to substitute your own subdomain.
Represented businesses
Onboard Represented Business
Register a business you invoice on behalf of and receive its immutable Gateway identifier plus its current versioned NRS identity.
List Represented Businesses
Page through every active mapping in the current parent, approved domain, test/live state, and mode version without making an NRS request.
Get Represented Business Information
Recover a represented-business mapping and its current stored NRS identity version without sending NRS credentials or making an NRS request.
Set or Replace NRS QR Material
Add or replace the optional NRS certificate value and public key used when Duplo generates invoice QR codes.
Related guides
- Onboard represented businesses explains onboarding, immutable Gateway identities, versioned NRS mappings, reverification, and QR material.
- Domain and API key explains how the approved host and
x-api-keyresolve one business. - Billing and safe retries covers idempotency behaviour for these endpoints.
- Gateway operations runbook covers dependency outages, health, capacity, circuits, routing loops, alerts, and ambiguous outcomes.
How is this guide?