Listings APIListings API
Anmelden

Apple Business Connect verbinden

Apple Maps: Standort über verifiziertes Apple Business-Inhaberkonto, sonst ListingsAPI veröffentlichen. Prüfen Sie den Eintrag; bei Kundenabgang trennen.

ListingsAPI veröffentlicht den Namen, die Kategorie, die Adresse, die Telefonnummer, die Website und die Öffnungszeiten eines Standorts auf Apple Maps und Siri auf eine von zwei Arten.

Der Unternehmensinhaber hatWas geschieht
Ein verifiziertes Apple Business-OrganisationskontoDer Inhaber verbindet es über einen OAuth-Link mit dem Standort (Schritte 1 und 2), und ListingsAPI veröffentlicht die Daten über sein Konto.
Kein verifiziertes Apple Business-OrganisationskontoEs ist keine Verbindung erforderlich. ListingsAPI reicht den Standort über sein eigenes Apple Business Connect-Konto ein, und Apple überprüft die Einreichung, bevor es die Daten veröffentlicht. Fahren Sie mit Schritt 3 fort.

OAuth verbindet jeweils einen Standort, wobei site auf APPLE gesetzt ist.

Überspringen Sie die Schritte 1 und 2, wenn der Inhaber kein verifiziertes Apple Business-Organisationskonto hat.

POST /locations/oauth_connect_url gibt eine OAuth-URL zurück, deren Geltungsbereich auf einen Standort beschränkt ist. Senden Sie site: "APPLE" mit der Standort-ID und Ihren beiden Weiterleitungs-URLs. Referenz: Einen Standort mit Apple Business Connect verbinden.

Connect 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": "APPLE",    "successUrl": "https://app.example.com/locations/1800289/apple/connected",    "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed"  }}'

Die Antwort ist data.createConnectUrl mit success, url und errors. Leiten Sie den Inhaber zu url weiter. Er meldet sich bei seinem verifizierten Apple Business-Organisationskonto an, gewährt Zugriff und wird zu Ihrem successUrl weitergeleitet; wenn er abbricht oder die Zugriffsgewährung fehlschlägt, wird er zu errorUrl weitergeleitet.

Der Link kann nur einmal verwendet werden; erstellen Sie daher für jeden Versuch einen neuen. Bei einer relativen oder nicht parsebaren Weiterleitungs-URL wird success: true mit einem url mit dem Wert null zurückgegeben. Prüfen Sie daher url vor der Weiterleitung. Ein Schlüssel, der nicht auf diesen Standort zugreifen darf, erhält 403 mit SY90003.

2. Verbindung bestätigen

Nachdem der Inhaber zu Ihrem successUrl zurückgekehrt ist, listen Sie die verbundenen Konten auf und filtern Sie dabei nach Apple. Dies ist eine Ergebnisseite mit Offset-Paginierung: records[] plus pageInfo.totalRecords, mit page und perPage zum Blättern.

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

Bewahren Sie connectedAccountId auf. status ist CONNECTED, MATCH_IN_PROGRESS oder CONNECTIVITY_ISSUE; jeder andere Wert als CONNECTED bedeutet, dass der Inhaber einen neuen Verbindungslink öffnen muss, bevor Aktualisierungen über sein Konto erfolgen können.

3. Apple Maps-Eintrag prüfen

Dieser Schritt ist unabhängig davon gleich, ob der Inhaber ein Konto verbunden hat. GET /locations/{locationId}/listings/premium gibt einen Datensatz pro Premium-Plattform im Tarif zurück. Im Apple Maps-Datensatz ist site.url auf business.apple.com gesetzt.

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

Der Datensatz ist nicht SYNCED und listingUrl ist null, bis Apple die Ortskarte veröffentlicht. Wenn der Standort über das ListingsAPI-Konto eingereicht wurde, überprüft Apple die Einreichung vor der Veröffentlichung. Sobald Apple die Ortskarte veröffentlicht, ist der Datensatz SYNCED und listingUrl ist auf die URL des veröffentlichten Apple Maps-Eintrags gesetzt. Die vollständige Statustabelle finden Sie unter Eintragsstatus und Links zu veröffentlichten Einträgen prüfen.

Die Siri-Ergebnisse stammen aus dem Apple Maps-Eintrag des Standorts. Ihr Status wird von GET /locations/{locationId}/voice-assistants unter dem voiceIdentifier SIRI zurückgegeben.

4. Vorgeschlagene Übereinstimmungen bestätigen

Wenn die Verbindungsvorschläge Apple-Datensätze enthalten, ist deren accountType gleich APPLE, und der Typ des Übereinstimmungsdatensatzes, den Sie für Verbindungsübereinstimmungen bestätigen kodieren, ist AppleLocationMatchedData. Erstellen Sie die ID als base64-Kodierung von AppleLocationMatchedData:<matchedDataDatabaseId> und senden Sie sie in matchRecordIds.

5. Trennen Sie die Verbindung des Standorts, wenn ein Kunde geht

Dieser Schritt gilt nur für einen Standort, der über OAuth verbunden ist. POST /locations/oauth-disconnect entfernt die Verbindung zwischen einem Standort und dem Apple Business-Konto des Inhabers. Senden Sie site: "APPLE". Der Standort bleibt in Ihrem Konto, und seine Verbindungen zu anderen Plattformen sind nicht betroffen. Referenz: Verbindung eines Standorts mit Apple Business Connect trennen.

Disconnect
curl -X POST https://listingsapi.com/api/v4/locations/oauth-disconnect \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "APPLE" } }'

Die Antwort ist data.disconnectConnectedAccountsLocations mit success und errors. Bei einem Standort ohne aktive Apple-Verbindung wird SY10057 zurückgegeben, und bei einer Anfrage, die weder site noch providerId enthält, wird SY10056 zurückgegeben.

6. Was als Nächstes passiert

Für Apple gibt es kein Webhook-Ereignis connection.*. Wenn der Inhaber die Verbindung über OAuth hergestellt hat, bestätigen Sie die Verbindung, indem Sie die Konten auflisten (Schritt 2). Prüfen Sie in beiden Fällen den Veröffentlichungsstatus, indem Sie den Apple Maps-Datensatz abrufen (Schritt 3). Das Ereignis listing.submission meldet jede Einreichung bei einer Plattform, sobald sie einen abschließenden Zustand erreicht.

Wenn die Verbindung später CONNECTIVITY_ISSUE meldet, erstellen Sie einen neuen Verbindungslink (Schritt 1) und bitten Sie den Inhaber, sich erneut anzumelden.

Nächste Schritte