# Quick start — your first ticket in 10 minutes

> **Issuing a ticket charges your agency wallet.** Run this guide on your platform's **test server** (same API, simulated airlines) with a key created there, then repeat it on the real one.

## 1. Get a key

In your panel open **Developers → API keys → Create key** and keep the default scopes. Copy the key (`tam_live_…`) — it is shown once.

```bash
export TAM_URL=https://quickota.com/api/v1
export TAM_KEY=tam_live_...
curl $TAM_URL/account -H "Authorization: Bearer $TAM_KEY"
```

## 2. Search

```bash
curl -X POST $TAM_URL/flights/search \
  -H "Authorization: Bearer $TAM_KEY" -H "Content-Type: application/json" \
  -d '{
    "slices": [{ "origin": "IKA", "destination": "IST", "departureDate": "2026-12-01" }],
    "passengers": { "adults": 1 },
    "maxResults": 5
  }'
```

Each offer has an `offerId`, an `expiresAt`, the itinerary (`slices` → `segments`), the price you pay (`price.total`), the fare conditions (`fare.refundable`, `fare.baggage`) and `seatsLeft`.

```json
{
  "data": {
    "offers": [{
      "offerId": "off_4Qb3…",
      "expiresAt": "2026-11-20T10:25:00Z",
      "price": { "total": { "amount": "180.00", "currency": "USD" } },
      "fare": { "brandName": "Economy Light", "cabin": "economy", "refundable": true, "baggage": [ … ] },
      "slices": [ … ],
      "seatsLeft": 9
    }],
    "warnings": []
  }
}
```

## 3. (Optional) Re-check the price and read the rules

```bash
curl -X POST $TAM_URL/flights/offers/off_4Qb3.../price -H "Authorization: Bearer $TAM_KEY"
curl $TAM_URL/flights/offers/off_4Qb3.../fare-rules -H "Authorization: Bearer $TAM_KEY"
```

If `priceChanged` is `true`, show the new price to the traveller before booking.

## 4. Hold the seats

```bash
curl -X POST $TAM_URL/flights/bookings \
  -H "Authorization: Bearer $TAM_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "offerId": "off_4Qb3...",
    "agencyReference": "ORDER-1042",
    "passengers": [{
      "type": "adult", "gender": "male", "firstName": "ALI", "lastName": "REZAEI", "birthDate": "1985-05-05",
      "document": { "type": "passport", "number": "P7654321", "issuingCountry": "IR", "expiryDate": "2031-01-01" }
    }],
    "contact": { "name": "Ali Rezaei", "email": "ali@example.com", "phone": "+989121111111" }
  }'
```

The booking comes back `held`, with the deadline to issue and what you can do next:

```json
{
  "data": {
    "id": "7c1e0a52-…",
    "bookingNumber": "FB-260-…",
    "agencyReference": "ORDER-1042",
    "status": "held",
    "isFinal": false,
    "deadlines": { "holdExpiresAt": "2026-11-20T10:40:00Z", "voidUntil": null },
    "nextActions": [
      { "action": "issue",  "method": "POST", "href": "/flights/bookings/7c1e…/issue",  "deadline": "2026-11-20T10:40:00Z" },
      { "action": "cancel", "method": "POST", "href": "/flights/bookings/7c1e…/cancel", "deadline": "2026-11-20T10:40:00Z" }
    ],
    "price": { "amountDue": { "amount": "180.00", "currency": "USD" }, … },
    "pnr": "X7K2QP"
  }
}
```

Holding costs nothing. If you do not issue before `holdExpiresAt`, the seats are released.

## 5. Issue (ticket)

```bash
curl -X POST $TAM_URL/flights/bookings/7c1e.../issue \
  -H "Authorization: Bearer $TAM_KEY" -H "Idempotency-Key: $(uuidgen)"
```

`amountDue` is taken from your wallet and the booking becomes `ticketed` with `ticketNumbers`. Some airlines confirm later: then the status is `issuing` — **wait** for the `flight.booking.ticketed` webhook or poll `GET /flights/bookings/{id}` every `pollAfterSeconds`. Never call issue again with a new key. Details: [Managing booking states](https://quickota.com/developers/guides/managing-booking-states.md).

## 6. Get the e-ticket

```bash
curl $TAM_URL/flights/bookings/7c1e.../documents/e-ticket -H "Authorization: Bearer $TAM_KEY" -o ticket.pdf
```

## Next steps

- Read [Managing booking states](https://quickota.com/developers/guides/managing-booking-states.md) — the most important page for a robust integration.
- Set up [Webhooks](https://quickota.com/developers/guides/webhooks.md) so you do not have to poll.
- Going live: create a key on the real server, use its base URL, and make sure your wallet has funds.