REST Connections

REST API Integration Specification

For integrators preferring a stateless, web-hook style architecture, our system can be configured to POST print request payloads to a designated endpoint. This is ideal for cloud-based KDS providers or remote logging services. Additionally for integrators looking to handle NX Orders print requests, REST Webhooks are the only supported option.

1. Endpoint Configuration

The integrator must provide a publicly accessible (or VPN-tunnelled) HTTPS endpoint.

Method: POST
Content-Type: application/json
Timeout: The integrator’s server must respond within 5 seconds. If the connection times out, our system will initiate a retry logic based on the retryCount field.

2. Security & Validation Headers

To ensure that incoming requests are legitimate and to provide routing context, every request from our system will include two custom headers. Integrators must use these headers to validate the origin of the data.

Header	Description	Required
`x-nx-venueid`	The unique UUID of the physical venue/location sending the data.	Yes
`x-nx-device-id`	The hardware ID of the specific tablet or terminal triggering the print.	Yes

Security Best Practice: > Integrators should maintain an allow-list of venueIds. If a request arrives with an unknown x-nx-venueid, the server should return a 403 Forbidden response.

3. Request Structure

The body of the POST request follows the standard IPrintRequest wrapper. Note that while the model allows for multiple records, most REST triggers will contain a single record within the records array per hit.

POST /your-integration-path HTTP/1.1
Host: api.integrator.com
Content-Type: application/json
x-nx-venueid: 9975ce43-1167-459f-8e97-a20b89a2866b
x-nx-device-id: BW-E-Tablet-01

{
    "records": [{ ... }],
    "status": "SUCCESS",
    "count": 1,
    "serverRequestTimestamp": "2026-02-06T21:49:48.832Z"
}

4. Expected Responses

The integrator's service must return standard HTTP status codes to communicate the result of the print job.

Status Code	Meaning	System Action
200 OK / 202 Accepted	Success	Job is marked as `SENT` or `CONSUMED` in our logs.
400 Bad Request	Schema Mismatch	Job is aborted; no retry. Logged as a configuration error.
401/403 Unauthorized	Header Validation Failed	Job is aborted. Alert sent to venue admin.
500/502/503/504	Server/Network Error	Retry Logic Triggered: The system will attempt to resend up to 3 times with exponential backoff.

5. Integration Workflow

Ingestion: Receive the JSON and extract x-nx-venueid to identify the merchant.
Deduplication: Use the records[0].id (the Print Request UUID) to ensure that retried requests are not processed twice (e.g., printing the same steak ticket twice).
Parsing: Iterate through the items array. If your system does not support nested modifiers, flatten the childItems recursively.
Acknowledgment: Return a 200 OK immediately after successfully persisting the data to your local queue, even if the physical printer hasn't finished the job yet.