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

# Introduction

> REST API for the PREXSELL bus booking platform.

The PREXSELL REST API exposes two surfaces — a **Distribution API** for agents
and PREXSELL's own client applications, and a **Backoffice API** for operators
and internal tooling. Each surface has its own authentication model and its own
group of endpoints in this reference.

## Client types

<CardGroup cols={2}>
  <Card title="Distribution API" icon="globe">
    For agents (third-party resellers), the PREXSELL website, and the PREXSELL
    app. Authenticated with a long-lived **API key** sent in the `x-api-key`
    header. Use this for booking flows, catalog reads, and any integration that
    runs outside the PREXSELL backoffice.
  </Card>

  <Card title="Backoffice API" icon="lock">
    For operators (bus companies) and internal tooling. Authenticated with
    **HTTP-only session cookies** issued by the login endpoints. Not intended
    for third-party use.
  </Card>
</CardGroup>

Distribution catalog endpoints (cities, stops) are read-only reference data.
They are listed under the Distribution API in this reference but are also
reachable from a Backoffice session — no separate group is needed.

## Base URL

<CodeGroup>
  ```bash Production theme={null}
  https://api.prexsell.com
  ```

  ```bash Staging theme={null}
  https://staging.api.prexsell.com
  ```
</CodeGroup>

All endpoints in this reference are versioned under `/v2`.

## Authentication

### Distribution API — API key

Distribution endpoints are authenticated with an API key passed in the
`x-api-key` header:

```bash theme={null}
curl https://api.prexsell.com/v2/cities \
  -H "x-api-key: <your-api-key>"
```

API keys are issued from the PREXSELL backoffice. Register as a PREXSELL partner at backoffice.prexsell.com (or staging.backoffice.prexsell.com for staging) to obtain one, and contact support if you need help. Keys are scoped to a single environment (staging vs production), so register in the environment you'll integrate against. Treat them as secrets — keep them on the server side, never ship them in browser or mobile bundles.

<Note>
  API-key enforcement is being rolled out across the v2 Distribution surface.
  Read-only catalog endpoints (cities, stops) are currently open while partner
  provisioning is finalized; pass the `x-api-key` header anyway so your client
  keeps working once enforcement turns on.
</Note>

### Backoffice API — session cookies

Backoffice endpoints use HTTP-only cookies set by the login flow:

<Steps>
  <Step title="Pre-login">
    `POST /v2/auth/pre-login` — verify credentials and discover the list of
    company contexts the user can log into. No session is created.
  </Step>

  <Step title="Login">
    `POST /v2/auth/login` with `email`, `password`, and the chosen `companyId`.
    The server automatically sets the access + refresh cookies
    (`backoffice_access_token`, `backoffice_refresh_token`) via `Set-Cookie`
    headers and returns the session payload — no client-side cookie handling
    required.
  </Step>

  <Step title="Call protected endpoints">
    Browsers send the cookies automatically on subsequent requests. Non-browser
    clients must store and replay the `Set-Cookie` values.
  </Step>

  <Step title="Refresh">
    When the access token expires, call `POST /v2/auth/refresh` with the refresh
    cookie. The server automatically rotates both cookies and returns a fresh
    session payload.
  </Step>
</Steps>

<Note>
  Google-based login is also supported via `/v2/auth/google/pre-login` and
  `/v2/auth/google/login`.
</Note>

## Quick start

<Tabs>
  <Tab title="Distribution (API key)">
    ```bash theme={null}
    # List cities — Distribution endpoint, API-key authenticated
    curl https://staging.api.prexsell.com/v2/cities \
      -H "x-api-key: <your-api-key>"
    ```
  </Tab>

  <Tab title="Backoffice (cookies)">
    ```bash theme={null}
    # 1. Log in — the server automatically sets the access + refresh cookies
    curl -X POST https://staging.api.prexsell.com/v2/auth/login \
      -H "Content-Type: application/json" \
      -c cookies.txt \
      -d '{
        "email": "user@example.com",
        "password": "your-password",
        "companyId": "cmp_xyz789"
      }'

    # 2. Use the cookies to call any backoffice endpoint
    curl https://staging.api.prexsell.com/v2/auth/me \
      -b cookies.txt
    ```
  </Tab>
</Tabs>

## Response envelope

Successful responses are wrapped in a `data` object:

```json theme={null}
{
  "data": { "...": "..." }
}
```

List endpoints additionally include a `total` counter for the unpaginated
result set and accept `take` (max 100, default 50) and `skip` (default 0)
query parameters.

## Errors

Errors are returned with an appropriate HTTP status and an `errors` array
describing what went wrong:

```json theme={null}
{
  "errors": [
    {
      "code": "UNAUTHORIZED",
      "message": "Missing or invalid credentials."
    }
  ]
}
```

Common status codes:

| Status | Meaning                                              |
| ------ | ---------------------------------------------------- |
| `200`  | Success.                                             |
| `201`  | Resource created.                                    |
| `204`  | Success, no response body.                           |
| `400`  | Validation error — check the request shape.          |
| `401`  | Missing or invalid API key / access token.           |
| `403`  | Authenticated, but not allowed to do this.           |
| `404`  | Resource not found.                                  |
| `409`  | Conflict — the resource is in an incompatible state. |
| `429`  | Rate limit exceeded.                                 |
| `500`  | Unexpected server error.                             |

## Next steps

<Card title="Getting started" icon="rocket" href="/guides/distribution-getting-started" horizontal arrow>
  Walk through a full Distribution integration end to end — search offers,
  create a booking, pay, and cancel.
</Card>