Konumları bulun ve artık yönetmediklerinizi arşivleyin

Anahtar kelimeyle arayın, mağaza kodu ve ID ile toplu konum bulun, kapalı şubeleri fatura dönemi sonunda arşivlemeyi planlayın ve planı iptal edin.

Üç okuma uç noktası, konumları farklı anahtarlara göre bulur: serbest metin araması, mağaza koduyla sorgulama ve id ile sorgulama. Arşivleme, planlanmış bir yazma işlemidir: konum, geçerli faturalandırma döneminin sonuna kadar etkin kalır; ardından senkronizasyonu ve ücretlendirilmesi durur. O ana kadar arşivlemeyi iptal edebilirsiniz.

1. Anahtar kelimeyle arayın

GET /locations/search?query=, arama terimini ad, sokak adresi, şehir ve mağaza id değeriyle eşleştirir ve bir cursor bağlantısı döndürür: pageInfo.endCursor içeren edges[].node, first ve after ile sayfalanır. Hesabın tamamını sayfalamak için query parametresini belirtmeyin.

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

Boş bir edges dizisi, hiçbir eşleşme bulunmadığı anlamına gelir; bir mağazanın zaten mevcut olup olmadığından emin değilseniz oluşturma işleminden önce bu kontrolü yapın. Her iki SDK da eşleşmeyi yalnızca name veya store_id ile sınırlandırmak için fields parametresini kabul eder.

2. Mağaza koduyla sorgulayın

Sistemleriniz konumları kendi mağaza kodunuzla tanımlıyorsa bunları doğrudan GET /locations-by-store-codes ile bulun. storeCodes parametresi, URL kodlaması uygulanmış bir JSON dizisidir. Eşleşmeyen kodlar sonuçta yer almaz.

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. Bir grup id için tam kayıtları alın

Kendi veri deponuzdan veya bir webhook yükünden aldığınız base64 id değerleri elinizde zaten varsa GET /locations-by-ids, bunların tümünün tam kayıtlarını tek bir çağrıda döndürür. Arşivlenmiş konumlar da döndürülür; bu nedenle bunları ayırt etmek için archived ve archivedAt değerlerini okuyun. Bilinmeyen id değerleri herhangi bir bildirim olmadan atlanır; sayıları karşılaştırın.

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

Hesabın tamamından sunucu tarafında bir alt küme seçmek için GET /locations, örneğin onay durumuna göre filtreleme yapmaya yarayan JSON kodlamalı bir filter parametresini de kabul eder. Bkz. Tüm konumları listeleme.

4. Artık yönetmediğiniz konumları arşivleyin

POST /locations/archive, input.locationIds alır ve her konum için bir result girdisi döndürür. Arşivleme hemen gerçekleşmez, planlanır: her konum ARCHIVE_SCHEDULED durumuna geçer, geçerli faturalandırma dönemi sona erene kadar senkronize edilmeye devam eder ve bir sonraki fatura oluşturulduğunda arşivlenir. O andan itibaren yayın platformlarıyla senkronizasyonu ve ücretlendirilmesi durur.

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

Her girdinin success değerini okuyun: tek bir hatalı id, grubun geri kalanını engellemez. Arşivleme planlanmış durumdayken listeleme ve arama sonuçlarında konumun archivalScheduledAt alanı ayarlanır. Arşivlenmiş bir konum, yeniden etkinleştirilene kadar güncellenemez. Webhook'lar yapılandırılmışsa bir profile.deleted olayı tetiklenir; bu bir mantıksal silme işlemidir ve kalıcı silme yoktur.

5. Planlanmış bir arşivlemeyi iptal edin

Dönem kapanmadan önce aynı id değerleriyle çağrılan POST /locations/cancel_archive, konumları ACTIVE durumuna döndürür ve ücretlendirme devam eder. Konum tamamen arşivlendikten sonra bu çağrı, o konum için 404 döndürür. İptal işlemi herhangi bir webhook olayı üretmez.

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

Her iki SDK da iki ek konumsal argüman gerektirir: bir seçim türü ve bir changedBy tanımlayıcısı; bunları locationIds ile birlikte gönderirler. REST gövdesinde yalnızca id değerleri gerekir.

Sonraki adımlar

• Konum ekleyin: oluşturma çağrısı ve bu çağrıda storeId ayarının yapılmasının 2. adımı neden mümkün kıldığı.
• Konumu güncelleyin: bulduğunuz konumları arşivlemek yerine ayrıntılarını düzeltin.
• Konumları arayın, Mağaza kodlarına göre konumları alın, Kimliklerine göre konumları alın, Konumları arşivleyin ve Planlanmış arşivlemeyi iptal edin: başvuru sayfaları.