Listings APIListings API
Oturum aç

Konum ekleme

Yayın platformlarının ihtiyaç duyduğu alanlarla bir konum oluşturun, doğrulama hatalarını giderin ve konumun gönderim kuyruğuna alındığını doğrulayın.

İşletme kayıtları, yorumlar, gönderiler ve analizlerin tümü bir konum kimliğiyle ilişkilendirilir. POST /api/v4/locations konumu oluşturur ve planınızdaki her yayın platformu için bir işletme kaydını kuyruğa alır.

1. Gerekli alanları hazırlayın

10 alan zorunludur. Hizmet bölgesi olan bir işletme de tam adresini gönderir: hideAddress: true kullanıldığında ListingsAPI adresi saklar ancak yayın platformlarına göndermez. Yayın platformları, gönderilmeyen isteğe bağlı alanları boş gösterir; bu nedenle elinizdeki tüm bilgileri gönderin.

AlanZorunluNotlar
nameEvet2 ile 150 karakter arasında.
descriptionEvetEn az 200 karakter (SY10005).
countryIsoEvetDesteklenen bir ülkenin 2 harfli kodu (SY10036).
cityEvetÜlkenin hasCity değeri true olduğunda zorunludur (SY10126). Bu değer false olduğunda, gönderdiğiniz şehir dikkate alınmaz.
subCategoryIdEvetAlt kategoriler listesinden sayısal databaseId değeri.
streetEvet5 ile 100 karakter arasında (SY10011).
stateIsoEvetÜlkenin stateRequired değeri true olduğunda zorunludur ve o ülkenin states değerlerinden biri olmalıdır (SY10010). stateRequired değeri false olduğunda bu alanı göndermeyin.
postalCodeHayırİsteğe bağlıdır, ancak ülkenin hasPostalCode değeri true olduğunda gönderin. Gönderdiğiniz değer ülkenin biçimine uymalıdır (SY10014).
phoneEvetÜlkeye göre doğrulanır (SY10015).
bizUrlEvetWeb sitesi olarak yayımlanır. Bazı yayın platformları, web sitesi olmayan işletme kayıtlarını reddeder.
storeIdHayırHesap genelinde benzersiz olan kendi mağaza kodunuz. Bizim kimlik değerlerimizi saklamadan konumu yeniden bulmak için bu kodu kullanın.
businessHoursHayırHafta içindeki her gün için bir girdi. Biçim için Konum güncelleme bölümüne bakın.

2. Konumu oluşturun

POST /api/v4/locations, alanları JSON istek gövdesindeki bir input nesnesi içinde alır. Python SDK yöntemi locations.add(), aynı alanları anahtar sözcüklü argümanlar olarak alır ve isteği göndermeden önce zorunlu olanları doğrular. Node SDK yöntemi createLocation(), camelCase nesnesini doğrudan alır.

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. Yanıtı okuyun

Başarılı bir oluşturma işlemi, success: true ve data.createLocation.location içinde yeni konumu döndürür. Her iki kimlik değerini de saklayın: id, sonraki her yazma işleminin aldığı base64 değeridir; databaseId ise kontrol panellerinde ve webhook yüklerinde gösterilen sayısal değerdir.

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

Konum doğrulanıp kuyruğa alınırken status değeri PENDING olur. Ek bir API çağrısı olmadan sonraki duruma geçer.

4. Doğrulama hatalarını giderin

Bir oluşturma işlemi 2 noktada başarısız olabilir. Hatalı biçimlendirilmiş bir istek veya geçersiz bir anahtar, en üst düzeyde bir errors dizisi içeren 4xx döndürür. Doğru biçimlendirilmiş ancak API'nin reddettiği bir alan içeren bir istek, success: false ile birlikte 200 döndürür ve sorun data.createLocation.errors içinde yer alır; bu nedenle her yazma işleminde yalnızca durum kodunu değil, yanıt gövdesini de kontrol edin.

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

Her iki SDK da başarısızlık durumunda istisna fırlatır. Python'daki locations.add(), zorunlu alanları yerel olarak kontrol eder ve isteği göndermeden önce ValidationError istisnasını fırlatır. Node'daki createLocation(), API girdiyi reddettiğinde ValidationError istisnasını fırlatır; bu nedenle yukarıdaki örnek herhangi bir başarı bayrağını kontrol etmez.

En sık karşılaşacağınız kodlar:

KodNedenÇözüm
SY10005Açıklama eksik veya 200 karakterden kısa.Daha kapsamlı bir açıklama yazın.
SY10011street eksik veya 5 karakterden kısa.street gönderin.
SY10010stateIso eksik veya ülke için geçerli değil.Ülkeler uç noktasından bir eyalet kodu gönderin.
SY10036countryIso desteklenen bir ülke değil.Ülkeler uç noktasından bir kod kullanın.
SY10126city, bu alanı zorunlu tutan bir ülke için eksik.city gönderin.
SY90016Anahtar yalnızca Read yetkisine sahip.Write yetkisine sahip bir anahtar kullanın.

5. Gönderimin başladığını doğrulayın

Konum oluşturulduğunda planınızdaki her yayın platformu için bir işletme kaydı kuyruğa alınır. Her işletme kaydı AVAILABLE veya IN_PROGRESS durumunda başlar ve yayın platformu kaydı kabul ettiğinde bir listingUrl ile SYNCED durumuna geçer.

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

Webhook'lar yapılandırıldığında düzenli aralıklarla sorgulama yapmanız gerekmez. Kayıt mevcut olduğunda bir profile.created olayı tetiklenir ve her yayın platformunun durumu değiştikçe o yayın platformu için bir listing.submission olayı tetiklenir.

Sonraki adımlar