Eine OAuth-Verbindungs-URL für einen Standort erstellen

Parameter

Body

Name	Typ	Erforderlich	Beschreibung
input	object	erforderlich	Wrapper object. The entire request body must be nested under `input`.
input.locationId	string	erforderlich	Location the connection will be attached to. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID.
input.site	string	erforderlich	Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`.
input.successUrl	string	erforderlich	Absolute URL the publisher returns the user to after they grant access.
input.errorUrl	string	erforderlich	Absolute URL the publisher returns the user to if they cancel or the grant fails.

Beispielanfrage

Body zum direkten Einfügen. Ersetzen Sie Platzhalter-IDs und -Werte durch Ihre eigenen.

Request body

{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}

Antworten

200A single-use OAuth URL to send the user to. `errors` is `null` on success. The `url` shown is a placeholder; send the user to the `url` returned in your own response.

Response

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

401Unauthenticated, missing or invalid API key.

403The key is valid but not permitted to connect this location (`SY90003`).

Gibt eine OAuth-URL für eine Plattform zurück, die auf einen Standort beschränkt ist. Leiten Sie den Endnutzer zu url weiter; nach Abschluss leitet die Plattform ihn zu Ihrer successUrl (oder errorUrl) weiter, und die daraus hervorgehenden Zugangsdaten werden dem Standort als verbundenes Konto zugeordnet.

Dies ist das Gegenstück für einen einzelnen Standort zu den Abläufen für die Massenverbindung, Google-Konten in einem Schritt verbinden und Facebook-Konten in einem Schritt verbinden, die einen kontoweiten Link erstellen und anschließend Einträge anhand eines Abgleichs zuordnen. Verwenden Sie diese Route, wenn Sie bereits wissen, welchen Standort der Nutzer verbindet, und möchten, dass er zur Seite dieses Standorts in Ihrem eigenen Produkt zurückkehrt.

Beide Weiterleitungs-URLs sind erforderlich und müssen absolut sein; bei einem relativen oder nicht parsebaren Wert wird success: true mit null url zurückgegeben. Prüfen Sie daher url und nicht nur success. Der Link ist nur einmal verwendbar und an den von Ihnen angegebenen Standort gebunden. Erstellen Sie daher für jeden Versuch einen neuen Link, statt ihn zwischenzuspeichern.

Anwendungsfall: Eine Filiale aus Ihrer eigenen App verbinden

Wenn ein Nutzer eine Filiale aus Ihrer App verbindet, rufen Sie diese Route mit POST auf und übergeben Sie die ID des Standorts, site: "GOOGLE" sowie Weiterleitungs-URLs, die zurück in Ihre App führen. Leiten Sie den Nutzer in einem Popup oder über eine Weiterleitung der gesamten Seite zu url weiter. Rufen Sie nach seiner Rückkehr Details zum verbundenen Konto abrufen oder die Verbindungsinformationen des Standorts ab, um zu bestätigen, dass die Verbindung hergestellt wurde, und zeigen Sie dann den verbundenen Zustand in Ihrer App an. Wenn der Nutzer den Ablauf abbricht, gelangt er zu errorUrl und es wird nichts zugeordnet. Erstellen Sie daher einen neuen Link und lassen Sie ihn es erneut versuchen.

Anwendungsfall: Über das Apple Business-Konto des Inhabers veröffentlichen

Senden Sie site: "APPLE", um einen Standort mit dem verifizierten Apple Business-Organisationskonto des Inhabers zu verbinden. Der Inhaber öffnet url, meldet sich bei diesem Konto an und gewährt Zugriff. Von da an veröffentlicht ListingsAPI die Apple Maps-Daten dieses Standorts über das Konto des Inhabers.

Wenn der Inhaber kein verifiziertes Apple Business-Organisationskonto hat, überspringen Sie diesen Ablauf. ListingsAPI veröffentlicht den Standort über sein eigenes Apple Business Connect-Konto, und Apple überprüft die Einreichung vor der Veröffentlichung. Jeder Standort wird separat verbunden, sodass ein Konto Standorte beider Arten enthalten kann.

Nachdem der Inhaber zu successUrl zurückgekehrt ist, rufen Sie Verbundene Konten auflisten mit publisher=AppleAccount auf und prüfen Sie, ob status des Kontos den Wert CONNECTED hat. Den vollständigen Ablauf einschließlich der Prüfung des Apple Maps-Eintrags finden Sie unter Apple Business Connect verbinden.

Dieser Endpoint erstellt echte OAuth-Zugangsdaten. Die oben gezeigte Anfrage und Antwort sind Beispiele.

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