NX Restaurant × Lodging Link CC (HTTP) — Integration Guide

Audience: Comtrol / Pepperl+Fuchs Lodging Link installers, hotel IT, and PMS integrators connecting a property's Property Management System (PMS) to NX Restaurant for room-charge posting and folio lookups.

What this covers: the HTTP interface NX Restaurant exposes to Lodging Link Cloud Connect (CC), how to authenticate it, the message format, the request flow, and a site setup checklist.

What this is not: it is not the on-premise UHLL Serial/TCP transport. That is a separate, LAN-hosted integration. This document is exclusively for the Lodging Link CC (HTTP/REST) transport.

1. How the interface works (read this first)

With Lodging Link CC, Lodging Link is the HTTP client and NX Restaurant is the HTTP server. Lodging Link polls NX on a site-configured timer (typically 3–30 seconds). NX never dials into Lodging Link.

This is by design: hotels do not open inbound firewall holes for an outside device to reach Lodging Link, so Lodging Link always initiates the connection outward to NX's cloud endpoint.

Two consequences follow, and they shape everything below:

1. NX's endpoint is a stable public URL (in the NX cloud), not a device on the hotel LAN.
2. Every exchange is asynchronous. NX cannot push a request the instant a cashier asks for it — it must wait for Lodging Link's next poll. A folio lookup or a room charge therefore completes seconds later, bounded by the poll interval. This is normal and expected.

   Hotel PMS  ◀──▶  Lodging Link CC (cloud)  ──── HTTPS poll ────▶  NX Restaurant
                     (HTTP client, polls)          every 3–30s        (HTTP server)

   • Lodging Link GET  /…/rest/inbound   → "give me anything NX has queued"
   • Lodging Link POST /…/rest/outbound  → "here is the PMS's response"

2. Endpoints

NX exposes exactly two paths. Both are provided to you, fully-formed, during onboarding (§6) — including the base host and the version segment.

• {ver} is the UHLL version segment (for example v16.0). Use the exact value NX gives you at onboarding.
• The host is stage-specific (production vs. test). Use the base URL from your onboarding packet.
• HTTPS is recommended. Self-signed certificates on the NX side are accepted by Lodging Link; whether you use HTTP or HTTPS is configured inside Lodging Link at the site.

3. Authentication

HTTP Basic authentication, sent on every request:

Authorization: Basic base64(username:password)

• The username and password identify the specific property. NX maps the credential to one hotel/venue.
• NX generates a unique credential per property when the integration is enabled and hands it to you at onboarding. Enter it into Lodging Link's configuration for that site.
• The password is shown once at provisioning and stored only as a hash on the NX side — keep it safe; it cannot be retrieved later, only re-issued.
• A missing or invalid credential returns HTTP 401. A correctly-provisioned, active credential is required for both endpoints.

If NX disables/decommissions the integration, the credential stops authenticating (401). That is expected — re-provision to resume.

4. Message format

4.1 Envelope

Both requests and responses use a single JSON object keyed "UHLL", whose value is an array of UHLL message strings, one message per array element:

{ "UHLL": [ "3735300000199991750321 7", "6135300000299990..." ] }

• Each element is a complete UHLL message (header + data fields), exactly as in the UHLL specification.
• An empty array ({"UHLL":[]}) or empty body means "nothing to send."

4.2 Ordering

Order matters. When a transaction spans multiple UHLL messages (for example a POS Post Request followed by POS Post Request Data), they must appear in the array in ascending sequence order (sequence 0001 first … 9999, the last message of a transaction, last). NX emits and expects messages in this order.

4.3 Device Message Marker (DMM)

Every UHLL message carries NX's Comtrol-assigned DMM in its header. NX stamps its outbound messages with the DMM configured for the property; Lodging Link drops messages with the wrong DMM. The DMM value is part of your onboarding configuration.

4.4 No ACK / NAK on REST

Unlike the serial/TCP transport, the HTTP transport does not use link-level ACK/NAK messages. Lodging Link never sends them and ignores any it receives. Reliability comes from the poll cadence plus transaction-id correlation, not link-level acknowledgements.

5. Request flow & semantics

5.1 The two calls

GET /…/rest/inbound — NX returns any messages queued for the property:

HTTP/1.1 200 OK
Content-Type: application/json

{ "UHLL": [ "<message>", "<message>" ] }

