/api/v4/locations/oauth_connect_urlCrear una URL de conexión OAuth para una ubicación
Crea un enlace OAuth de una plataforma de publicación que conecta una sola ubicación, con tus propias redirecciones de éxito y error.
Parámetros
Cuerpo
| Nombre | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| input | object | obligatorio | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | obligatorio | 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 | obligatorio | Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`. |
| input.successUrl | string | obligatorio | Absolute URL the publisher returns the user to after they grant access. |
| input.errorUrl | string | obligatorio | Absolute URL the publisher returns the user to if they cancel or the grant fails. |
Solicitud de ejemplo
Cuerpo listo para pegar. Sustituye los ID y valores de ejemplo por los tuyos.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE", "successUrl": "https://app.example.com/locations/1800289/connected", "errorUrl": "https://app.example.com/locations/1800289/connect-failed" }}Respuestas
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.
{ "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`).
Devuelve una URL OAuth de una plataforma de publicación limitada a una ubicación. Envía al usuario final a url; cuando termine, la plataforma de publicación lo redirigirá a tu successUrl (o errorUrl) y las credenciales resultantes se asociarán a la ubicación como una cuenta conectada.
Esta es la alternativa para una sola ubicación a los flujos de conexión masiva, Conectar cuentas de Google en bloque y Conectar cuentas de Facebook en bloque, que crean un enlace para toda la cuenta y luego dependen de la búsqueda de coincidencias para asociar fichas. Usa esta ruta cuando ya sepas qué ubicación está conectando el usuario y quieras que vuelva a la página de esa ubicación en tu propio producto.
Ambas URL de redirección son obligatorias y deben ser absolutas; un valor relativo o que no se pueda analizar se devuelve como success: true con un null url, así que comprueba url y no solo success. El enlace es de un solo uso y está vinculado a la ubicación que especificaste, así que crea uno nuevo para cada intento en lugar de almacenarlo en caché.
Caso de uso: conectar una tienda desde tu propia aplicación
Cuando un usuario conecte una tienda desde tu aplicación, haz una solicitud POST a esta ruta con el ID de la ubicación, site: "GOOGLE" y las URL de redirección que lleven de vuelta a tu aplicación. Envía al usuario a url en una ventana emergente o mediante una redirección de página completa. Cuando vuelva, consulta Obtener los detalles de una cuenta conectada o la información de conexión de la ubicación para confirmar que se ha establecido la conexión y, a continuación, muestra el estado conectado en tu aplicación. Si el usuario abandona el flujo, llegará a errorUrl y no se asociará nada, así que crea un enlace nuevo y permite que lo intente de nuevo.
Caso de uso: publicar a través de la cuenta de Apple Business del propietario
Envía site: "APPLE" para conectar una ubicación a la cuenta de organización verificada de Apple Business del propietario. El propietario abre url, inicia sesión en esa cuenta y concede acceso. A partir de ese momento, ListingsAPI publica los datos de Apple Maps de esa ubicación a través de la cuenta del propietario.
Si el propietario no tiene una cuenta de organización verificada de Apple Business, omite este flujo. ListingsAPI publica la ubicación a través de su propia cuenta de Apple Business Connect, y Apple verifica el envío antes de publicarlo. Cada ubicación se conecta por separado, por lo que una cuenta puede tener ubicaciones de ambos tipos.
Cuando el propietario vuelva a successUrl, llama a Listar cuentas conectadas con publisher=AppleAccount y comprueba que el valor de status de la cuenta sea CONNECTED. Para conocer el flujo completo, incluido cómo comprobar la ficha de Apple Maps, consulta Conectar Apple Business Connect.
Este endpoint crea credenciales OAuth reales. La solicitud y la respuesta de muestra anteriores son ejemplos.
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" } }'