Google Business Profile'ı bağlayıp konumlarınızı içe aktarın

Google'ı bağlamak için bağlantı oluşturun, sahibin Google işletme kayıtlarını konumlarınızla eşleştirip onaylayın ve konumu olmayan kayıtları içe aktarın.

Bağlı bir Google hesabı, bir konum için Google'da yayın yapmayı ve raporlamayı etkinleştirir. Bir hesap bağlanana kadar konumun premium işletme kayıtlarındaki Google Maps satırı REQUIRING_ACTION olarak kalır, Google yorumları alınmaz, gönderiler GOOGLE üzerinde yayınlanamaz ve Google analizleri null döndürür. Hesabın bağlanması bu dört sorunu da çözer.

Toplu işlem akışı (1-6. adımlar), Google hesabının tamamını tek seferde bağlar ve hesabın sahip olduğu her işletme kaydını konumlarınızla eşleştirir. Tek konum akışı (7. adım), her seferinde bir konumu bağlar: bağlantı o konuma özeldir, bu nedenle ardından bir eşleştirme adımı gelmez.

1. Hesap bağlama bağlantısını oluşturun ve hesap sahibini yönlendirin

Bağlantının kapsamı, API anahtarının sahibi olan hesapla sınırlıdır; bu nedenle istek gövdesi yalnızca iki yönlendirme URL'nizi içerir. Hesap sahibini döndürülen url adresine yönlendirin; işlemi tamamladığında Google onu successUrl veya errorUrl adresine geri yönlendirir.

Connect link

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/google/success",    "errorUrl": "https://app.example.com/connect/google/error"  }}'

JSON

{  "data": {    "bulkConnectLinkForGoogle": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

Yukarıdaki url bir yer tutucudur. Hesap sahibini kendi yanıtınızda döndürülen url adresine yönlendirin.

Bağlantı 24 saat geçerlidir. Yalnızca success değerine güvenmek yerine url değerinin null olmadığını kontrol edin. Hesap sahibinin kimlik bilgilerinin süresi daha sonra dolarsa aynı şekilde yeni bir bağlantı oluşturun: mevcut bağlantı yenilenir, ikinci bir bağlantı oluşturulmaz.

2. OAuth dönüşünden sonra bağlı hesapları listeleyin

Hesap sahibi successUrl adresinize ulaştığında Google hesaplarını listeleyin. Bu, offset tabanlı bir sayfadır: records[] ve pageInfo.totalRecords içerir, page ve perPage ile sayfalanır.

List accounts

curl "https://listingsapi.com/api/v4/connected-accounts?publisher=GoogleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "email": "owner@brightsmile-dental.com",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

email değeri az önce izin veren hesap sahibine karşılık gelen kaydı seçin ve bu kaydın connectedAccountId değerini saklayın. Sonraki tüm çağrılar bu UUID'yi alır.

`status`	Anlamı
`CONNECTED`	Kimlik bilgileri geçerlidir. Eşleştirmeyi güvenle başlatabilirsiniz.
`MATCH_IN_PROGRESS`	Bir eşleştirme işlemi kuyruğa alınmıştır veya çalışmaktadır.
`CONNECTIVITY_ISSUE`	Verilen iznin süresi dolmuştur. `connectivityIssue` nedenini belirtir; hesap bağlama bağlantısını yeniden oluşturun.

İsteğe bağlı status sorgu filtresi farklı sözcükler (Connected, NotConnected, ConnectionIssue) kullanır; bir kaydın kendi status değerini bu filtreye verirseniz 400 döndürülür.

3. Eşleştirmeyi başlatın

Eşleştirme, hesabın erişebildiği tüm profilleri alır ve her birini konumlarınızdan biriyle eşleştirir. Yalnızca öneriler üretir; henüz hiçbir şey bağlanmaz.

Trigger matches

curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["4f712c17-4f95-42dd-90f4-97171a2e67b5"] } }'

Yanıt, success ve failedIds içeren data.connectedAccountsTriggerMatches şeklindedir. success: true, işin kuyruğa alındığı anlamına gelir; kuyruğa alınamayan tüm hesaplar failedIds içinde listelenir.

