帮助中心 · 面向航空公司管理人员

集成：API 密钥、Webhook 和运行 API

你航空公司的数据可以接入你自己的工具：Discord 机器人、你的网站、电子表格。这里的一切都在 管理 → 航空公司设置 → 设置 的集成标签页上。你需要 航空公司设置和运行密钥 权限；只管理 Discord 的管理人员看不到这个标签页。

运行 API 密钥

创建密钥 会给航空公司一个密钥，它可以读取运行 API 中的所有内容，但不能修改任何东西。它只显示一次；只保留一个指纹，所以请立即复制。如果丢了，就生成一个新的（旧的会失效）。密钥属于创建它的管理人员：如果他离开航空公司，或失去管理权限或这些权限，密钥就会失效，需要由有权限的人重新生成。

每次请求都用请求头 Authorization: Bearer your-key 发送它。在网站上打开 /api/v1/ops 查看所有地址；主要的有：

/api/v1/ops/flights：现在在空中的航班，以及最近几分钟内提交的航班及其 PIREP 结果。
/api/v1/ops/pireps：已决定的 PIREP（已接受、已拒绝等）的历史，最早的决定在前，包括航线、时间、飞机、着陆率和积分。
/api/v1/ops/pilots 和 /api/v1/ops/pilots/FCV0002：花名册，以及某位飞行员的等级、枢纽、小时和位置。
/api/v1/ops/routes、/api/v1/ops/fleet、/api/v1/ops/events 和 /api/v1/ops/ranks：时刻表、机队（机型和每架飞机）、即将举行的活动和等级阶梯，可用于你自己的网站。

每个地址都只能读取。每个密钥每分钟最多 120 次请求。

示例

你的花名册，每次 100 位飞行员：curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pilots?limit=100&offset=0"
接下来的 100 位：同样的请求加上 offset=100。回答中的 next_offset 说明下一页从哪里开始，在最后一页为 null；total 说明总共有多少。不带 limit 时会一次返回整个列表。
你的机队：curl -H "Authorization: Bearer your-key" https://vaeroly.com/api/v1/ops/fleet
10 月 1 日以来决定的 PIREP：curl -H "Authorization: Bearer your-key" "https://vaeroly.com/api/v1/ops/pireps?since=2026-10-01&limit=200"
再下一页：加上 cursor= 和回答中的 next_cursor。保存你拿到的最后一个 next_cursor，中断后你的工具就能从那里继续。之后决定发生变化的 PIREP 会带着新状态再次出现。决定满 2 分钟后才会列出，所以一页永远不会漏掉正在保存的决定。

API 永远不会显示什么

API 永远不会给出邮箱地址或其他任何私密内容。飞行员的隐私选择在这里和在网站上一样有效：

在实时地图中隐藏航班的飞行员不会出现在 /flights 或 /pireps 中。
不上排行榜的飞行员在 /pireps 中不带名字列出（"pilot": null），所以他们的航班无法被排名。
账户即将被删除的飞行员在所有地方都不会出现。

命名的 API 密钥

开启 命名的 API 密钥（可选功能）后，可以为每个工具单独生成一个密钥，每个只允许它需要的权限：航班、飞行员、航班表 或 飞行员变更（开启或关闭飞行员的活跃度豁免）。航班涵盖 /flights 和 /pireps；航班表 涵盖航线、机队、活动和等级。密钥可以设定到期日期，也可以单独吊销。每家航空公司最多 10 个；列表会显示每个密钥上次使用的时间。

Webhook

开启 Webhook 后，当发生某件事时，你自己的服务器会在几秒内收到一条消息：PIREP 被提交或审核、飞行员加入或离开、等级变化、预订被创建或取消、航班起飞。每条消息都有签名，你的服务器可以核实它来自 Vaeroly（X-Vaeroly-Signature 请求头，用 Webhook 的密钥对时间戳和正文计算的 HMAC）。

Webhook 和 API 一样遵守飞行员的隐私选择。在实时地图中隐藏航班的飞行员，或账户即将被删除的飞行员，不会发送预订、起飞或 PIREP 消息。不上排行榜的飞行员在 PIREP 消息中不带名字（"pilot": null）。关于飞行员加入、离开或等级变化的消息对所有人都会发送，和 /pilots 的列出方式一样。

还要在你的服务器上检查两件事。X-Vaeroly-Timestamp 请求头是消息签名的时间，单位为 Unix 秒：拒绝时间戳与你服务器时钟相差超过 5 分钟的消息，这样被复制的消息就不能在之后重放给你（每次重试都会重新签名，所以重试能通过）。另外，同一条消息可能不止一次到达你那里，例如你的服务器收到了消息但回答太慢，于是又重试了一次：一条消息的每次尝试都带有相同的 X-Vaeroly-Delivery 编号，所以把你处理过的编号保留几天，跳过已经见过的。在日志中用 再次发送 重发的投递是一次新的投递，带有新编号。

失败的投递会重试大约 15 小时。每个 Webhook 都有投递日志和 发送测试 按钮。连续失败 3 天的 Webhook 会被关闭，所有者会收到邮件。每家航空公司最多 5 个（在 Webhook 上打开 日志和设置 查看日志和测试按钮）。每个 Webhook 每 30 秒可以发送一次测试或重发一次投递，一家航空公司每小时可以发送 20 次测试和重发。