CoopCycle API完全指南：API Platform资源、API Key认证与Webhook集成一次讲透
CoopCycle API完全指南API Platform资源、API Key认证与Webhook集成一次讲透【免费下载链接】coopcycle-webLogistics marketplace platform. Only for worker-owned business.项目地址: https://gitcode.com/gh_mirrors/co/coopcycle-webCoopCycle 是一个专为合作社所有制企业设计的物流与市场平台它的开放 API 让开发者可以快速对接订单、配送任务与商户数据。本文带你一次讲透 CoopCycle API 的三大核心能力API Platform 资源模型、API Key 认证机制以及Webhook 事件推送帮你从零打通与 CoopCycle 物流平台的集成。一、为什么选择 CoopCycle APICoopCycle 不只是送外卖它覆盖了一整套本地物流业务场景配送管理任务Task、配送Delivery、骑手与调度市场功能订单Order、餐厅/商户Store、支付Stripe 集成开放生态RESTful API、Webhook、OAuth2 与 API Key 双认证体系对于新手来说最大的优势是你不需要读源码也能玩转它的 API——因为内置了在线接口文档。二、API 快速上手打开 Swagger 文档发出第一个请求CoopCycle 的 API 完全构建在API PlatformSymfony 生态的 REST API 框架之上。核心配置位于config/packages/api_platform.yaml几个关键信息配置项说明文档入口启用 Swagger UIenable_swagger_ui: true访问/api/docs即可在线调试数据格式支持 JSON-LD、JSON、CSV、HTML 四种格式分页支持客户端指定每页数量上限100 条/页版本API 版本1.0.0想改接口API Platform 资源定义在哪里所有 API 资源以 PHP 实体 属性注解的方式声明分为两个目录src/Api/Resource/—— 对外暴露的 API 资源如Webhook.php、CykeWebhook.phpsrc/Api/Dto/—— 数据传输对象DTO用于定制请求/响应结构每个资源类上都带有#[ApiResource]注解直接声明了允许的操作GET/POST/PUT/DELETE以及对应的权限规则比如Webhook资源规定创建操作需要create权限。这种注解即接口的写法让接口权限一目了然。三、API Key 认证三步搞定身份验证 CoopCycle 支持四种认证方式其中API Key 是最简单的一种适合脚本、定时任务等轻量场景创建 API App管理员在后台创建一个类型为api_key的应用对应src/Entity/ApiApp.php实体系统会生成以ak_开头的密钥并可绑定到指定商户Store或餐厅Shop实现数据隔离携带令牌请求在 HTTP 请求头Authorization: Bearer ak_xxxxx中传入密钥自动鉴权src/Security/ApiKeyManager.php检测到令牌以ak_前缀开头时走 API Key 认证通道否则自动回退到 JWT、OAuth2 等其他方式逻辑集中在src/Security/BearerTokenAuthenticator.php。怎么选认证方式服务器端脚本用 API Key需要代表用户操作的前端应用用 JWTX-CoopCycle-Session头第三方系统深度集成用 OAuth2。四、Webhook 集成订单与配送状态自动推送 轮询 API 又慢又浪费Webhook 让你在事件发生时实时收到推送。支持的 Webhook 事件定义在src/Entity/Webhook.php中共 7 种事件触发时机delivery.assigned配送任务已指派骑手delivery.started骑手开始配送delivery.picked已取货delivery.in_transit配送途中delivery.completed配送完成 ✅delivery.failed配送失败order.created新订单创建创建 Webhook 并验证签名两步走第一步使用 OAuth 访问令牌向POST /api/webhooks提交 JSON只需两个字段{ event: delivery.completed, url: https://example.com/webhook }创建成功后响应会一次性返回secret密钥——请务必保存之后查询接口不会再次显示。第二步在你的回调服务中验证签名。src/MessageHandler/WebhookHandler.php会对推送体做 HMAC-SHA256 签名放在请求头X-CoopCycle-Signature中。用你的secret对收到的 JSON 体计算同样的签名并比对即可确认推送确实来自 CoopCycle防止伪造请求。推送体结构很简单{ data: { object: /api/deliveries/1, event: delivery.completed } }拿到object中的 IRi 链接后再回查 API 即可获取完整详情。此外系统还会通过WebhookExecution实体记录每一次推送的执行结果方便排查失败原因。完整的 Webhook 行为测试用例可参考features/webhooks.feature。五、常见问题排查清单 ️现象可能原因请求返回 401API Key 未以ak_开头或密钥已失效请求返回 403API App 绑定的商户/餐厅与所访问数据不匹配Webhook 收到 400event字段不在上面 7 个合法事件之列签名校验失败未使用原始 JSON 字符串而非重新序列化后的计算 HMAC六、总结三件事打通 CoopCycle 集成看文档从 Swagger UI 出发API Platform 资源定义在src/Api/Resource/与src/Api/Dto/选认证脚本用 API Keyak_前缀应用集成用 JWT / OAuth2接推送通过/api/webhooks订阅配送与订单事件用X-CoopCycle-Signature保障安全。完成这三步你的系统就能与 CoopCycle 物流平台顺畅协作把配送、订单、商户数据纳入自己的业务流。【免费下载链接】coopcycle-webLogistics marketplace platform. Only for worker-owned business.项目地址: https://gitcode.com/gh_mirrors/co/coopcycle-web创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考