4. MATCH_COMPLETED olana kadar düzenli aralıklarla sorgulayın

Sınırlı bir döngü kullanarak hesabın ayrıntılarını 15 saniyede bir sorgulayın. Bu aralık, Launch planının dakikada 10 istek sınırının aşılmasını da önler.

Poll details

curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/details \-H "Authorization: API $LISTINGSAPI_KEY"

Kayıt, data.connectedAccountDetails.details içinde döndürülür ve liste kaydıyla aynı alanlara sahiptir. requestMatchesStatus, iş çalışırken MATCH_IN_PROGRESS, öneriler hazır olduğunda ise MATCH_COMPLETED değerindedir. Completed, eşleştiricinin işlemi bitirdiği anlamına gelir, herhangi bir şeyin bağlandığı anlamına gelmez: siz onaylayana kadar connectedLocationsCount, 0 olarak kalır.

5. Önerileri inceleyin ve onaylayın

Her öneri, konumlarınızdan birini (locationInfo; databaseId değeri locationId olan konum) bir Google işletme kaydıyla (suggestedLocationInfo) eşleştirir. Her iki tarafı bir operatöre gösterin veya ad ve şehir uyuştuğunda otomatik olarak kabul edin.

Suggestions

curl "https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "connectionSuggestionsForAccount": {      "pageInfo": { "hasNextPage": false, "totalRecords": 2 },      "records": [        {          "accountType": "GMB",          "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc",          "locationId": "73415",          "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" },          "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } }        }      ]    }  }}

Bir önerinin id değeri yoktur. Onaylamak için bir eşleştirme kaydı id'si oluşturmanız gerekir: türü accountType içinden seçerek <MatchRecordType>:<matchedDataDatabaseId> değerini base64 ile kodlayın. Google (GMB) için tür GmbLocationMatchedData olduğundan, yukarıdaki kayıt R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M= olarak kodlanır. Facebook (FB) için FbLocationMatchedData, Apple (APPLE) için ise AppleLocationMatchedData kullanılır.

Confirm matches

# base64 of GmbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M="] } }'

Yanıt, success ve failedIds içeren data.confirmConnectMatches şeklindedir. failedIds, daha önce kullanılmış bir kayıt veya eşleştirmeden sonra arşivlenmiş bir konum gibi onaylanamayan kayıtların kodu çözülmüş matchedDataDatabaseId değerlerini içerir. Yanlış türle oluşturulmuş bir id, 400 döndürmez: çağrı, success: false içeren ve failedIds içermeyen bir 200 yanıtı döndürür; bu nedenle her seferinde success değerini kontrol edin. Gönderilmeyen öneriler değişmeden kalır.

6. Henüz konumu olmayan işletme kayıtlarını içe aktarın

Eşleştirme, işletme kayıtlarını yalnızca mevcut konumlarınızla eşleştirir. Geri kalanları içe aktarmak için hesabın görebildiği tüm işletme kayıtlarını listeleyin, ardından istediğiniz her işletme kaydından bir konum oluşturun.

Account listings

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50 }'

JSON

{  "data": {    "connectedAccountListings": {      "pageInfo": { "hasNextPage": false, "totalRecords": 60 },      "records": [        {          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "locationName": "Trial",          "address": "123 William St, NY 10038, Manhattan, US",          "liveLink": null        }      ]    }  }}

Çok sayıda işletme kaydı olan bir hesaptaki sonuçları ad, adres, telefon, posta kodu veya mağaza koduna göre daraltmak için locationInfo parametresini bir arama terimiyle gönderin. Her kayıttaki id, sonraki iki çağrının aldığı connectedAccountListingId değeridir. Her iki SDK da henüz create-location-from-listing için bir sarmalayıcı sunmadığından, Python ve Node örnekleri aynı üst bilgiyi kullanarak doğrudan REST çağrısı yapar.

Create from listing

curl -X POST https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'

JSON

{  "data": {    "createLocationFromConnectedAccountListing": { "success": true, "locationId": 88277, "errors": null }  }}

