Listings APIListings API
Se connecter

Connecter Apple Business Connect

Apple Maps : publiez via le compte Apple Business vérifié du propriétaire ou, à défaut, ListingsAPI. Vérifiez la fiche ; déconnectez au départ du client.

ListingsAPI publie le nom, la catégorie, l'adresse, le numéro de téléphone, le site Web et les horaires d'un établissement sur Apple Maps et Siri de l'une des deux manières suivantes.

Le propriétaire de l'entreprise possèdeCe qui se passe
Un compte d'organisation Apple Business vérifiéLe propriétaire le connecte à l'établissement à l'aide d'un lien OAuth (étapes 1 et 2), et ListingsAPI publie via son compte.
Aucun compte d'organisation Apple Business vérifiéAucune connexion n'est nécessaire. ListingsAPI soumet l'établissement via son propre compte Apple Business Connect, et Apple vérifie la soumission avant de publier les données. Passez à l'étape 3.

OAuth connecte un seul établissement à la fois, avec site défini sur APPLE.

Ignorez les étapes 1 et 2 si le propriétaire ne possède pas de compte d'organisation Apple Business vérifié.

POST /locations/oauth_connect_url renvoie une URL OAuth dont la portée est limitée à un seul établissement. Envoyez site: "APPLE" avec l'identifiant de l'établissement et vos deux URL de redirection. Référence : Connecter un établissement à 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 réponse est data.createConnectUrl avec success, url et errors. Redirigez le propriétaire vers url. Il se connecte à son compte d'organisation Apple Business vérifié, accorde l'accès et est redirigé vers votre successUrl ; s'il annule ou si l'autorisation échoue, il est redirigé vers errorUrl.

Le lien est à usage unique ; créez-en donc un nouveau pour chaque tentative. Une URL de redirection relative ou impossible à analyser entraîne une réponse success: true avec un url à null ; vérifiez donc url avant de rediriger le propriétaire. Une clé qui n'est pas autorisée à agir sur cet établissement reçoit une réponse 403 avec SY90003.

2. Confirmez la connexion

Une fois le propriétaire revenu sur votre successUrl, récupérez la liste des comptes connectés en la filtrant sur Apple. Il s'agit d'une page de résultats avec pagination par décalage : records[] et pageInfo.totalRecords, paginés à l'aide de page et perPage.

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

Conservez connectedAccountId. status vaut CONNECTED, MATCH_IN_PROGRESS ou CONNECTIVITY_ISSUE ; toute valeur autre que CONNECTED signifie que le propriétaire doit ouvrir un nouveau lien de connexion avant que les mises à jour puissent être effectuées via son compte.

3. Vérifiez la fiche Apple Maps

Cette étape est identique, que le propriétaire ait connecté un compte ou non. GET /locations/{locationId}/listings/premium renvoie un enregistrement par plateforme de publication premium incluse dans le forfait. Dans l'enregistrement Apple Maps, site.url est défini sur business.apple.com.

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

L'enregistrement n'est pas SYNCED et listingUrl vaut null tant qu'Apple n'a pas publié la fiche du lieu. Lorsque l'établissement a été soumis via le compte ListingsAPI, Apple vérifie la soumission avant de publier. Une fois la fiche publiée par Apple, l'enregistrement est SYNCED et listingUrl contient l'URL de la fiche Apple Maps en ligne. Pour consulter le tableau complet des statuts, voir Vérifier le statut des fiches et les liens vers les fiches en ligne.

Les résultats Siri proviennent de la fiche Apple Maps de l'établissement. Leur statut est renvoyé par GET /locations/{locationId}/voice-assistants sous SIRI voiceIdentifier.

4. Confirmez les correspondances suggérées

Si les suggestions de connexion incluent des enregistrements Apple, leur accountType vaut APPLE, et le type d'enregistrement de correspondance à encoder pour Confirmer les correspondances de connexion est AppleLocationMatchedData. Construisez l'identifiant en encodant AppleLocationMatchedData:<matchedDataDatabaseId> en base64 et envoyez-le dans matchRecordIds.

5. Déconnecter l'établissement lorsqu'un client vous quitte

Cette étape s'applique uniquement à un établissement connecté via OAuth. POST /locations/oauth-disconnect supprime la connexion entre un établissement et le compte Apple Business de son propriétaire. Envoyez site: "APPLE". L'établissement reste dans votre compte et ses connexions aux autres plateformes de publication ne sont pas affectées. Référence : Déconnecter un établissement d'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 réponse est data.disconnectConnectedAccountsLocations avec success et errors. Un établissement sans connexion Apple active renvoie SY10057, et une requête ne contenant ni site ni providerId renvoie SY10056.

6. Ce qui se passe ensuite

Il n'existe aucun événement webhook connection.* pour Apple. Si le propriétaire s'est connecté via OAuth, confirmez la connexion en répertoriant les comptes (étape 2). Dans les deux cas, vérifiez le statut de publication en consultant l'enregistrement Apple Maps (étape 3). L'événement listing.submission signale chaque soumission à une plateforme de publication lorsqu'elle atteint un état final.

Si la connexion indique ultérieurement CONNECTIVITY_ISSUE, créez un nouveau lien de connexion (étape 1) et demandez au propriétaire de se reconnecter.

Étapes suivantes