查找地点并归档您不再管理的地点
按关键词搜索、批量解析门店代码和 id、安排在计费周期结束时归档已关闭的分店，以及取消已安排的归档。
3 个读取端点通过不同的键查找地点：自由文本搜索、门店代码查询和 id 查询。归档是一项定时执行的写入操作：地点在当前计费周期结束前保持有效，之后停止同步和计费。在此之前，您可以取消归档。
1. 按关键词搜索
GET /locations/search?query= 将搜索词与名称、街道地址、城市和门店 id 进行匹配，并返回游标连接：包含 pageInfo.endCursor 的 edges[].node，使用 first 和 after 分页。省略 query 则分页列出整个账户的地点。
curl "https://listingsapi.com/api/v4/locations/search?query=Acme&first=10" \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "searchLocations": { "edges": [ { "cursor": "TG9jYXRpb246MTgwMDI4OQ==", "node": { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "name": "Acme Kitchen", "storeId": "ACME-NYC-001", "approved": "APPROVED", "archived": false, "archivalScheduledAt": null } } ], "pageInfo": { "endCursor": "TG9jYXRpb246MTgwMDI4OQ==", "hasNextPage": false, "total": 1 } } }}edges 数组为空表示没有匹配项，当您不确定门店是否已存在时，应在创建前执行此检查。两个 SDK 都可以用 fields 把匹配范围限制为只匹配 name 或 store_id。
2. 按门店代码查询
如果您的系统使用自定义门店代码作为地点的键，请使用 GET /locations-by-store-codes 直接解析这些代码。storeCodes 参数是经过 URL 编码的 JSON 数组。没有匹配项的代码不会出现在结果中。
curl -G https://listingsapi.com/api/v4/locations-by-store-codes \--data-urlencode 'storeCodes=["ACME-NYC-001","ACME-NYC-002"]' \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "getLocationsByStoreCodes": [ { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "storeId": "ACME-NYC-001", "name": "Acme Kitchen", "archived": false } ] }}3. 批量获取 id 对应的完整记录
如果您已从自己的存储或 webhook 载荷中获得 base64 id，GET /locations-by-ids 可在一次调用中返回所有这些 id 对应的完整记录。已归档的地点也能解析，因此请读取 archived 和 archivedAt 以区分它们。未知 id 会被静默忽略；请比较数量。
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ==","TG9jYXRpb246MTgwMDI5MA=="]' \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "getLocationsByIds": [ { "id": "TG9jYXRpb246MTgwMDI4OQ==", "databaseId": 1800289, "name": "Acme Kitchen", "archived": false, "archivedAt": null }, { "id": "TG9jYXRpb246MTgwMDI5MA==", "databaseId": 1800290, "name": "Acme Kitchen Brooklyn", "archived": false, "archivedAt": null } ] }}如需在服务端筛选整个账户的数据子集，例如按审批状态筛选，GET /locations 还接受 JSON 编码的 filter 参数。请参阅列出所有地点。
4. 归档您不再管理的地点
POST /locations/archive 接受 input.locationIds，并为每个地点返回一个 result 条目。归档会按计划执行，而非立即生效：每个地点进入 ARCHIVE_SCHEDULED 状态，继续同步直至当前计费周期结束，并在生成下一张账单时归档。此后，该地点停止向发布平台同步，并停止计费。
curl -X POST https://listingsapi.com/api/v4/locations/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ==", "TG9jYXRpb246MTgwMDI5MA=="] }}'{ "data": { "archiveLocations": { "errors": null, "result": [ { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null }, { "locationId": "TG9jYXRpb246MTgwMDI5MA==", "status": "ARCHIVE_SCHEDULED", "success": true, "errors": null } ] } }}请读取每个条目的 success：单个无效 id 不会阻止批次中其余地点的处理。在等待归档期间，列表和搜索结果中会设置该地点的 archivalScheduledAt 字段。已归档的地点必须重新激活后才能更新。如果配置了 webhook，则会触发 profile.deleted 事件；这是软删除，不存在硬删除。
5. 取消已安排的归档
在计费周期结束前，使用相同的 id 调用 POST /locations/cancel_archive 会使这些地点恢复为 ACTIVE，并继续计费。地点完全归档后，此调用会为该地点返回 404。取消归档不会触发 webhook 事件。
curl -X POST https://listingsapi.com/api/v4/locations/cancel_archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationIds": ["TG9jYXRpb246MTgwMDI4OQ=="] } }'{ "data": { "cancelLocationsArchive": { "errors": null, "result": [ { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "status": "ACTIVE", "success": true, "errors": null } ] } }}两个 SDK 都需要额外提供 2 个位置参数，即选择类型和 changedBy 标识符，它们会将这两个参数与 locationIds 一同发送。REST 请求体只需要 id。