企业官网建设流程全解析

LetsFG PFS 航班搜索API完整指南：Bearer Token 四步完成搜索、轮询与真实订座

【免费下载链接】LetsFGAgent-native flight & hotel search and booking — MCP server, CLI, and Python/JS SDKs. Every airline in the world, major booking sites and OTAs, with per-flight reliability history.项目地址: https://gitcode.com/gh_mirrors/le/LetsFG

LetsFG 是一个面向 AI Agent 的航班与酒店搜索订座开源项目，其 PFS（Programmatic Flight Search）原始 API 让你仅凭一个 Bearer Token，四步就能完成航班搜索、结果轮询和真实出票订座——搜索免费、无需本地浏览器、看到的是多少钱就付多少钱。

PFS 原始API是什么？为什么选它

LetsFG 提供三条访问路径，PFS 是其中最适合脚本和 Agent 的"免费服务端"通道：

PFS 的全部搜索都运行在官方服务端，你不需要 Playwright、不需要自己爬航司网站。完整对比见 README.md 的 PFS 章节和 docs/getting-started.md。

一键获取 Bearer Token：连接无需卡片

letsfg.co 网站本身对人类用户设有人机验证，脚本无法直接访问，因此Bearer Token 是唯一合法的编程入口。获取流程只需一次点击，且不涉及任何扣款：

1. 将 LetsFG 添加为 MCP 服务器（或运行letsfg auth命令）；
2. 在打开的连接页面一次性授权——此时不需要卡片；
3. 卡片只在第一次订座时才被要求（0.00 元验证流程，卡信息交给支付渠道，不经过 LetsFG）。

Token 的存放与携带方式：

• SDK 和 CLI 从环境变量LETSFG_BEARER_TOKEN或~/.letsfg/config.json读取；
• 裸 HTTP 请求则在每个请求头中携带Authorization: Bearer <token>。

💡 限流规则：每张卡片每 10 分钟 10 次、每小时 30 次、每天 100 次搜索；轮询结果永远不计入额度。超限会返回 429 和retry_after_seconds，请按提示等待。

四步完整流程：搜索 → 轮询 → 订座 → 出票

以下四步对应原始 HTTP 端点，与 MCP 工具search_flights/get_flight_results/book_flight/get_flight_booking一一对应。

第一步：POST /api/search 发起航班搜索

请求体只需三要素：出发地、目的地、日期（支持自然语言查询）。服务端立即返回search_id：

curl -X POST https://letsfg.co/api/search \ -H "Authorization: Bearer <token>" \ -H "Content-Type: application/json" \ -d '{"origin":"LHR","destination":"BCN","date_from":"2026-06-15"}' # → {"search_id":"ws_abc123","status":"searching"}

首次结果通常在8–10 秒内到达。

第二步：GET /api/results/{search_id} 轮询搜索结果

拿到search_id后立即轮询（不要先睡眠再轮询），之后每隔 2 秒一次：

curl https://letsfg.co/api/results/ws_abc123 \ -H "Authorization: Bearer <token>"

两个关键细节：

• 搜索报告completed之后报价集合仍可能继续增长，响应中的split_ticket_pending标记为 true 时要继续轮询，否则你可能丢掉最便宜的行程；
• 搜索出的报价约15 分钟后过期，订座请趁新鲜，过期就重新搜索。

第三步：POST /api/agent-book 发起真实订座

把search_id、选中的offer_id和旅客真实信息（姓名须与护照一致、生日、国籍、电话、住址、联系邮箱）一起提交，数秒内返回booking_ref，票价随即被**冻结（hold）**在卡片上：

curl -X POST https://letsfg.co/api/agent-book \ -H "Authorization: Bearer <token>" -H "Content-Type": application/json" \ -d '{"search_id":"ws_abc123","offer_id":"wo_abc123","contact_email":"ada@example.com", "passenger":{"given_name":"Ada","family_name":"Lovelace","born_on":"1990-04-01", "gender":"f","nationality":"GB","phone_number":"+447700900000", "phone_country":"GB","address_line1":"1 Analytical Way", "address_city":"London","address_postal":"N1 9GU","address_country":"GB"}}' # → {"booking_ref":"eyJ...","state":"booking_in_progress"}

常见即时应答：缺字段返回missing_details+missing_fields（补上再调即可，不扣款）；尚未绑卡返回payment_method_required+add_card_url。

第四步：POST /api/agent-book/status 轮询出票状态

出票全程需要4–11 分钟，每 20–30 秒轮询一次状态端点，直到终态：

curl -X POST https://letsfg.co/api/agent-book/status \ -H "Authorization: Bearer <token>" -H "Content-Type": application/json" \ -d '{"booking_ref":"eyJ..."}'

资金安全设计：先冻结，出票后才扣款

这是 PFS 最值得理解的安全机制：

1. 订座开始时，票价只是被冻结在卡片上，不是划走；
2. LetsFG 订座代理替你在卖家处购买机票；
3. 只有真实航司 PNR 存在时，冻结才会转成扣款；订座失败则释放，分文不扣；
4. 结账期间票价若变动，你会收到price_change询问，接受或放弃都由你决定，绝不会"静默扣款"。

原来的 unlock（解锁报价）步骤已于 2026-09-08 退役，相关路由返回410 Gone——冻结-扣款机制让它彻底失去了存在必要。

新手常见坑清单

• ❌ 搜索后放着不订：报价约 15 分钟过期，请趁新鲜订座或重新搜索；
• ❌ 同一个行程同时发起两笔订座：会形成第二笔卡片冻结，进行中请只等结果；
• ❌ 轮询前加固定睡眠：首次结果 8–10 秒就到，应先轮询再等待；
• ❌ 用占位符旅客信息：卖家结账页需要全部真实字段，电子票会发到contact_email；
• ✅ 收到 429 时遵守retry_after_seconds，反复超限会升级封禁（10 分钟 → 6 小时 → 24 小时）。

延伸阅读

• 完整 Agent 构建指南与最佳实践：docs/agent-guide.md
• 快速上手（两条路径选型与首个搜索）：docs/getting-started.md
• Developer API 订座全流程（问题应答、中止订座、沙箱）：docs/api-booking.md
• 异步搜索与轮询详解：docs/api-polling.md
• 航班搜索 Skill 定义：skills/flight-search/SKILL.md
• Python SDK 实现：sdk/python/letsfg/

【免费下载链接】LetsFGAgent-native flight & hotel search and booking — MCP server, CLI, and Python/JS SDKs. Every airline in the world, major booking sites and OTAs, with per-flight reliability history.项目地址: https://gitcode.com/gh_mirrors/le/LetsFG