Perlatours Booking API

# Perlatours Booking API — Integration Guide

You are an AI coding assistant helping a developer integrate with the Perlatours Booking API.
Read this entire prompt before starting. Follow each phase in order. Ask clarifying questions when needed.

## Documentation
Full reference: https://developers.perlatours.com

## About the client's system
> ⚠️ IMPORTANT: Replace this block with a description of YOUR system.
> Include: programming language, framework, database, how you handle HTTP calls,
> whether you have an existing booking system, and what your end goal is
> (e.g., "search and book hotels from our travel agency website").
>
> Example:
> "We are a travel agency using Node.js + Express with PostgreSQL.
> We use axios for HTTP calls. We want to let our customers search
> and book hotels through our website. We already have a payment
> system with Stripe."

[DESCRIBE YOUR SYSTEM HERE]

---

## Phase 1: Authentication Setup

**Goal:** Configure JWT Bearer authentication.

- Base URL: `https://api.perlatours.com`
- All requests require header: `Authorization: Bearer <YOUR_JWT_TOKEN>`
- The token is permanent (provided by Perlatours), no refresh flow needed.
- Test it by calling any endpoint — a 401 means the token is invalid.

**Action:** Create a base HTTP client/service in my project that:
1. Sets the base URL
2. Adds the Authorization header to every request
3. Handles common errors (401, 429, 500)

---

## Phase 2: Understand the Response Format

All API responses follow this structure:

```json
{
  "success": true,
  "errorCode": null,
  "errorMessages": [],
  "warningMessages": [],
  "data": { ... }
}
```

**Important patterns:**
- `success: true` → operation worked, read `data`
- `success: false` → read `errorMessages` for details
- GetHotels returns PAGINATED: `data.data` (array inside pagination object)
- Catalog endpoints (MealPlans, RoomTypes, etc.) return: `data` directly as array
- HTTP 429 = rate limited (Search endpoint only, 1-second fixed window)

**Action:** Create a response parser/wrapper that handles both patterns.

---

## Phase 3: Load Inventory Data (Optional but Recommended)

Before searching, load reference data to understand IDs in search results.

| Endpoint | Method | Path | Body | Returns |
|----------|--------|------|------|---------|
| Hotels | POST | /Inventory/GetHotels | `{ "ids": [163608], "pageNumber": 1, "pageSize": 10 }` | Paginated (data.data) |
| Meal Plans | POST | /Inventory/GetMealPlans | `{ "language": "EN" }` (optional) | Array |
| Room Types | POST | /Inventory/GetRoomTypes | `{ "language": "EN" }` (optional) | Array |
| Room Amenities | POST | /Inventory/GetRoomAmenities | `{ "language": "EN" }` (optional) | Array |
| Hotel Types | POST | /Inventory/GetHotelTypes | `{ "language": "EN" }` (optional) | Array |
| Hotel Categories | POST | /Inventory/GetHotelCategories | `{ "language": "EN" }` (optional) | Array |
| Hotel Chains | POST | /Inventory/GetHotelChains | `{ "language": "EN" }` (optional) | Array |
| Markets | GET | /Inventory/Markets | None | Array |
| Nationalities | GET | /Inventory/Nationalities | None | Array |
| Currencies | GET | /Inventory/Currencies | None | Array |
| Languages | GET | /Inventory/Languages | None | Array |
| All Countries | GET | /Inventory/AllCountries | None | Array |
| All Currencies | GET | /Inventory/AllCurrencies | None | Array |
| All Languages | GET | /Inventory/AllLanguages | None | Array |
| Booking Flow Statuses | GET | /Inventory/BookingFlowStatuses | None | Array |

**Important:** POST endpoints accept an optional JSON body with filters. GET endpoints have no body.

**Action:** Create services/functions to fetch and cache inventory data.

---

## Phase 4: Implement Search

**POST /Booking/Search**

