Get started

Quickstart

Create a test key, book a flight, pay for it with the mock provider and read its timeline. About ten minutes.

You need the 1fly stack running locally (API on http://localhost:4000, dashboard on http://localhost:3000; see the repository README), curl, and optionally jq to pick values out of responses.

1. Create an account#

Open http://localhost:3000/signup and sign up with your e-mail, a password of at least 12 characters, your name and an account name (your agency or app). You become the owner of a new account on the Free plan.

The same thing over the API, if you prefer:

Shell
curl -X POST http://localhost:4000/v1/auth/signup \
  -H 'Content-Type: application/json' \
  -c cookies.txt \
  -d '{"email":"dev@example.uz","password":"correct-horse-battery","name":"Dilnoza Rahimova","accountName":"Sky Travel"}'

2. Create a test API key#

Go to http://localhost:3000/app/api-keys and choose Create key:

  • Name: something that says where it runs, for example quickstart.
  • Mode: Test.
  • Scopes: orders:read and orders:write. Add logs:read if you want to read request logs with this key.
  • Expires: 30 days is plenty for a trial.

The secret (1fly_test_ followed by 40 hex characters) is shown once. Copy it into your shell:

Shell
export ONEFLY_API_KEY=1fly_test_0123456789abcdef0123456789abcdef01234567

3. Create an order#

An order books one flight offer for its passengers. In production the offer comes from a search; for this test any well-formed offer works.

Shell
curl -X POST http://localhost:4000/v1/orders \
  -H "Authorization: Bearer $ONEFLY_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotencyKey": "quickstart-0001",
    "scenario": "happy",
    "offer": {
      "offerId": "off_9d1c",
      "supplier": "hy-ndc",
      "searchId": "srch_51ab",
      "fareBrand": "Standard",
      "mix": { "adults": 1, "children": 0, "infants": 0 },
      "price": { "amountMinor": 398000000, "currency": "UZS" },
      "segments": [
        { "from": "TAS", "to": "IST", "departAt": "2027-03-12T07:40", "arriveAt": "2027-03-12T10:05", "carrier": "HY", "flightNumber": "HY273" },
        { "from": "IST", "to": "TAS", "departAt": "2027-03-19T13:20", "arriveAt": "2027-03-19T19:30", "carrier": "HY", "flightNumber": "HY274" }
      ]
    },
    "passengers": [
      { "type": "ADT", "firstName": "AZIZ", "lastName": "KARIMOV", "birthDate": "1990-04-12", "gender": "M",
        "citizenship": "UZ", "documentNumber": "FA1234567", "documentExpiry": "2031-05-01" }
    ],
    "contact": { "email": "aziz@example.uz", "phone": "+998901234567" }
  }'
JSON
{ "order": { "id": "ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10", "reference": "K7QX2P", "status": "draft", "mode": "test" }, "created": true }

The call returns at once; booking continues in the background. Save the id:

Shell
export ORDER_ID=ord_0d6c3f8a2b9e4c1d8f7a6b5c4d3e2f10   # use the id from your response

Note

Run the same request again: you get the same order back with "created": false. That is the idempotency key at work. Use one key per purchase, so a retried request can never book twice.

4. Wait for payment#

Within a few seconds the order reaches awaiting_payment: passengers are checked, the price is confirmed and seats are held.

Shell
curl -s http://localhost:4000/v1/orders/$ORDER_ID \
  -H "Authorization: Bearer $ONEFLY_API_KEY" | jq '{status: .order.status, holdExpiresAt: .order.holdExpiresAt, payUrl: .live.payUrl, paymentId: .payments[0].id}'
JSON
{ "status": "awaiting_payment", "holdExpiresAt": "2026-11-17T10:15:00.000Z", "payUrl": "http://localhost:4000/v1/mockpay/ord_0d6c…/pay_418230995512", "paymentId": "pay_418230995512" }

In production you send the traveller to payUrl. The seats are held until holdExpiresAt (at most 15 minutes).

5. Simulate the payment#

In test mode, play the payment provider yourself by sending the webhook it would send:

Shell
export PAYMENT_ID=pay_418230995512   # from step 4

curl -X POST http://localhost:4000/v1/webhooks/mockpay \
  -H 'Content-Type: application/json' \
  -d "{\"orderId\":\"$ORDER_ID\",\"paymentId\":\"$PAYMENT_ID\",\"status\":\"held\",\"providerEventId\":\"evt_$(date +%s)\"}"
JSON
{ "received": true, "duplicate": false }

The order moves through paid_hold and issuing to issued in a few seconds. Try "status": "declined" with a reason first to see a declined card: the order keeps waiting, and a later held still succeeds.

6. Read the timeline#

Shell
curl -s http://localhost:4000/v1/orders/$ORDER_ID/timeline \
  -H "Authorization: Bearer $ONEFLY_API_KEY" | jq '.steps[] | {step, state, attempts}'
JSON
{ "step": "validate_passengers", "state": "succeeded", "attempts": 1 }
{ "step": "recheck_price", "state": "succeeded", "attempts": 1 }
{ "step": "book_seats", "state": "succeeded", "attempts": 1 }
{ "step": "create_payment", "state": "succeeded", "attempts": 1 }
{ "step": "await_payment", "state": "succeeded", "attempts": 1 }
{ "step": "issue_ticket", "state": "succeeded", "attempts": 1 }
{ "step": "capture_payment", "state": "succeeded", "attempts": 1 }
{ "step": "send_ticket", "state": "succeeded", "attempts": 1 }

events in the same response has every individual event in order. Read Chronology to learn how to interpret it.

Next#

  • Repeat step 3 with a new idempotencyKey and "scenario": "flaky_supplier" or "price_up" to watch retries and a price change. All scenarios: Test scenarios.
  • Handle failures properly: Errors.
  • Let an AI agent do all of this: MCP.
API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)