> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seyaha.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner Quickstart

> Expose an OCTO-compatible API so Seyaha can sync your catalog and manage bookings.

To integrate with Seyaha you need to expose a set of HTTP endpoints on your platform.
Seyaha calls these endpoints to pull your product catalog, check availability, and manage
the booking lifecycle. This guide walks you through the minimum required implementation.

## What you need to implement

| Endpoint                                    | When Seyaha calls it                                 |
| ------------------------------------------- | ---------------------------------------------------- |
| `GET /products`                             | Nightly sync, manual sync triggers, health probes    |
| `POST /availability`                        | During sync (60-day window per option) + at checkout |
| `POST /bookings/reserve`                    | When a customer initiates checkout                   |
| `POST /bookings/confirm`                    | After the customer's payment succeeds                |
| `DELETE /bookings/{reservationCode}`        | When a hold is abandoned or expires                  |
| `POST /bookings/{externalBookingId}/cancel` | When a confirmed booking is cancelled                |

All of these are served from a single `base_url` that you register with Seyaha.

<Steps>
  <Step title="Stand up a /products endpoint">
    This is the only endpoint required to complete registration and start syncing.
    Return your full catalog as an array of [OCTO product objects](/api-reference/partner/list-products).

    ```json theme={null}
    GET /products
    Authorization: Bearer <your-auth-key>

    → 200 OK
    [
      {
        "id": "product_abc",
        "internalName": "Desert Safari Standard",
        "locale": "en",
        "timeZone": "Asia/Riyadh",
        "instantConfirmation": true,
        "options": [
          {
            "id": "option_xyz",
            "internalName": "Standard Package",
            "availabilityType": "START_TIME",
            "units": [
              {
                "id": "unit-adult",
                "internalName": "Adult",
                "type": "ADULT",
                "pricingFrom": [{ "original": 25000, "currency": "SAR", "currencyPrecision": 2 }]
              }
            ]
          }
        ]
      }
    ]
    ```

    <Note>
      `id` and option `id` are permanent keys — never change them after your first sync.
      Seyaha uses them to match incoming products to existing activities in the database.
    </Note>
  </Step>

  <Step title="Register your integration with Seyaha">
    Log in to the Seyaha partner portal and provide:

    * **Base URL** — the root of your OCTO API (e.g. `https://octo.yourplatform.com`)
    * **Auth type** — `bearer` or `api_key`
    * **Auth key** — the credential Seyaha will send in the `Authorization` header

    Seyaha will immediately probe `GET /products?limit=1` to verify connectivity.
    A Seyaha admin must then approve your integration before syncs run.
  </Step>

  <Step title="Implement /availability">
    Once your integration is approved, Seyaha fetches availability for each option
    during every sync. Add `POST /availability` that accepts:

    ```json theme={null}
    POST /availability
    {
      "productId": "product_abc",
      "optionId": "option_xyz",
      "localDateStart": "2026-07-01",
      "localDateEnd": "2026-08-30",
      "units": [{ "id": "unit-adult", "quantity": 1 }]
    }
    ```

    And returns an array of [availability slots](/api-reference/partner/query-availability).

    Each slot must have a stable `id` (`availabilityId`) — Seyaha caches this and
    uses it to identify the slot when creating a reservation.
  </Step>

  <Step title="Implement booking lifecycle endpoints">
    Once you want Seyaha to confirm bookings on your platform in real time,
    implement the three booking endpoints:

    1. `POST /bookings/reserve` — create a hold at checkout
    2. `POST /bookings/confirm` — confirm after payment
    3. `DELETE /bookings/{code}` — release abandoned holds

    And optionally `POST /bookings/{id}/cancel` for cancellation propagation.

    See [the booking lifecycle guide](/pages/partner/sync) for the full flow.
  </Step>
</Steps>

## Authentication

Seyaha sends your `auth_key` in every request. Validate it server-side:

| `auth_type` | Header Seyaha sends                |
| ----------- | ---------------------------------- |
| `bearer`    | `Authorization: Bearer <auth_key>` |
| `api_key`   | `Authorization: <auth_key>`        |

Return `401` for invalid credentials. Seyaha treats any non-2xx response as a failure
and increments the health failure counter.