概述
好停ParkingLink提供100+ RESTful API接口，支持停车场管理、订单处理、支付结算、数据统计等全业务场景。本文档将引导您在5分钟内完成首次API调用。所有接口均遵循RESTful设计规范，采用HTTPS加密传输，返回统一的JSON格式响应数据。
认证方式
好停API支持两种认证方式：JWT Token认证和OAuth 2.0认证。JWT Token认证适用于简单的服务端调用场景，通过client_id和client_secret换取access_token，每个Token有效期为2小时，到期后需调用刷新接口获取新Token。OAuth 2.0认证适用于需要多应用授权的复杂场景，通过authorization_code换取access_token和refresh_token，refresh_token有效期为30天，可用于长期免登场景。
JWT Token获取方式：联系好停商务团队申请API密钥（client_id和client_secret），然后调用认证接口POST /api/v1/auth/token获取access_token。请求体中传入client_id和client_secret，响应返回access_token和expires_in字段。后续所有API请求都需要在Header中携带Authorization: Bearer {access_token}。
OAuth 2.0认证流程：首先将用户引导至好停授权页面（https://api.parkinglink.cn/oauth/authorize），用户授权后会重定向到您的回调地址并携带authorization_code参数。使用authorization_code调用POST /api/v1/oauth/token接口换取access_token和refresh_token。
基础请求格式
所有API请求均使用JSON格式，请求头必须设置Content-Type为application/json，认证请求头为Authorization: Bearer {access_token}。API基础URL为https://api.parkinglink.cn，所有接口均通过HTTPS协议访问，不支持HTTP明文传输。
请求示例：GET请求直接在URL中携带查询参数，如/api/v1/parking/lots?city=beijing&page=1&size=20。POST/PUT/PATCH请求在请求体中传递JSON数据。分页接口统一使用page和size参数，page从1开始计数，size默认20最大100。
时间格式统一使用ISO 8601标准，如2026-07-01T10:30:00+08:00。金额单位统一为分（人民币），避免浮点数精度问题。
响应格式
所有API返回统一的JSON响应结构：code字段表示业务状态码，0代表成功，非0代表失败；message字段提供人类可读的状态描述；data字段包含实际的业务数据，可能是对象、数组或null。分页响应中data包含list（数据列表）、total（总记录数）、page（当前页码）、size（每页大小）四个子字段。
错误码说明
HTTP状态码层面：200表示请求成功，400表示请求参数错误，401表示认证失败或Token过期，403表示无权限访问该资源，404表示资源不存在，429表示请求频率超限，500表示服务器内部错误。
业务错误码：1001表示参数缺失，1002表示参数格式错误，1003表示停车场不存在，1004表示订单不存在，1005表示订单状态不允许当前操作，2001表示Token已过期，2002表示Token无效，2003表示没有访问权限，3001表示余额不足，3002表示支付渠道异常，4001表示Webhook签名验证失败，4002表示事件类型不支持。遇到错误时请先检查错误码和message字段，根据提示修正请求参数或联系技术支持。
5分钟首次调用示例
第一步：获取API密钥。联系好停商务团队（电话137-3262-6640或邮箱service@parkinglink.cn），申请API密钥，获取client_id和client_secret。第二步：获取Access Token。使用curl命令调用认证接口POST /api/v1/auth/token，将返回的access_token保存下来。第三步：调用业务接口。以查询停车场列表为例，使用curl命令携带access_token调用GET /api/v1/parking/lots接口，您将获得JSON格式的停车场列表数据。
curl示例：curl -X POST https://api.parkinglink.cn/api/v1/auth/token -H 'Content-Type: application/json' -d '{"client_id":"your_id","client_secret":"your_secret"}'。获取token后：curl https://api.parkinglink.cn/api/v1/parking/lots -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'。恭喜！您已成功完成首次API调用。