Quick start — run the API yourself

This page is for anyone who wants to see the integration work before wiring a PMS. You only need:

A computer with curl (Mac, Linux, or Windows terminal)
A sandbox API key from Nuitee Cloud onboarding
About 10 minutes

In simple terms — what you are doing

Think of Nuitee Cloud like a shop window for your hotels:

Step	What you tell Nuitee Cloud	Plain English
1	“Here is my hotel”	Register the property
2	“Here are my room types and rate plans”	Publish what you sell
3	“Here are prices and availability for these dates”	Update the shelf
4	“Call this URL when you need live price”	Register price-check webhook
5	“Call this URL when you have a booking”	Register reservation webhook

Steps 1–3 are you → Nuitee Cloud. Steps 4–5 save URLs where Nuitee Cloud → you later (you must build those pages separately).

Before you start

Copy your sandbox key from onboarding (never commit it to git).
Open a terminal.
Paste the block below and replace YOUR_SANDBOX_API_KEY.

export BASE="https://ari-dev.thehotelplanet.com/v1"
export KEY="YOUR_SANDBOX_API_KEY"

Optional: use a test property code you can recognize in logs:

export HOTEL="TEST001"
export ROOM="R1"
export RATE="BAR"

Step 0 — Check that the API is reachable

curl -sS "$BASE/push"
echo ""
curl -sS "$BASE/push/ari"
echo ""
curl -sS "$BASE/push/webhook/hc"
echo ""

What you should see: JSON or text indicating the services are up (exact body may vary).
If it fails: check VPN, firewall, and that BASE has no trailing slash typo.

Step 1 — Register a test hotel

What this does: Creates (or updates) hotel TEST001 in Nuitee Cloud.

curl -sS -w "\nHTTP %{http_code}\n" -X POST "$BASE/push/hotels" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d "[{
    \"hotelId\": \"$HOTEL\",
    \"hotelName\": \"Test Hotel\",
    \"currency\": \"USD\",
    \"isAvailable\": true,
    \"minChildAge\": 1,
    \"maxChildAge\": 12
  }]"

Success looks like:

{ "code": "200", "message": "Hotels updated successfully" }

Common problems:

HTTP	Message	Fix
401	Unauthorized API KEY	Wrong key or disabled key
400	validation error	`minChildAge` and `maxChildAge` must be greater than 0

Step 2 — Add a room and rate (product)

What this does: Links room R1 and rate BAR to your hotel so ARI can target them.

curl -sS -w "\nHTTP %{http_code}\n" -X POST "$BASE/push/products" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"hotelId\": \"$HOTEL\",
    \"products\": [{
      \"roomId\": \"$ROOM\",
      \"roomType\": \"double\",
      \"rateId\": \"$RATE\",
      \"isAvailable\": true,
      \"roomName\": \"Test Double Room\",
      \"rateName\": \"Best Available Rate\",
      \"occupancy\": { \"maxOccupancy\": 2, \"maxAdult\": 2, \"maxChild\": 0 }
    }]
  }"

Success looks like:

{ "code": "200", "message": "Hotel rates & rooms saved successfully" }

If you see Hotel ID is not found → run Step 1 first.

If you see RoomType is not valid → ask onboarding for allowed room type names (often lowercase, e.g. double).

Step 2b — Configure taxes (optional)

What this does: Adds a 20% VAT at property level. Skip if the property has no taxes.

curl -sS -w "\nHTTP %{http_code}\n" -X POST "$BASE/push/taxes" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"hotelId\": \"$HOTEL\",
    \"taxes\": [{
      \"type\": \"VAT\",
      \"valueType\": \"%\",
      \"value\": 20,
      \"appliedOn\": \"net\",
      \"appliedPer\": \"per_room_per_stay\",
      \"included\": true,
      \"payNow\": true
    }]
  }"

Success looks like:

{ "code": "200", "message": "Taxes saved successfully" }

Taxes can also be scoped to a specific room, rate, or room-rate pairing.

Step 3 — Push availability and price (ARI)

What this does: Tells Nuitee Cloud that room R1 / rate BAR is open for one week at $100/night with 5 rooms to sell.

