Technical Integration

Overview

This guide provides technical details for integrating with the NewSkies PriceFile API.

Authentication Setup

OAuth 2.0

The API uses OAuth 2.0 for authentication. Include your access token in the Authorization header:

Authorization: Bearer <your_access_token>

Each API key is linked to a specific pricefile via the app registration. The file mapping determines which pricefile(s) you can access.

PriceFile Mapping

Important: After creating your app in the developer portal, you must request file mapping:

1. Note your app name from the developer portal
2. Email api.flightproduction@tui.com with:
   • Your app name (as shown in the developer portal)
   • The pricefile(s) you need access to

Without proper mapping, your API requests will fail with an error response.

Integration Steps

1. Obtain Credentials

Register an app in the TUI Developer Portal to obtain your client ID and secret.

2. Request File Mapping

Contact the NSCC team to map your app to the correct pricefile. Access must be approved.

3. Test Connectivity

Test basic connectivity using the timestamp endpoint:

curl -X GET "https://playground.api.tui/flight/newskies/pricefile/download/{filename}/timestamp" \
  -H "Authorization: Bearer <your_access_token>"

Expected response:

{
  "fileName": "your_pricefile.zip",
  "timeStamp": "2026-06-15T09:25:36Z"
}

4. Download a PriceFile

curl -X GET "https://playground.api.tui/flight/newskies/pricefile/download/{filename}" \
  -H "Authorization: Bearer <your_access_token>"

Expected response body (truncated):

VGhpc1dpbGxCZVlvdXJCYXNlNjRFbmNvZGVkWmlwQXJjaGl2ZQ==...

The response is a base64-encoded string, as reflected in the Content-Transfer-Encoding: base64 header.

5. Decode the Response

Since the response body is base64 encoded you must decode it before extracting the zip archive:

bash

# Decode the base64 response to a zip file
base64 --decode pricefile_encoded.txt > pricefile.zip

# Extract the CSV content
unzip pricefile.zip

python

import base64
import requests

response = requests.get(url, headers={"Authorization": f"Bearer {token}"})
zip_data = base64.b64decode(response.content)
with open("pricefile.zip", "wb") as f:
     f.write(zip_data)

powershell

[System.Convert]::FromBase64String((Get-Content responseBody.txt)) | Set-Content priceFileArchive.zip -Encoding Byte

Best Practices

Efficient Polling

• Use /download/{filename}/timestamp to check if a new file is available before downloading
• Files are regenerated approximately every 15 minutes

Error Handling

• Always check response status codes
• Handle 401 errors by refreshing your access token
• Implement retry logic for 5xx errors with exponential delay

Error Responses

All error responses return JSON with this structure:

{
  "errorMessage": "Description of what went wrong",
  "exception": null
}

The exception field may contain additional error details or be null.

Common Error Messages

Status	Error Message	Endpoint	Meaning
400	"No price file mapped to ApiKey YourAppName"	/download/{filename}, /download/{filename}/timestamp	Your app has no pricefile mapping configured
400	"Pricefile {filename} not mapped to ApiKey YourAppName"	/download/{filename}, /download/{filename}/timestamp	You requested a file your app doesn't have access to
400	"No price file delta mapped to ApiKey YourAppName"	/download/delta, /download/delta/timestamp	No delta file is configured for your app
404	"Failed to load file {filename}: The specified key does not exist."	/download/delta, /download/{filename}	The file is mapped but doesn't exist in storage — contact support

For mapping-related errors, contact api.flightproduction@tui.com to verify your app configuration.

Apigee-Level Errors

These errors come from the API gateway before reaching the backend:

Status	Error	Meaning
401	"Invalid Access Token"	OAuth token is expired or malformed — obtain a fresh token
403	"Invalid API call as no apiproduct match found"	Your app is not approved for the "NewSkies PriceFile Api" product

Response Structure

Download Endpoints (/download/{filename}, /download/delta)

• Content-Type: application/zip
• Body: base64-encoded zip archive
• Header: Content-Transfer-Encoding: base64

Timestamp Endpoints (/download/{filename}/timestamp, /download/delta/timestamp)

{
  "fileName": "your_pricefile.zip",
  "timeStamp": "2026-06-15T09:25:36Z"
}

Environment-Specific Configuration

Environment	Base URL	Purpose
Playground	https://playground.api.tui/flight/newskies/pricefile	Integration testing
Production	https://prod.api.tui/flight/newskies/pricefile	Live environment

Troubleshooting

401 Unauthorized

• Verify your access token is valid and not expired
• Check the Authorization header format: Bearer <token>
• Ensure your app has been approved for the "NewSkies PriceFile Api" product

File Not Found / Empty Response

• Verify your app has been mapped to a pricefile (contact NSCC team)
• Check you're using the correct environment
• For /download/{filename}, ensure the filename matches exactly (including extension)

Apigee Error: "InvalidAPICallAsNoApiProductMatchFound"

• Either, your API credentials are not associated with the PriceFile API product
• or, your registration is still waiting for approval

Corrupted File After Download

• Ensure you're base64-decoding the response before saving as zip
• Check the Content-Transfer-Encoding header is base64