Skip to main content

Getting started

Goal: your first successful AirShoppingRS from the sandbox in under ten minutes. You'll need a terminal with curl (or Postman).

Try it locally

This repo ships the gateway (apps/ndc-api, port 3018) that routes NDC requests to the real offer/order services as the ndc channel. Start it with pnpm ndc:api (plus the domain services via scripts/dev-services.sh start) and use http://localhost:3018 as your base URL, with the sandbox client ndc-dev-client / ndc-dev-secret at /oauth/token. What it answers is on the Capabilities page; a message it does not implement answers 501.

1. Get sandbox credentials​

Request sandbox access (see Support). You'll receive either:

  • an OAuth 2.0 client-credentials pair — client_id + client_secret (primary), or
  • an API key for the X-API-Key header (sandbox shortcut).

2. Configure the base URL​

EnvironmentBase URLToken URL
Sandboxhttps://ndc.retailaer.comhttps://ndc.retailaer.com/oauth/token
Localhttp://localhost:3018 (run apps/ndc-api)http://localhost:3018/oauth/token

Production URLs are issued at go-live; the path and headers below are the stable part of the contract.

3. Get an access token​

curl -X POST https://ndc.retailaer.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" \
  -d client_secret="$CLIENT_SECRET"
# → { "access_token": "…", "token_type": "Bearer", "expires_in": 1800 }

Export it for the next step:

export TOKEN="…"   # the access_token value

4. Send your first AirShoppingRQ​

NDC messages are XML over HTTPS POST. The message is routed by both the URL path and the IATA-Message-Name header.

curl -X POST https://ndc.retailaer.com/24.4/AirShoppingRQ \
  -H 'Content-Type: application/xml' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'IATA-Message-Name: IATA_AirShoppingRQ' \
  --data-binary @air-shopping-rq.xml

Copy the exact body (air-shopping-rq.xml) from the IATA_AirShoppingRQ reference page or run the request straight from the Postman collection where it's prefilled.

5. Read the AirShoppingRS​

A 200 response carries an IATA_AirShoppingRS XML body containing the offers. See the IATA_AirShoppingRS reference page for the shape, and Errors & acknowledgements for how failures look on the wire.

6. Or skip the typing — use Postman​

Import the collection + sandbox environment, fill clientId / clientSecret, and Send any request. The collection fetches and refreshes the OAuth token for you, and ships a saved example response for every message.

Next steps​