Temukan dan arsipkan lokasi yang tidak lagi Anda kelola

Cari dengan kata kunci, cocokkan kode toko dan ID secara massal, jadwalkan arsip cabang tutup di akhir siklus tagihan, dan batalkan jadwal arsip.

Tiga endpoint baca menemukan lokasi berdasarkan kunci yang berbeda: pencarian teks bebas, pencarian berdasarkan kode toko, dan pencarian berdasarkan id. Pengarsipan adalah operasi tulis terjadwal: lokasi tetap aktif hingga akhir siklus penagihan saat ini, lalu berhenti disinkronkan dan tidak lagi dikenai biaya. Hingga saat itu, Anda dapat membatalkannya.

1. Cari berdasarkan kata kunci

GET /locations/search?query= mencocokkan istilah pencarian dengan nama, alamat jalan, kota, dan id toko, lalu mengembalikan koneksi berbasis cursor: edges[].node dengan pageInfo.endCursor, yang dibagi menjadi halaman menggunakan first dan after. Hilangkan query untuk menelusuri seluruh akun secara berhalaman.

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 }    }  }}

Array edges yang kosong berarti tidak ada kecocokan, dan inilah pemeriksaan yang perlu dilakukan sebelum membuat toko saat Anda tidak yakin apakah toko tersebut sudah ada. Kedua SDK menerima fields untuk membatasi pencocokan hanya pada name atau store_id.

2. Cari berdasarkan kode toko

Jika sistem Anda menggunakan kode toko Anda sendiri sebagai kunci lokasi, temukan lokasi tersebut secara langsung dengan GET /locations-by-store-codes. Parameter storeCodes adalah array JSON yang dikodekan untuk URL. Kode yang tidak memiliki kecocokan tidak disertakan dalam hasil.

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. Ambil data lengkap untuk sekumpulan id

Jika Anda sudah memiliki id base64, baik dari penyimpanan Anda sendiri maupun dari payload webhook, GET /locations-by-ids mengembalikan rekaman lengkap untuk semuanya dalam satu panggilan. Lokasi yang diarsipkan juga ditemukan, jadi baca archived dan archivedAt untuk membedakannya. Id yang tidak dikenal diabaikan tanpa pemberitahuan; bandingkan jumlahnya.

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 }    ]  }}

Untuk mengambil sebagian data dari seluruh akun melalui pemrosesan di sisi server, GET /locations juga menerima parameter filter yang dikodekan sebagai JSON, misalnya berdasarkan status persetujuan. Lihat Daftar semua lokasi.

4. Arsipkan lokasi yang tidak lagi Anda kelola

POST /locations/archive menerima input.locationIds dan mengembalikan satu entri result per lokasi. Pengarsipan dijadwalkan, bukan dilakukan seketika: setiap lokasi masuk ke status ARCHIVE_SCHEDULED, terus disinkronkan hingga siklus penagihan saat ini berakhir, dan diarsipkan saat faktur berikutnya dibuat. Sejak saat itu, lokasi berhenti disinkronkan ke platform publikasi dan tidak lagi dikenai biaya.

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 }      ]    }  }}

Baca success pada setiap entri: satu id yang tidak valid tidak menghalangi pemrosesan id lainnya dalam kumpulan tersebut. Selama pengarsipan terjadwal, field archivalScheduledAt lokasi tersebut diisi pada hasil daftar dan pencarian. Lokasi yang telah diarsipkan tidak dapat diperbarui hingga diaktifkan kembali. Jika webhook dikonfigurasi, peristiwa profile.deleted dipicu; ini merupakan penghapusan sementara, dan tidak ada penghapusan permanen.

5. Batalkan pengarsipan terjadwal

Sebelum siklus berakhir, POST /locations/cancel_archive dengan id yang sama mengembalikan lokasi tersebut ke ACTIVE dan penagihan berlanjut. Setelah lokasi sepenuhnya diarsipkan, panggilan ini mengembalikan 404 untuk lokasi tersebut. Pembatalan tidak memicu peristiwa 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 }      ]    }  }}

Kedua SDK memerlukan dua argumen posisi tambahan, yaitu tipe pemilihan dan pengenal changedBy, yang dikirim bersama locationIds. Isi permintaan REST hanya memerlukan id.

Langkah selanjutnya

• Tambahkan lokasi: panggilan untuk membuat lokasi, dan alasan pengaturan storeId dalam panggilan tersebut memungkinkan langkah 2 dilakukan.
• Perbarui lokasi: perbaiki detail lokasi yang Anda temukan alih-alih mengarsipkannya.
• Cari lokasi, Dapatkan lokasi berdasarkan kode toko, Dapatkan lokasi berdasarkan ID, Arsipkan lokasi, dan Batalkan pengarsipan terjadwal: halaman referensi.