Konum, Google verilerinden (ad, adres, çalışma saatleri, kategoriler, telefon, özellikler) oluşturulur ve aynı anda işletme kaydına bağlanır. Google işletme kaydı, ilk konum güncellemeniz bu kayıtta yayımlanana kadar IN_PROGRESS durumunda kalır. locationId, yalın databaseId değeridir. İşlem başarısız olduğunda success değeri false olur ve errors, SY81067 gibi bir kod içerir (işletme kaydının kimliği çözümlenememiştir). Alanın adı connectedAccountListingId şeklindedir; listingId şema tarafından reddedilir.

İşletme kaydı mevcut konumlarınızdan birine aitse yinelenen bir konum oluşturmak yerine kaydı bu konuma bağlayın.

Link a listing

curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'

Başarısız bir bağlama işlemi, message ile birlikte success: false döndürür; örneğin Listing record not found veya işletme kaydının zaten başka bir konuma bağlı olduğunu belirten bir not döndürülebilir.

7. Bunun yerine tek bir konum bağlayın

Sahibin hangi konumu bağlayacağını zaten biliyorsanız eşleştirmeyi atlayın ve o konuma özel bir bağlantı oluşturun. İşlem başarılı olduğunda sahip, belirttiğiniz successUrl adresine döner ve kimlik bilgileri yalnızca o konuma bağlanır.

Single-location link

curl -X POST https://listingsapi.com/api/v4/locations/oauth_connect_url \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}'

Yanıt, success, url ve errors içeren data.createConnectUrl biçimindedir. Bağlantı tek kullanımlıktır, bu nedenle her deneme için yeni bir bağlantı oluşturun. Göreli veya ayrıştırılamayan bir yönlendirme URL'si, null url içeren success: true yanıtıyla sonuçlanır; bu nedenle url değerini kontrol edin. Bu konuma erişim izni olmayan bir anahtar için SY90003 içeren 403 yanıtı döndürülür.

8. Sonrasında ne olur

Bir işletme kaydı bağlandığında, konumun premium işletme kayıtlarındaki Google Maps satırı REQUIRING_ACTION durumundan çıkar, IN_PROGRESS durumundan geçer ve listingUrl ile birlikte SYNCED durumuna ulaşır. Google otomatik olarak yorum kaynağı olarak eklenir; böylece yorumlar etkileşim listesine gelmeye başlar ve konumda yaptığınız güncellemeler profile aktarılır.

Kontrol panelinde bir webhook URL'si ayarlandığında düzenli sorgulama yapmanız gerekmez. Her veri yükü location_id ve data.connected_account_id içerir.

Olay	Tetiklenme koşulu	Yapılması gereken
`connection.location_connected`	Bir işletme kaydı bir konuma bağlanır; `data.platform` değeri `google` olur.	Kullanıcı arayüzünüzde konumu bağlı olarak işaretleyin.
`connection.reauth_required`	Hesabın kimlik bilgileri geçersiz kılınmıştır. Yeniden yetkilendirme yapılana kadar hiçbir şey senkronize edilmez.	Yeni bir bağlantı oluşturun (1. adım) ve sahibinden yeniden oturum açmasını isteyin.
`connection.listing_inaccessible`	Kimlik bilgileri geçerlidir ancak yalnızca o işletme kaydına erişim kaldırılmıştır.	Sahibinden Google'da erişimi yeniden sağlamasını isteyin veya farklı bir işletme kaydı bağlayın.

Sonraki adımlar

Google Business Profile oluşturun: eşleştirilecek bir Google işletme kaydı olmayan konumlar için.
Facebook Sayfalarını bağlayın: diğer OAuth yayın platformu için aynı işlem akışı.
İşletme kaydının durumunu ve yayındaki bağlantıları kontrol edin ve Yorumları alın: sonuçları geldikçe izleyin.
SDK başvuru belgeleri: Python bağlı hesaplar ve Node bağlı hesaplar.
Başvuru belgeleri: Google hesabı bağlayın, Konum eşleştirmelerini tetikleyin, Bağlantı eşleştirmelerini onaylayın, Bağlı bir hesabın işletme kayıtlarını alın, İşletme kaydından konum oluşturun ve Bağlı hesaplar dizini.