格物开放 API用户与收货地址

REST API · 接口参考

REST API 参考 · 消费者购物

用户与收货地址

用户身份直接用你那边每个用户的 open-id（放进 x-open-user），首次访问自动建档，不需要先注册。收货地址要用行政区划码，先用区划接口级联选出来；地址簿是可选的便利，不用也能下单。

#行政区划级联

GET/v1/divisions

行政区划级联（下单要的 divisionCode / townDivisionCode；老路径 /v1/lm/divisions 仍可用）

鉴权appKey

出现在福利 / 采购 · 额度与下单消费者 · 用户与地址

从 parent=1（全国）开始逐级下钻：省 → 市 → 区县（divisionCode）→ 乡镇街道（townDivisionCode）。与福利GO 小程序、网页商城的地址选择同一份数据。老路径 /v1/lm/divisions 仍可用，返回相同。企业购下单的 receiver.province / city / area 用这里选出的名称，乡镇街道名称放进 receiver.street；也可以把带区划码的地址存进地址簿，下单传 addressId。

查询参数

字段	类型	必填	说明
`parent`	string	否	上一级区划码。默认 `"1"`

返回字段

字段	类型	说明
`ok`	boolean
`items`	object[]
`items[].code`	string
`items[].name`	string
`items[].parentCode`	string
`items[].hasChildren`	boolean
`items[].level`	integer	2 省 / 3 市 / 4 区县 / 5 乡镇街道

调用示例

1curl -X GET "https://api.gowu.net/v1/divisions?parent=1" \2  -H "x-app-key: $GOWU_APP_KEY"

返回示例

1{2  "ok": true,3  "items": [4    {5      "code": "string",6      "name": "string",7      "parentCode": "string",8      "hasChildren": true,9      "level": 010    }11  ]12}

#地址簿列表 / 新增

GETPOST/v1/buyer/addresses

地址簿列表 / 新增（complete 标记能否直接下单）

鉴权用户态可选

GET

地址簿

可选：也可以不用地址簿，下单时直接传 receiver。默认地址在前。

返回字段

字段	类型	说明
`items`	object[]
`items[].id`	string
`items[].receiver`	string
`items[].receiverPhone`	string
`items[].province`	string
`items[].city`	string
`items[].district`	string
`items[].street`	string
`items[].divisionCode`	string
`items[].townDivisionCode`	string
`items[].addressDetail`	string
`items[].isDefault`	boolean
`items[].complete`	boolean	能否直接用于下单
`items[].missingFields`	string[]	缺哪些项（如 divisionCode、townDivisionCode）
`items[].createdAt`	string

POST

新增地址

请求体application/json

字段	类型	必填	说明
`receiver`	string	是
`receiverPhone`	string	是
`addressDetail`	string	是
`province`	string	否
`city`	string	否
`district`	string	否
`street`	string	否
`divisionCode`	string	否	传了会自动补齐省市区名称
`townDivisionCode`	string	否
`isDefault`	boolean	否

返回字段

字段	类型	说明
`ok`	boolean
`address`	object
`address.id`	string
`address.receiver`	string
`address.receiverPhone`	string
`address.province`	string
`address.city`	string
`address.district`	string
`address.street`	string
`address.divisionCode`	string
`address.townDivisionCode`	string
`address.addressDetail`	string
`address.isDefault`	boolean
`address.complete`	boolean	能否直接用于下单
`address.missingFields`	string[]	缺哪些项（如 divisionCode、townDivisionCode）
`address.createdAt`	string

错误

400 参数不合法

调用示例

1curl -X GET "https://api.gowu.net/v1/buyer/addresses" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001"

返回示例

1{2  "items": [3    {4      "id": "string",5      "receiver": "string",6      "receiverPhone": "string",7      "province": "string",8      "city": "string",9      "district": "string",10      "street": "string",11      "divisionCode": "string",12      "townDivisionCode": "string",13      "addressDetail": "string",14      "isDefault": true,15      "complete": true,16      "missingFields": [17        "string"18      ],19      "createdAt": "string"20    }21  ]22}

#改 / 设默认 / 删地址

PUTPOSTDELETE/v1/buyer/addresses/{id}

鉴权用户态可选

PUT

修改地址

整体覆盖：没传的字段会被清空。

路径参数

字段	类型	必填	说明
`id`	string	是

请求体application/json

字段	类型	必填	说明
`receiver`	string	是
`receiverPhone`	string	是
`addressDetail`	string	是
`province`	string	否
`city`	string	否
`district`	string	否
`street`	string	否
`divisionCode`	string	否	传了会自动补齐省市区名称
`townDivisionCode`	string	否
`isDefault`	boolean	否

返回字段

字段	类型	说明
`ok`	boolean
`address`	object
`address.id`	string
`address.receiver`	string
`address.receiverPhone`	string
`address.province`	string
`address.city`	string
`address.district`	string
`address.street`	string
`address.divisionCode`	string
`address.townDivisionCode`	string
`address.addressDetail`	string
`address.isDefault`	boolean
`address.complete`	boolean	能否直接用于下单
`address.missingFields`	string[]	缺哪些项（如 divisionCode、townDivisionCode）
`address.createdAt`	string

错误

400 参数不合法

POST

设为默认地址

路径参数

字段	类型	必填	说明
`id`	string	是

查询参数

字段	类型	必填	说明
`action`	string	是	固定为 default。可选值：`default`

返回字段

字段	类型	说明
`ok`	boolean	例：`true`

错误

404 资源不存在，或不归属你的 appKey / 当前用户

DELETE

删除地址

路径参数

字段	类型	必填	说明
`id`	string	是

返回字段

字段	类型	说明
`ok`	boolean	例：`true`

错误

404 资源不存在，或不归属你的 appKey / 当前用户

调用示例

1curl -X PUT "https://api.gowu.net/v1/buyer/addresses/{id}" \2  -H "x-app-key: $GOWU_APP_KEY" \3  -H "x-timestamp: $TS" \4  -H "x-nonce: $NONCE" \5  -H "x-sign-version: 2" \6  -H "x-signature: $SIG" \7  -H "x-open-user: u-001" \8  -H "content-type: application/json" \9  -d '{"receiver":"string","receiverPhone":"string","addressDetail":"string"}'

返回示例

1{2  "ok": true,3  "address": {4    "id": "string",5    "receiver": "string",6    "receiverPhone": "string",7    "province": "string",8    "city": "string",9    "district": "string",10    "street": "string",11    "divisionCode": "string",12    "townDivisionCode": "string",13    "addressDetail": "string",14    "isDefault": true,15    "complete": true,16    "missingFields": [17      "string"18    ],19    "createdAt": "string"20  }21}