```json
{
  "hotelIds": ["163608"],
  "checkIn": "2026-09-01",
  "checkOut": "2026-09-05",
  "occupancies": [
    { "paxAges": [30, 28] }
  ],
  "metadata": {
    "market": "ES",
    "currency": "EUR",
    "language": "EN",
    "nationality": "ES"
  }
}
```

**Key rules:**
- `occupancies` uses `paxAges` — a flat list of ages per room (e.g. [30, 28] = two adults aged 30 and 28; [35, 8] = one adult + one child age 8)
- `checkIn` must be a future date
- `checkOut` must be after `checkIn`
- `hotelIds` accepts both strings and numbers
- `metadata` values must match your credential's allowed markets/currencies (use inventory endpoints to discover valid values)
- Each result option contains a `searchToken` — save it for the next step

**Response structure:**
```
accommodations[] → options[] → { searchToken, price, rooms[], cancellationPolicy, mealPlanId }
```

**Action:** Implement search and display results. Save `searchToken` from selected option.

---

## Phase 5: Implement Prebook

**POST /Booking/Prebook**

```json
{
  "searchToken": "<token from search>"
}
```

**Response:** Returns updated price, cancellation policy, and a `prebookToken`.
- Compare price with search — it may have changed
- Show cancellation policy to the customer before confirming
- Save `prebookToken` for booking

**Action:** Implement prebook flow. Show price confirmation to user.

---

## Phase 6: Implement Book

**POST /Booking/Book**

```json
{
  "prebookToken": "<token from prebook>",
  "clientReference": "YOUR-REF-001",
  "holderName": "John",
  "holderSurname": "Smith",
  "paxes": [
    { "name": "John", "surname": "Smith", "age": 30 }
  ],
  "remarks": "Late check-in requested"
}
```

**Key rules:**
- `paxes` surname is optional, `name` and `age` are required
- If `paxes` is empty, holder becomes first pax, others are UNDEFINED
- Response includes `locator` — THIS IS THE BOOKING ID for all future operations
- Save the `locator` in your database

**Action:** Implement booking with guest data collection. Store `locator`.

---

## Phase 7: Implement Get Booking

**POST /Booking/GetBooking**

```json
{
  "locator": "<booking locator>"
}
```

**Note:** The response uses field name `booking` (not `option` like Book).

**Action:** Implement booking detail retrieval.

---

## Phase 8: Implement Cancel

**POST /Booking/Cancel**

```json
{
  "locator": "<booking locator>"
}
```

**Response includes:**
- `status`: "CANCELLED" if successful
- `price`: cancellation penalty cost (null if no penalty)
  - `price.netAmount`: penalty amount
  - `price.currency`: currency code

**Note:** In sandbox, all bookings are fully refundable (price = null).
In production, check cancellationPolicy deadlines before cancelling.

**Action:** Implement cancellation with penalty display.

---

## Phase 9: Error Handling Checklist

Implement handling for:
- [ ] HTTP 401 → Invalid/expired token
- [ ] HTTP 429 → Rate limited, implement retry with backoff
- [ ] HTTP 400 → Validation error, show errorMessages to developer
- [ ] `success: false` → Business error, show errorMessages to user
- [ ] Network timeouts → Retry with exponential backoff
- [ ] Price changed between Search and Prebook → Show updated price

**Error categories (by errorCode range):**
- 1000-1999: Validation errors
- 2000-2999: Authentication errors
- 4000-4999: Business errors (no availability, already cancelled)
- 5000-5999: Provider/connector errors
- 8000-8999: Rate limit errors

---

## Complete Flow Summary

```
Search (hotelIds, dates, occupancies)
  ↓ searchToken
Prebook (searchToken)
  ↓ prebookToken + confirm price
Book (prebookToken, guests, reference)
  ↓ locator
GetBooking (locator) ← check status anytime
Cancel (locator) ← if needed
```

## Rate Limiting
- Only Search is rate-limited
- Fixed window: 1 request per second (configurable per credential)
- Response headers: X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After