NRS Gateway API Overview

Call the Gateway on your approved business domain, for example https://acme.invoice.tryduplo.com. This reference covers all 27 public operations: represented-business and identity management, the Stored customer/invoice flow, health probes, and the finite NRS route allowlist. Two recognized inbound NRS operations are documented as unavailable.

Download the OpenAPI specification to import the contract into your API client or generate an SDK. Each operation below links to its request headers, parameters, schemas, responses, and interactive examples. Use the server selector to substitute your approved subdomain.

Authentication and request handling

Send x-api-key for customer, represented-business, invoice, and NRS operations. The Gateway binds the key to the approved domain and its parent business and test/live state. Public health probes do not require an API key. Any configured source-IP allowlist still applies to authenticated operations.

Use x-sub-business-id when a supported NRS invoice operation requires the represented business. This is the immutable Gateway identifier returned by onboarding. Customer create/list/lookup does not require that header; Stored transmission instead takes gatewaySubBusinessId in its request body. Follow each operation's required idempotency headers and preserve the same key and identical content when an allowed retry occurs.

Every operation accepts optional caller X-Request-ID correlation metadata. Gateway generates the authoritative response X-Request-ID and propagates it to dependencies. Responses use Cache-Control: no-store. Gateway failures use Problem Details; branch on code and retry.strategy, and honor Retry-After.

Represented businesses and NRS identity

Onboard the businesses you invoice on behalf of, retrieve their immutable Gateway IDs, and manage their versioned NRS identity. Read operations use the stored mapping without making an NRS request.

Protected identity migrations require Duplo support; the public review-decision endpoint does not authorize them. See represented-business onboarding and identity management.

Stored invoices

The STORED integration flow is: resolve a customer → submit the invoice with customerId → poll its status → transmit after signing. Customer management is part of this flow. PASSTHROUGH sends the NRS invoice document directly and does not require a Duplo customer lookup or creation step.

1. Create or resolve the customer

Create or resolve an invoice customer before submitting a Stored invoice with its customerId. Customers belong to the authenticated parent business and test/live state. Approved domains with the same parent and state share the customer set, and customers can be reused across represented businesses. Customer records are not isolated per sub-business or domain; caller-supplied ownership fields are rejected.

A duplicate email/TIN conflict returns 409 GW_CUSTOMER_ALREADY_EXISTS. If creation has an uncertain outcome, look up the customer by email before retrying. Missing or inaccessible customer IDs return 404 GW_CUSTOMER_NOT_FOUND.

Customer endpoints currently enforce domain/API-key authorization and parent/state ownership without a STORED-mode restriction. Their integration purpose is to prepare customer records for Stored invoices.

Intake currently accepts an omitted customerId, but asynchronous NRS readiness rejects an invoice without a customer. Gateway exposes no later operation to attach one. Resolve and persist the customer ID before submitting; include the customer's NRS-ready identity and address details as described in the Stored mode guide.

2. Submit the Stored invoice

Call sign or store an invoice at POST /api/v1/invoice/sign on a domain configured for STORED mode. Send the Stored payload with customerId, x-sub-business-id, and the required x-idempotency-key. A 202 response confirms durable intake, not completed NRS signing.

3. Read status and transmit

These Gateway-owned endpoints use Spend invoice UUIDs; the direct NRS routes use an IRN.

See the Stored mode guide for customer resolution, payloads, processing states, and transmission retries.

NRS authentication, diagnostics, and resources

These allowlisted operations relay supported requests to NRS. They are distinct from Gateway's local health probes.

NRS invoice operations

Only the documented method/path combinations are eligible for relay. A successful supported direct relay preserves the sanitized NRS-owned 2xx status, content type, and body. NRS non-2xx bodies are discarded and mapped to safe Gateway Problem Details. The sign route follows the domain's configured PASSTHROUGH or STORED behavior, as described in its reference.

The following inbound operations are recognized but deliberately unavailable. Eligible requests return 503 GW_INVOICE_OPERATION_UNAVAILABLE; do not build an integration that depends on them succeeding.

See NRS API through your domain for supported resources, headers, and routing rules.

Gateway health

These unauthenticated probes report local process health and do not make a live dependency request.

Readiness returns 503 with its documented JSON status body during startup or process shutdown. Liveness remains available while accepted work drains.

Domain draining and Gateway restarts

Signed STORED invoices awaiting NRS transmission block mode/state changes and disable. Email delivery and local cancellation do not discharge NRS transmission obligations. Canceled signed invoices and unknown provider outcomes require evidence-based support reconciliation.

The Gateway exposes no customer-facing endpoint to start or override draining.

Related guides

• Domain and API key explains domain approval, tenant scope, and credentials.
• Invoice payloads describes invoice submission formats.
• Billing and safe retries explains mutation identity and uncertain outcomes.
• Stable error codes lists actionable Gateway failures.