duffel

通过 Duffel Flights API 搜索、预订和管理航班。覆盖 300 多家航空公司（NDC、GDS、LCC）。在以下情况下使用：(1) 搜索城市之间的航班，(2) 比较价格和票价舱位，(3) 预订航班，(4) 检查预订状态，(5) 取消预订，(6) 查看座位图，(7) 查找机场/城市 IATA 代码。支持单程、往返、多乘客、舱位过滤和直达偏好。

# Duffel Flights

Search, book, and manage flights across 300+ airlines via the Duffel API.

## Setup

Set `DUFFEL_TOKEN` env var with your Duffel API access token.
Get one at https://app.duffel.com → Developers → Access Tokens.
Test tokens (prefix `duffel_test_`) use sandbox data with unlimited balance.

## Commands

### Search flights
```bash
python scripts/duffel.py search --from MIA --to LHR --date 2026-04-15
python scripts/duffel.py search --from MIA --to CDG --date 2026-03-15 --return-date 2026-03-22 --cabin business
python scripts/duffel.py search --from JFK --to LAX --date 2026-05-01 --nonstop --adults 2
```

Options: `--cabin economy|premium_economy|business|first`, `--nonstop`, `--adults N`, `--children N`, `--infants N`, `--sort price|duration`, `--max-results N`, `--json`

Results are numbered. Use the number with other commands.

### View offer details
```bash
python scripts/duffel.py offer 3
```
Shows segments, baggage, fare conditions (refund/change), available extras.

### Book a flight
```bash
python scripts/duffel.py book 3 --pax "RIBEIRO/FABIO MR 1977-01-31 fabio@ribei.ro +13059159687 BR m"
```
Pax format: `LAST/FIRST TITLE DOB EMAIL PHONE NATIONALITY GENDER`
- TITLE: MR, MRS, MS, MISS, DR
- GENDER: m or f
- Multiple passengers: repeat `--pax "..."` for each

Payment uses Duffel account balance. Top up at https://app.duffel.com.

### Check order status
```bash
python scripts/duffel.py order ord_0000XXXXX
```

### Cancel order
```bash
python scripts/duffel.py cancel ord_0000XXXXX           # Quote (shows refund amount)
python scripts/duffel.py cancel ord_0000XXXXX --confirm  # Execute cancellation
```

### Seat map
```bash
python scripts/duffel.py seatmap 3
```

### Airport/city lookup
```bash
python scripts/duffel.py places "new york"
```

## Typical workflow

1. `search` → browse numbered results
2. `offer N` → check details, baggage, conditions
3. `book N --pax "..."` → get PNR
4. `order <id>` → verify booking
5. `cancel <id>` → if needed

## Notes

- Offers expire (usually ~20 min). Re-search if expired.
- Test mode: unlimited balance, bookings on "Duffel Airways" (fake airline).
- Production: real airlines, real tickets. Balance must be funded.
- All commands support `--json` for raw API output.
- Last search saved to `/tmp/duffel-last-search.json` for index reference.
- For API details, see `references/api-guide.md` and `references/booking-flow.md`.

---

## 中文说明

# Duffel Flights

通过 Duffel API 在 300 多家航空公司中搜索、预订和管理航班。

## 设置

将 `DUFFEL_TOKEN` 环境变量设置为你的 Duffel API 访问令牌。
可在 https://app.duffel.com → Developers → Access Tokens 处获取。
测试令牌（前缀 `duffel_test_`）使用沙箱数据，余额无限。

## 命令

### 搜索航班
```bash
python scripts/duffel.py search --from MIA --to LHR --date 2026-04-15
python scripts/duffel.py search --from MIA --to CDG --date 2026-03-15 --return-date 2026-03-22 --cabin business
python scripts/duffel.py search --from JFK --to LAX --date 2026-05-01 --nonstop --adults 2
```

选项：`--cabin economy|premium_economy|business|first`、`--nonstop`、`--adults N`、`--children N`、`--infants N`、`--sort price|duration`、`--max-results N`、`--json`

结果带有编号。在其他命令中使用该编号。

### 查看报价详情
```bash
python scripts/duffel.py offer 3
```
显示航段、行李额、票价条件（退票/改签）以及可用的附加项。

### 预订航班
```bash
python scripts/duffel.py book 3 --pax "RIBEIRO/FABIO MR 1977-01-31 fabio@ribei.ro +13059159687 BR m"
```
乘客格式：`LAST/FIRST TITLE DOB EMAIL PHONE NATIONALITY GENDER`
- TITLE：MR、MRS、MS、MISS、DR
- GENDER：m 或 f
- 多名乘客：为每名乘客重复使用 `--pax "..."`

付款使用 Duffel 账户余额。可在 https://app.duffel.com 充值。

### 检查订单状态
```bash
python scripts/duffel.py order ord_0000XXXXX
```

### 取消订单
```bash
python scripts/duffel.py cancel ord_0000XXXXX           # Quote (shows refund amount)
python scripts/duffel.py cancel ord_0000XXXXX --confirm  # Execute cancellation
```

### 座位图
```bash
python scripts/duffel.py seatmap 3
```

### 机场/城市查找
```bash
python scripts/duffel.py places "new york"
```

## 典型工作流程

1. `search` → 浏览带编号的结果
2. `offer N` → 查看详情、行李额、条件
3. `book N --pax "..."` → 获取 PNR
4. `order <id>` → 核实预订
5. `cancel <id>` → 如有需要

## 注意事项

- 报价会过期（通常约 20 分钟）。过期后请重新搜索。
- 测试模式：余额无限，预订记于 “Duffel Airways”（虚构航空公司）名下。
- 生产模式：真实航空公司、真实机票。余额必须已充值。
- 所有命令均支持 `--json` 以输出原始 API 结果。
- 最近一次搜索保存到 `/tmp/duffel-last-search.json` 以供编号引用。
- 有关 API 详情，请参阅 `references/api-guide.md` 和 `references/booking-flow.md`。