Skip to content

宠物档案接口总览 ​

本页汇总宠物档案的公共约定、数据对象与校验规则。每个接口的完整请求、完整返回示例和字段说明见对应接口页。

统一 JSON 响应 ​

json
{
  "code": 200,
  "message": "success",
  "data": {}
}
字段类型说明
codeinteger200 表示成功;失败时为业务错误码,与 HTTP 状态一致。
messagestring状态提示信息:成功固定为 "success"(网关统一归一化),失败时为安全的中文提示。不要用它做程序判断。
dataany业务数据;结构与内容随接口变化。

列表不返回分页统计

列表接口接受 page、limit 等参数,但响应体只有 code、message、data 三个字段,不返回 page_info、total 或 total_pages。需要总数时请由接入方自行累计,或按返回条数是否等于 limit 判断是否还有下一页。

接口一览 ​

接口方法返回用途
/pets/pet-infoGET品种目录前置:查询标准品种库,取得创建/更新档案用的 breed_code。
/pet-profilesPOST单个档案创建宠物档案。
/pet-profilesGETdata 为档案数组分页查询档案列表。
/pet-profiles/{pet_profile_id}GET档案 + records查询档案详情。
/pet-profiles/{pet_profile_id}PATCH更新后的档案部分更新档案。
/pet-profiles/{pet_profile_id}DELETE{"id": 44}逻辑删除档案。

数据对象:PetProfile ​

字段类型可写说明
idinteger否宠物档案 ID,创建后由平台生成。
namestring是宠物名,创建必填,最长 64 个字符。
avatarstring | null是头像 URL,最长 500 个字符。
birthdaystring(date-time) | null是出生日期。
genderinteger | null是1 公、2 母、null 未知。
pet_typeinteger | null是1 猫、2 狗、3 异宠、null 未指定。
pet_varietystring | null是调用方填写的品种文本,最长 100 个字符。
breed_codestring | null是标准品种编码,最长 64 个字符。
weightstring | null是体重,带单位的字符串,如 "10.10kg",最长 20 个字符。
is_neuteredinteger | null是0 未绝育、1 已绝育、null 未知。
localestring否本次响应实际使用的展示语言。
breed_display_namestring | null否按 locale 返回的标准品种展示名。
created_at / updated_atstring(date-time)否创建与更新时间。
recordsobject否仅详情接口返回:按 record_type 分组的扩展记录;无记录时为 {}。

字段校验规则 ​

字段规则
name必填(创建时),最长 64 个字符。
gender只能是 1、2 或 null。
pet_type只能是 1、2、3 或 null。
is_neutered只能是 0、1 或 null。
breed_code非空时必须存在于平台标准品种库;pet_type 为猫或狗时品种类别必须匹配。
weight字符串,建议始终带单位(如 kg)。
birthdayISO 8601 date-time 字符串。未知值用 null,不要用空字符串。

错误处理 ​

HTTP 状态含义调用方处理
400业务规则不满足,例如 locale 未启用、品种与类型不匹配。读取 message 修正输入。
401 / 403Token 缺失、无效或权限不足。重新换取 Token;不要传递内部身份字段。
404档案不存在、已删除或不属于当前用户。刷新本地状态,不要当作可安全重试。
422字段类型、长度或格式不符合 Schema。按字段规则修正后重试。
429触发限流。退避后重试。
5xx服务或依赖暂时不可用。读取类可重试;写操作先确认上一次结果,避免重复创建。

未纳入本轮的接口 ​

宠物扩展记录(/pet-profiles/{pet_profile_id}/records 系列)在当前对外流程中没有被使用,因此本轮没有整理成接口页。需要时再单独评估。

最近更新

栖界开放平台 · API Documentation