Conecta Apple Business Connect

Publica en Apple Maps con la cuenta verificada de Apple Business del dueño o con ListingsAPI si no tiene; revisa la ficha y desconecta al irse el cliente.

ListingsAPI publica el nombre, la categoría, la dirección, el teléfono, el sitio web y el horario de una ubicación en Apple Maps y Siri de una de estas dos formas.

OAuth conecta una ubicación a la vez, con site establecido en APPLE.

1. Crea el enlace de conexión y redirige al propietario

Omite los pasos 1 y 2 si el propietario no tiene una cuenta de organización verificada de Apple Business.

POST /locations/oauth_connect_url devuelve una URL OAuth cuyo alcance se limita a una ubicación. Envía site: "APPLE" con el ID de la ubicación y tus dos URL de redirección. Referencia: Conectar una ubicación a Apple Business Connect.

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 respuesta es data.createConnectUrl con success, url y errors. Redirige al propietario a url. El propietario inicia sesión en su cuenta de organización verificada de Apple Business, concede acceso y se le redirige a tu successUrl; si cancela o falla la concesión de acceso, se le redirige a errorUrl.

El enlace es de un solo uso, así que crea uno nuevo para cada intento. Una URL de redirección relativa o que no se pueda analizar devuelve success: true con un url con valor null, así que comprueba url antes de redirigir. Una clave sin permiso para operar sobre esta ubicación recibe un 403 con SY90003.

2. Confirma la conexión

Después de que el propietario vuelva a tu successUrl, enumera las cuentas conectadas filtradas por Apple. Esta es una página con paginación por desplazamiento: records[] más pageInfo.totalRecords, paginada mediante page y perPage.

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

Conserva el connectedAccountId. status es CONNECTED, MATCH_IN_PROGRESS o CONNECTIVITY_ISSUE; cualquier valor distinto de CONNECTED significa que el propietario debe abrir un nuevo enlace de conexión antes de que las actualizaciones puedan realizarse a través de su cuenta.

3. Comprueba la ficha de Apple Maps

Este paso es el mismo tanto si el propietario ha conectado una cuenta como si no. GET /locations/{locationId}/listings/premium devuelve un registro por cada plataforma de publicación prémium incluida en el plan. El registro de Apple Maps tiene site.url establecido en business.apple.com.

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

El registro no es SYNCED y listingUrl es null hasta que Apple publica la ficha del lugar. Cuando la ubicación se ha enviado a través de la cuenta de ListingsAPI, Apple verifica el envío antes de publicarla. Una vez que Apple la publica, el registro es SYNCED con listingUrl establecido en la URL de la ficha publicada en Apple Maps. Para consultar la tabla completa de estados, ve a Comprobar el estado de las fichas y los enlaces publicados.

Los resultados de Siri proceden de la ficha de Apple Maps de la ubicación. GET /locations/{locationId}/voice-assistants devuelve su estado bajo el SIRI voiceIdentifier.

4. Confirma las coincidencias sugeridas

Si las sugerencias de conexión incluyen registros de Apple, su accountType es APPLE, y el tipo de registro de coincidencia que codificas para Confirmar coincidencias de conexión es AppleLocationMatchedData. Construye el ID como la codificación en base64 de AppleLocationMatchedData:<matchedDataDatabaseId> y envíalo en matchRecordIds.

5. Desconecta la ubicación cuando un cliente se vaya

Este paso se aplica solo a una ubicación conectada mediante OAuth. POST /locations/oauth-disconnect elimina la conexión entre una ubicación y la cuenta de Apple Business del propietario. Envía site: "APPLE". La ubicación permanece en tu cuenta y sus conexiones con otras plataformas de publicación no se ven afectadas. Referencia: Desconectar una ubicación de Apple Business Connect.

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 respuesta es data.disconnectConnectedAccountsLocations con success y errors. Para una ubicación sin una conexión activa con Apple, se devuelve SY10057, y para una solicitud que no incluya ni site ni providerId, se devuelve SY10056.

6. Qué ocurre después

No hay ningún evento de webhook connection.* para Apple. Si el propietario se conectó mediante OAuth, confirma la conexión enumerando las cuentas (paso 2). En ambos casos, comprueba el estado de publicación consultando el registro de Apple Maps (paso 3). El evento listing.submission informa de cada envío a una plataforma de publicación cuando alcanza un estado terminal.

Si la conexión indica CONNECTIVITY_ISSUE más adelante, crea un nuevo enlace de conexión (paso 1) y pide al propietario que vuelva a iniciar sesión.

Próximos pasos

• Comprobar el estado de las fichas y los enlaces activos: comprueba el estado del envío a Apple Maps y obtén la URL activa.
• Encontrar y corregir errores de las fichas: convierte las filas REQUIRING_ACTION y FAILED en correcciones.
• Referencias del SDK: Cuentas conectadas en Python y Cuentas conectadas en Node.
• Referencia: Conectar una ubicación a Apple Business Connect, Desconectar una ubicación de Apple Business Connect, Crear una URL de conexión mediante OAuth para una ubicación, Enumerar las cuentas conectadas, Obtener fichas prémium, Desconectar una ubicación de una plataforma de publicación.