curl -sS -w "\nHTTP %{http_code}\n" -X POST "$BASE/push/ari" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d "[{
    \"hotelId\": \"$HOTEL\",
    \"startDate\": \"2025-12-01\",
    \"endDate\": \"2025-12-07\",
    \"pricingModel\": \"unit\",
    \"data\": [{
      \"roomId\": \"$ROOM\",
      \"rates\": [{
        \"rateId\": \"$RATE\",
        \"price\": 100,
        \"inventory\": 5,
        \"stopSell\": false
      }]
    }]
  }]"

Success looks like:

{ "code": "200", "message": "ARI request saved successfully" }

If you see RoomID not found or RateID not found → run Step 2 with the same roomId and rateId.

Tip: Use "pricingModel": "unit" for a single price per room night. Use "guest" only when you send separate lines per adult/child — see ARI push guide.

Step 4 — Register webhooks (URLs on your server)

What this does: Saves where Nuitee Cloud should call your system later. Registration does not test your server — you still need to implement the endpoints.

Replace the URLs with your real HTTPS endpoints when ready:

curl -sS -w "\nHTTP %{http_code}\n" -X POST "$BASE/push/webhook/availability" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook":"https://your-company.example.com/hp/pricecheck"}'

curl -sS -w "\nHTTP %{http_code}\n" -X POST "$BASE/push/webhook/pushbook" \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook":"https://your-company.example.com/hp/reservations"}'

Success looks like:

{ "code": "200", "message": "Webhook request saved successfully" }

For local development, use a tunnel (e.g. ngrok) and paste the public HTTPS URL instead of your-company.example.com.

Step 5 — What you cannot test with curl alone

These need Nuitee Cloud booking flow or your live webhook server:

Test	Why
Price-check callback	Nuitee Cloud calls you during booking
Reservation push	Nuitee Cloud POSTs booking JSON to your URL
End-to-end book	Requires distribution/booking environment

Coordinate with onboarding for a supervised book test after Steps 1–4 succeed.

All-in-one script

Save as hp-ari-sandbox-test.sh, set KEY, then run bash hp-ari-sandbox-test.sh:

#!/usr/bin/env bash
set -euo pipefail

BASE="${BASE:-https://ari-dev.thehotelplanet.com/v1}"
KEY="${KEY:?Set KEY=your-sandbox-api-key}"
HOTEL="${HOTEL:-TEST001}"
ROOM="${ROOM:-R1}"
RATE="${RATE:-BAR}"

auth=(-H "x-api-key: $KEY" -H "Content-Type: application/json")

echo "== Health =="
curl -sS "$BASE/push" && echo
curl -sS "$BASE/push/ari" && echo

echo "== 1. Hotels =="
curl -sS -X POST "$BASE/push/hotels" "${auth[@]}" \
  -d "[{\"hotelId\":\"$HOTEL\",\"hotelName\":\"Test Hotel\",\"currency\":\"USD\",\"isAvailable\":true,\"minChildAge\":1,\"maxChildAge\":12}]"
echo

echo "== 2. Products =="
curl -sS -X POST "$BASE/push/products" "${auth[@]}" \
  -d "{\"hotelId\":\"$HOTEL\",\"products\":[{\"roomId\":\"$ROOM\",\"roomType\":\"double\",\"rateId\":\"$RATE\",\"isAvailable\":true,\"roomName\":\"Test Double\",\"rateName\":\"BAR\",\"occupancy\":{\"maxOccupancy\":2}}]}"
echo

echo "== 3. ARI =="
curl -sS -X POST "$BASE/push/ari" "${auth[@]}" \
  -d "[{\"hotelId\":\"$HOTEL\",\"startDate\":\"2025-12-01\",\"endDate\":\"2025-12-07\",\"pricingModel\":\"unit\",\"data\":[{\"roomId\":\"$ROOM\",\"rates\":[{\"rateId\":\"$RATE\",\"price\":100,\"inventory\":5,\"stopSell\":false}]}]}]"
echo

echo "Done. Register webhooks separately when your HTTPS URLs are ready."

Checklist — am I ready for production?

Steps 1–3 return 200 in sandbox
Same hotelId / roomId / rateId used everywhere
Price-check URL implemented and tested with onboarding
Push-booking URL returns 2xx and handles Confirm/Cancel
Production key + production URLs configured
ARI pushed for required forward window (confirm horizon with onboarding)

Where to go next

Static data — Hotels content
ARI push — Availability - Rate - Inventory
Booking — Retrieve/Push bookings
Webhooks — Receive notifications for the following actions: booking, cancellation, and price check.