公开 API参考
REST 端点供将 PulseCargo 数据与自己的系统集成的租户使用 — ERP、BI 工具、货代门户、面向客户的应用。
概述
PulseCargo 公开 API 在 /api/v1/* 下公开出站端点，使用 API 密钥认证。API 目前是读取重点：货运、订单、集装箱、海关条目、发票和文件元数据。写入端点受层级限制，按集成伙伴逐个推出。
开发者门户 — 自助 API 密钥颁发、速率限制可视性和 OpenAPI 规范下载 — 在构建路线图中。目前，API 密钥颁发由租户管理员通过管理界面进行。
身份验证
所有 API 请求都需要有效的 API 密钥，通过 X-PulseCargo-Api-Key 头传递。密钥的作用域有两种方式：
- 租户 API 密钥 — 对租户数据的完全读取访问权限。由租户管理员通过管理界面颁发。
- 客户端 API 密钥 — 限制于单个客户端（租户的一个客户）。根据租户的数据可见性配置颁发。
curl -H "X-PulseCargo-Api-Key: pcg_live_..." \
https://api.pulsecargo.ai/api/v1/shipments密钥在 TenantApiKeys 和 ClientApiKeys 表中进行管理。支持轮换；撤销立即生效。
速率限制
每个 API 密钥的默认速率限制：
- 每分钟 60 个请求对公开状态端点（
/api/public-status）— 唯一的未认证端点。 - 租户协商的限制对认证端点。默认是慷慨的；每层阈值在管理界面中记录。如需提高，请与您的租户管理员联系。
速率限制响应头（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset）在每个响应中发送。
端点（读取）
| 方法 | 路径 | 描述 |
|---|---|---|
GET | /api/v1/shipments | 列出货运。按日期范围、路线、运输方式、状态筛选。 |
GET | /api/v1/shipments/{id} | 单个货运，包括里程碑、文件、费用。 |
GET | /api/v1/orders | 列出采购订单。按日期范围、客户、状态筛选。 |
GET | /api/v1/orders/{id} | 单个 PO，包括链接的货运和 ASN。 |
GET | /api/v1/containers | 跨货运的集装箱搜索。 |
GET | /api/v1/customs | 海关条目状态。 |
GET | /api/v1/invoices | 发票列表，带审计状态标志。 |
GET | /api/v1/invoices/{id} | 发票详情，包括行项目 + 审计异常。 |
GET | /api/v1/documents | 文件元数据。通过签署的 URL 下载。 |
GET | /api/public-status | 未认证的平台状态检查。 |
端点（写入 — 层级限制）
写入端点受层级限制，按集成伙伴协议推出。目前在专业层及以上可用：
| 方法 | 路径 | 描述 |
|---|---|---|
POST | /api/v1/orders | 创建采购订单。通过 eAdaptor 推送至 CargoWise。 |
PUT | /api/v1/orders/{id} | 更新采购订单。最后写入者获胜，冲突时警告。 |
POST | /api/v1/comments | 向货运/订单/集装箱线程发布评论。也在 CW eAdaptor 中呈现。 |
POST | /api/v1/products | 创建客户端产品（第 2 阶段进行中；CW Native 架构）。 |
写入端点遵循与读取端点相同的认证、速率限制和审计日志。每个成功的写入都记录在租户审计日志中，包括时间戳、用户 / API 密钥、源记录和结果。
Webhooks
支持出站 webhook 投递用于计划导出、SIEM 事件导出和 PayCargo 供应商付款事件。详见 webhook 参考，了解有效载荷架构、重试策略和签名验证。
审计日志
每个 API 调用都记录至 OutboundApiLogs，包括时间戳、API 密钥标识符、端点、响应代码和源 IP。租户管理员可通过管理界面查询日志以获取合规证据（SOC 2 CC4.1 / CC7.2）。
版本控制策略
API 在 URL 路径中进行版本控制（/api/v1/*）。破坏性变更在新版本下发布。前一个版本在后继版本发布后至少支持 12 个月，并通过响应头（Deprecation、Sunset）附带弃用通知。
非破坏性添加（新字段、新端点、扩展的枚举值）在主版本内发布而不通知。
SDK
官方支持的 SDK 尚未发布。OpenAPI 规范随每个版本发布；客户可从中生成特定语言的 SDK。SDK 可用性在构建路线图中；如果特定语言阻碍了您的集成，请联系我们以优先考虑。