拠点を検索し、管理対象でなくなった拠点をアーカイブする

キーワードで検索し、店舗コードと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は1回の呼び出しで、それらすべての完全なレコードを返します。アーカイブ済みの拠点も取得されるため、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を受け取り、拠点ごとに1つの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を確認してください。1つの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も、選択タイプとchangedBy識別子という2つの追加の位置引数を必要とし、これらをlocationIdsとともに送信します。RESTのリクエストボディに必要なのはidのみです。

次の手順

• 拠点を追加する: 作成呼び出しと、その呼び出しで storeId を設定すると手順2を使える理由を説明します。
• 拠点を更新する: 見つかった拠点をアーカイブする代わりに、その詳細情報を修正します。
• 拠点を検索する、店舗コードで拠点を取得する、ID で拠点を取得する、拠点をアーカイブする、予定されているアーカイブをキャンセルする: それぞれのリファレンスページです。