Listings APIListings API
Accedi

Collega Apple Business Connect

Pubblica la sede su Apple Maps con Apple Business verificato del titolare o ListingsAPI se assente; verifica la scheda e scollega a fine rapporto.

ListingsAPI pubblica il nome, la categoria, l'indirizzo, il numero di telefono, il sito web e gli orari di una sede su Apple Maps e Siri in uno dei due modi seguenti.

Il proprietario dell'attività haCosa succede
Un account organizzazione Apple Business verificatoIl proprietario lo collega alla sede tramite un link OAuth (passaggi 1 e 2) e ListingsAPI pubblica tramite il suo account.
Nessun account organizzazione Apple Business verificatoNon è necessario alcun collegamento. ListingsAPI invia la sede tramite il proprio account Apple Business Connect e Apple verifica l'invio prima di pubblicare i dati. Vai al passaggio 3.

OAuth collega una sede alla volta, con site impostato su APPLE.

Salta i passaggi 1 e 2 se il proprietario non ha un account organizzazione Apple Business verificato.

POST /locations/oauth_connect_url restituisce un URL OAuth limitato a una sola sede. Invia site: "APPLE" con l'ID della sede e i tuoi due URL di reindirizzamento. Riferimento: Collega una sede ad Apple Business Connect.

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

La risposta è data.createConnectUrl con success, url e errors. Reindirizza il proprietario a url. Il proprietario accede al proprio account organizzazione Apple Business verificato, concede l'accesso e viene reindirizzato al tuo successUrl; se annulla o la concessione dell'accesso non riesce, viene reindirizzato a errorUrl.

Il link è monouso, quindi creane uno nuovo per ogni tentativo. Un URL di reindirizzamento relativo o non interpretabile produce una risposta success: true con url impostato su null, quindi controlla url prima di reindirizzare il proprietario. Una chiave che non è autorizzata a operare su questa sede riceve una risposta 403 con SY90003.

2. Conferma il collegamento

Dopo che il proprietario torna al tuo successUrl, elenca gli account collegati filtrando per Apple. Questa è una pagina con paginazione basata su offset: records[] più pageInfo.totalRecords, con paginazione tramite page e perPage.

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

Conserva connectedAccountId. status è CONNECTED, MATCH_IN_PROGRESS o CONNECTIVITY_ISSUE; qualsiasi valore diverso da CONNECTED significa che il proprietario deve aprire un nuovo link di collegamento prima che gli aggiornamenti possano essere inviati tramite il suo account.

3. Controlla la scheda su Apple Maps

Questo passaggio è lo stesso sia che il proprietario abbia collegato un account sia che non l'abbia fatto. GET /locations/{locationId}/listings/premium restituisce un record per ogni piattaforma di pubblicazione premium inclusa nel piano. Il record di Apple Maps ha site.url impostato su business.apple.com.

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

Il record non è SYNCED e listingUrl è null finché Apple non pubblica la scheda del luogo. Quando la sede è stata inviata tramite l'account ListingsAPI, Apple verifica l'invio prima di pubblicarla. Dopo la pubblicazione da parte di Apple, il record è SYNCED con listingUrl impostato sull'URL della scheda pubblicata su Apple Maps. Per la tabella completa degli stati, consulta Controlla lo stato delle schede e i link alle schede pubblicate.

I risultati di Siri provengono dalla scheda della sede su Apple Maps. Il loro stato viene restituito da GET /locations/{locationId}/voice-assistants con voiceIdentifier pari a SIRI.

4. Conferma le corrispondenze suggerite

Se i suggerimenti di collegamento includono record Apple, il loro accountType è APPLE e il tipo di record di corrispondenza da codificare per Conferma le corrispondenze di collegamento è AppleLocationMatchedData. Crea l'ID codificando AppleLocationMatchedData:<matchedDataDatabaseId> in base64 e invialo in matchRecordIds.

5. Scollega la sede quando un cliente interrompe il rapporto

Questo passaggio si applica solo a una sede collegata tramite OAuth. POST /locations/oauth-disconnect rimuove il collegamento tra una sede e l'account Apple Business del proprietario. Invia site: "APPLE". La sede rimane nel tuo account e i suoi collegamenti alle altre piattaforme di pubblicazione non vengono modificati. Riferimento: Scollegare una sede da Apple Business Connect.

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

La risposta è data.disconnectConnectedAccountsLocations con success e errors. Per una sede senza un collegamento Apple attivo viene restituito SY10057, mentre per una richiesta che non contiene né site né providerId viene restituito SY10056.

6. Cosa succede dopo

Non esiste un evento webhook connection.* per Apple. Se il proprietario ha effettuato il collegamento tramite OAuth, conferma il collegamento elencando gli account (passaggio 2). In entrambi i casi, verifica lo stato di pubblicazione leggendo il record di Apple Maps (passaggio 3). L'evento listing.submission segnala ogni invio a una piattaforma di pubblicazione quando raggiunge uno stato finale.

Se in seguito il collegamento riporta CONNECTIVITY_ISSUE, crea un nuovo link di collegamento (passaggio 1) e chiedi al proprietario di accedere nuovamente.

Passaggi successivi