update_address

编辑用户已保存的某个地址。只允许两种改法：单独改 tag（重新打标，配送目标不变），或 suggestion_token + address_detail 改位置 / 门牌（网关会用新 POI 在上游重新注册地址，并把同一条记录指向新地址）。收货人姓名 / 电话在这里不可改（如需改请走 select_address）。address_id 保持不变。

地址链路：search_addresses 搜地点得到建议的 token → select_address 保存地址得到 address_id → update_address 编辑已保存地址。改位置 / 门牌前必须先调 search_addresses 拿到对应地点的 suggestion_token，因为上游只认已注册的配送地址，改位置实质是「重新注册」而非文本编辑。

两种改法：

仅改 tag（不传 suggestion_token） → 直接更新标签，配送目标不动。此时若 address_detail 与当前值不同且非空，返回 ADDRESS_UPDATE_REQUIRES_TOKEN。
传 suggestion_token + address_detail → 用新 POI 在上游重新注册配送地址，沿用该记录原有收货人，写回同一条记录的位置 / 门牌；address_id 与收货人不变。此时 address_detail 为空白返回 DETAIL_REQUIRED。

参数

参数	类型	必填	默认	说明
`consent_grant_id`	string	是	—	用户授权 ID（`cg_` 前缀，来自 `verify_user_bind`），标识已授权用户
`address_id`	string	是	—	要编辑的已保存地址 ID，原样使用 `select_address` 返回的 `address_id`
`suggestion_token`	string \| null	否	`null`	地址建议 token（来自 `search_addresses`）。改位置 / 门牌时必填；仅改 `tag` 时省略
`address_detail`	string \| null	否	`null`	新门牌 / 楼层 / 房间号。传了 `suggestion_token` 时必填且不能为空白
`tag`	string \| null	否	`null`	新标签 —— `home` / `work` / `school` / 空串

字段	类型	说明
`address_id`	string	网关地址 ID（`addr_` 前缀）；更新后保持不变，可直接传给 `preview_order` 等
`display_name`	string	地址显示名（重新注册后为新选中 POI 的名称）
`address_detail`	string	门牌 / 楼层等详情
`city`	string	城市名（如「武汉」）。早期创建的地址为空串，表示未知，不代表在其他城市。
`lat`	number \| null	纬度
`lng`	number \| null	经度
`contact_name`	string \| null	收货人姓名（此工具不可改，沿用原值）
`contact_phone_masked`	string \| null	脱敏后的收货人手机号（仅展示，不回传明文）

错误码

code	说明
`CONSENT_GRANT_REQUIRED`	缺少用户授权（未传 `consent_grant_id`）
`CONSENT_GRANT_INVALID`	用户授权无效
`CONSENT_GRANT_EXPIRED`	用户授权已过期，需重新授权
`CAP_NOT_BOUND`	该 Agent 未开通外卖能力
`CONSENT_GRANT_WRONG_CAP`	授权属于其它能力 / 服务商
`PUBLIC_REFERENCE_INVALID`	`address_id` 无效、过期或不属于当前授权用户
`ADDRESS_UPDATE_REQUIRES_TOKEN`	改位置 / 门牌却未传 `suggestion_token`；仅改 `tag` 无需
`DETAIL_REQUIRED`	传了 `suggestion_token` 但 `address_detail` 为空 / 空白
`SUGGESTION_EXPIRED`	`suggestion_token` 无效或已过期，需重新调 `search_addresses`
`ADDRESS_CREATE_REJECTED`	平台拒绝按新位置重新注册该地址（业务原因）。换一条地址建议重试
`ELEME_ERROR`	上游饿了么 / 淘宝闪购返回错误（如重新注册地址失败）

完整错误码见错误处理。

调用示例

仅改标签：

{
  "name": "update_address",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "address_id": "<来自 select_address>",
    "tag": "home"
  }
}

改位置 / 门牌（需先搜地址）：

{
  "name": "update_address",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "address_id": "<来自 select_address>",
    "suggestion_token": "<来自 search_addresses 的 token>",
    "address_detail": "3 号楼 101"
  }
}

概览

接入

指南

授权

店铺

地址

下单

支付

update_address

update_address

参数

返回

错误码

调用示例

​update_address

​参数

​返回

​错误码

​调用示例

update_address

参数

返回

错误码

调用示例