or, when nothing is queued:

HTTP/1.1 200 OK

{ "UHLL": [] }

POST /…/rest/outbound — Lodging Link delivers the PMS's messages; NX may piggyback any freshly-queued outbound messages in the same 200 response:

POST /lodginglink/api/v16.0/rest/outbound
Authorization: Basic ...
Content-Type: application/json

{ "UHLL": [ "<PMS response message>" ] }

HTTP/1.1 200 OK

{ "UHLL": [ "<any newly-queued NX message>" ] }

If NX has nothing to piggyback, the response body is {"UHLL":[]}.

5.2 Always HTTP 200

NX always responds 200 OK to an authenticated request, even when the body is empty. Lodging Link reports non-200 responses to the PMS as connection errors, so NX never returns 204/404/error envelopes on the poll paths — an empty {"UHLL":[]} means "nothing right now." (Authentication failure is the single exception: an unauthenticated request returns 401.)

5.3 Correlation

Each NX request carries a UHLL transaction id (a 4-digit number in the message header) allocated per property. When the PMS responds, Lodging Link delivers a message carrying the same transaction id, which NX uses to match the response to the originating request. Preserve transaction ids and sequence numbers as-is.

5.4 Supported operations

Notes:

• A void is conveyed via the UHLL Void charge type — amounts stay positive (NX does not negate amounts).
• Currency fields are decimal strings (e.g. 46.00), consistent with the UHLL spec.
• A room charge is decomposed so that subtotals + taxes + service charges + tip + discounts == total, which the PMS requires (Opera denies a mismatch).

6. Site onboarding checklist

NX provides these at integration enablement — enter them into Lodging Link's configuration for the property:

• [ ] Base URL / host for the correct environment (production or test).
• [ ] Inbound path: /lodginglink/api/v{ver}/rest/inbound (GET).
• [ ] Outbound path: /lodginglink/api/v{ver}/rest/outbound (POST).
• [ ] UHLL version segment {ver} (e.g. v16.0).
• [ ] Basic-auth username + password (property-specific; password shown once).
• [ ] DMM assigned to this property.
• [ ] Poll interval — see §7 for the tradeoff; set per the property's needs.
• [ ] HTTP vs. HTTPS and certificate handling (HTTPS recommended).

Once configured, Lodging Link will begin polling NX automatically; no action is required on the NX side to "start."

7. Poll interval: latency vs. cost

The poll interval is configured inside Lodging Link at the site and is the single biggest factor in responsiveness. NX cannot make Lodging Link poll on demand — a request waits for the next poll.

Worst-case round-trip ≈ 2 × poll interval + PMS processing time (once to pick up NX's request, once to deliver the PMS's response). NX piggybacks queued messages on both endpoints to shave up to one interval off the pickup leg.

Recommendation: for properties where cashiers do interactive room charges at the point of sale, configure 3–5 s. Where lookups are infrequent, a longer interval (10–15 s) reduces load. Choose per the property's workflow.

8. Troubleshooting

For connection-level errors Lodging Link surfaces to the PMS, first confirm the base URL, path, version segment, and credentials against the onboarding packet.

9. Quick reference

# Poll for queued NX messages
curl -sS https://<host>/lodginglink/api/v16.0/rest/inbound \
  -H "Authorization: Basic $(printf '%s' 'USER:PASS' | base64)"
# → {"UHLL":["<message>", ...]}  or  {"UHLL":[]}

# Deliver a PMS response (and receive any piggybacked NX messages)
curl -sS -X POST https://<host>/lodginglink/api/v16.0/rest/outbound \
  -H "Authorization: Basic $(printf '%s' 'USER:PASS' | base64)" \
  -H "Content-Type: application/json" \
  -d '{"UHLL":["<PMS response message>"]}'
# → {"UHLL":[...]}  (piggybacked NX messages, or empty)

Contract summary

• Lodging Link polls NX; NX never initiates.
• Two paths: GET …/inbound, POST …/outbound.
• Basic auth per property, on every request.
• JSON envelope {"UHLL":[ ... ]}, ascending sequence order, correct DMM.
• Always 200 OK (empty body = nothing pending); 401 only for bad auth.
• No ACK/NAK. Correlation is by UHLL transaction id.
• Responsiveness is governed by the Lodging Link poll interval.