Cuentas conectadas

Todos los endpoints, ejemplos cURL/Python/Node: conectar Google/Facebook, listar cuentas, cotejar/vincular fichas, carpetas, crear GMB y desconectar.

Una cuenta conectada es una autorización OAuth concedida por el propietario de una cuenta de Google Business Profile o Facebook Pages que permite a la API leer y gestionar las fichas a las que esa cuenta tiene acceso. El recurso cubre tres tareas: crear los enlaces OAuth, buscar coincidencias o vincular las fichas de la cuenta con tus ubicaciones y eliminar la conexión. Las dos consultas GET, de lista y de detalle, funcionan con una clave Read (lectura); cada POST, incluida la consulta de fichas de solo lectura, necesita una clave Write (escritura), y usar una clave Read en una operación de escritura devuelve HTTP 400 con SY90016.

Todos los ejemplos siguientes suponen que el cliente se crea una sola vez, como muestra el primer ejemplo, y leen LISTINGSAPI_KEY del entorno. Los identificadores son el UUID connectedAccountId del endpoint de lista y el identificador de ubicación en base64 (TG9jYXRpb246MTgwMDI4OQ==); nunca apliques codificación URL a ninguno de los dos.

Resumen de endpoints

MétodoRutaFunciónReferencia
POST/connected-accounts/connect-googleCrea un enlace de conexión masiva para una cuenta de Google, válido durante 24 horas.Conectar una cuenta de Google
POST/connected-accounts/connect-facebookCrea un enlace de conexión masiva para una cuenta de Facebook, válido durante 24 horas.Conectar una cuenta de Facebook
POST/locations/oauth_connect_urlCrea un enlace de conexión de un solo uso asociado a una ubicación.URL de conexión OAuth para una ubicación
GET/connected-accountsEnumera las cuentas conectadas con su estado y el número de fichas vinculadas.Enumerar las cuentas conectadas
GET/connected-accounts/{connectedAccountId}/detailsConsulta una cuenta, incluido el estado de la tarea de búsqueda de coincidencias.Obtener los detalles de una cuenta conectada
POST/connected-accounts/connected-account-listingsEnumera las fichas de las plataformas de publicación a las que una cuenta tiene acceso.Obtener las fichas de una cuenta conectada
POST/connected-accounts/trigger-matchesAñade a la cola la tarea de obtención de fichas y búsqueda de coincidencias para una o más cuentas.Iniciar la búsqueda de coincidencias de ubicaciones
GET/connected-accounts/{connectedAccountId}/connection-suggestionsConsulta las correspondencias sugeridas entre ubicaciones y fichas.Enumerar las sugerencias de conexión
POST/connected-accounts/confirm-matchesAcepta las sugerencias y crea los vínculos activos.Confirmar las coincidencias de conexión
POST/connected-accounts/connect-listingVincula una ficha seleccionada a una ubicación.Conectar una ficha a una ubicación
POST/connected-accounts/disconnect-listingDesvincula una ubicación de una plataforma de publicación.Desconectar una ficha de una ubicación
POST/connected-accounts/create-location-from-listingCrea una ubicación a partir de una ficha de una plataforma de publicación.Crear una ubicación a partir de una ficha
GET/connected-accounts/{connectedAccountId}/foldersEnumera los grupos de cuentas de Google (carpetas).Enumerar las carpetas de GMB
POST/locations/create/gmb-listingCrea un perfil nuevo de Google Business Profile para una ubicación.Crear una ficha de GMB
POST/connected-accounts/disconnect-googleDesconecta una cuenta de Google completa.Desconectar una cuenta de Google
POST/connected-accounts/disconnect-facebookDesconecta una cuenta de Facebook completa.Desconectar una cuenta de Facebook
POST/locations/oauth-disconnectDesconecta una ubicación de una plataforma de publicación (la misma operación que disconnect-listing).Desconectar una ubicación de una plataforma de publicación

POST /connected-accounts/connect-google

Devuelve una URL OAuth de corta duración. Redirige al propietario de la cuenta a esa URL; Google lo devuelve a tu successUrl o errorUrl. El enlace se limita a la cuenta a la que pertenece la clave de API, por lo que el cuerpo solo contiene tus dos URL de redirección. Volver a generar un enlace para una cuenta cuya autorización ha caducado actualiza la conexión existente en lugar de duplicarla.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor; todo el cuerpo se incluye dentro de él.
input.successUrlbodysíURL https absoluta que controlas. Se accede a ella después de otorgar el consentimiento.
input.errorUrlbodysíURL https absoluta que controlas. Se accede a ella en caso de cancelación o error.
Connect Google
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/google/success",    "errorUrl": "https://app.example.com/connect/google/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForGoogle": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

El valor de url anterior es un marcador de posición. Dirige al propietario al valor de url devuelto en tu propia respuesta.

El enlace es válido durante 24 horas. errors solo se rellena cuando falla la generación, así que comprueba que url no sea null. Un cuerpo sin anidar, o uno que contenga un accountId, se rechaza con HTTP 400.

POST /connected-accounts/connect-facebook

Es el equivalente para Facebook, con el mismo cuerpo. Durante el proceso, el propietario acepta las condiciones de Facebook y concede los permisos de gestión de páginas que necesita la API; si omite un permiso, la conexión no puede sincronizarse, así que vuelve a generar el enlace y pídele que otorgue el consentimiento de nuevo.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.successUrlbodysíURL https absoluta que controlas.
input.errorUrlbodysíURL https absoluta que controlas.
Connect Facebook
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/facebook/success",    "errorUrl": "https://app.example.com/connect/facebook/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForFacebook": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

El valor de url anterior es un marcador de posición. Dirige al propietario al valor de url devuelto en tu propia respuesta.

La clave de la respuesta es bulkConnectLinkForFacebook; por lo demás, interprétala exactamente igual que la del enlace de Google. Una vez que el propietario termina, la cuenta aparece en el endpoint de lista como un FacebookAccount.

POST /locations/oauth_connect_url

Úsalo cuando ya sepas qué ubicación va a conectar el propietario. El enlace queda vinculado a la ubicación que indiques, por lo que no hay un paso posterior de búsqueda de coincidencias: cuando el propietario da su consentimiento, las credenciales se asocian directamente a esa ubicación. En cambio, los dos enlaces de conexión masiva anteriores conectan una cuenta completa.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.locationIdbodysíID de la ubicación en Base64 o ID numérico sin codificar.
input.sitebodysíGOOGLE, FACEBOOK o APPLE.
input.successUrlbodysíURL absoluta a la que se redirige tras conceder la autorización.
input.errorUrlbodysíURL absoluta a la que se redirige en caso de cancelación o fallo.
Single-location 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": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}'
JSON
{  "data": {    "createConnectUrl": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

El valor url anterior es un marcador de posición. Dirige al propietario al valor de url devuelto en tu propia respuesta.

El enlace es de un solo uso, así que crea uno nuevo para cada intento en lugar de almacenarlo en caché. Una URL de redirección relativa o que no se pueda analizar devuelve success: true con null url, así que comprueba url y no solo success. Una clave sin permiso para operar sobre esta ubicación recibe un 403 con SY90003. Los SDK convierten site a mayúsculas por ti.

Listar las cuentas conectadas

GET /connected-accounts

Devuelve todas las cuentas autorizadas en tu cuenta de API, con el estado de la conexión y el número de ubicaciones vinculadas a cada una. La paginación se basa en desplazamientos: records[] más pageInfo.totalRecords, con los parámetros de consulta page y perPage sin anidar. El orden es fijo y ascendente por correo electrónico de la cuenta.

NombreEnObligatorioNotas
pagequerynoNúmero de página, empezando por 1. Valor predeterminado: 1.
perPagequerynoRegistros por página. Valor predeterminado: 20.
publisherquerynoGoogleAccount, FacebookAccount, AppleAccount, YelpAccount, TripadvisorAccount, LinkedinAccount, PinterestAccount o TwitterAccount.
statusquerynoConnected, NotConnected o ConnectionIssue. Con mayúsculas y minúsculas.
List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=GoogleAccount&status=Connected&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "totalPages": 1, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "connectedAccountType": "GoogleAccount",          "email": "owner@brightsmile-dental.com",          "status": "CONNECTED",          "connectivityIssue": null,          "connectedLocationsCount": 0,          "requestMatchesStatus": "MATCH_COMPLETED",          "lastFetchMatchesRequestedAt": "2026-07-06 21:43:07 UTC"        }      ]    }  }}

Selecciona el registro cuyo email corresponda al propietario que dio su consentimiento y guarda su connectedAccountId; todas las llamadas posteriores lo requieren. Cualquier dato distinto de los cuatro parámetros de consulta se ignora en lugar de rechazarse, por lo que enviar pageInfo en JSON devuelve la página 1 sin avisar.

status del registroSignificado
CONNECTEDLas credenciales son válidas. Puedes iniciar la búsqueda de coincidencias o publicar con seguridad.
MATCH_IN_PROGRESSHay una búsqueda de coincidencias en cola o en curso.
CONNECTIVITY_ISSUELa autorización ha caducado. connectivityIssue indica el motivo; vuelve a generar el enlace de conexión.

El filtro status y el campo status del registro no usan el mismo conjunto de valores. Pasar CONNECTED como valor del filtro proporciona un valor de enumeración no válido y devuelve un 400.

Obtener los detalles de una cuenta

GET /connected-accounts/{connectedAccountId}/details

Devuelve los mismos campos que un registro de la lista, limitados a una cuenta. Úsalo para consultar periódicamente requestMatchesStatus después de iniciar la búsqueda de coincidencias, o para comprobar status y connectivityIssue antes de enviar una actualización a través de la cuenta.

NombreEnObligatorioNotas
connectedAccountIdpathsíUUID obtenido del endpoint que lista las cuentas.
Account details
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/details \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountDetails": {      "details": {        "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",        "connectedAccountType": "GoogleAccount",        "status": "CONNECTED",        "connectivityIssue": null,        "connectedLocationsCount": 0,        "requestMatchesStatus": "MATCH_COMPLETED"      }    }  }}

El registro está un nivel por debajo, en data.connectedAccountDetails.details. requestMatchesStatus pasa de MATCH_IN_PROGRESS a MATCH_COMPLETED cuando las sugerencias están listas. El estado completado significa que el proceso de búsqueda de coincidencias ha terminado, no que se haya vinculado algo: connectedLocationsCount permanece en 0 hasta que confirmes o conectes una ficha.

Obtener las fichas a las que tiene acceso una cuenta

POST /connected-accounts/connected-account-listings

Lista todas las fichas de Google Business Profile o Facebook a las que tiene acceso la cuenta, estén o no vinculadas a una de tus ubicaciones. El valor de id de cada registro es el connectedAccountListingId que reciben connect-listing y create-location-from-listing. Es una operación POST que solo lee datos y devuelve una página basada en desplazamientos: records[] más pageInfo, con las claves page y perPage sin anidar en el cuerpo para controlar la paginación.

NombreEnObligatorioNotas
connectedAccountIdbodysíUUID de la cuenta cuyas fichas se van a obtener. No va dentro de input.
pagebodynoNúmero de página. Valor predeterminado: 1.
perPagebodynoRegistros por página. Valor predeterminado: 500, que también es el máximo.
locationInfobodynoBúsqueda de texto libre por nombre, dirección, localidad, código postal, código de tienda y teléfono.
Account listings
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50, "locationInfo": "William St" }'
JSON
{  "data": {    "connectedAccountListings": {      "pageInfo": { "hasNextPage": false, "totalPages": 1, "totalRecords": 60 },      "records": [        {          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "accountTypeName": "Google",          "locationName": "Trial",          "address": "123 William St, NY 10038, Manhattan, US",          "phone": "(718) 667-7787",          "liveLink": null        }      ]    }  }}

Recorre las páginas del conjunto con pageInfo.hasNextPage y pageInfo.totalPages. Los SDK colocan connectedAccountId en el cuerpo por ti, por lo que esto solo afecta a las llamadas REST escritas manualmente.

Iniciar el emparejamiento

POST /connected-accounts/trigger-matches

Pone en cola la tarea que recupera todos los perfiles a los que pueden acceder las cuentas indicadas y empareja cada uno con una de tus ubicaciones. El emparejamiento tiene en cuenta todas las ubicaciones activas, no archivadas y que aún no están conectadas. Solo guarda sugerencias; no se vincula nada hasta que lo confirmes.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.connectedAccountIdsbodysíArray de UUID de cuentas del endpoint de listado.
Trigger matches
curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["4f712c17-4f95-42dd-90f4-97171a2e67b5"] } }'
JSON
{  "data": {    "connectedAccountsTriggerMatches": {      "success": true,      "failedIds": null    }  }}

success: true significa que la tarea se puso en cola, no que el emparejamiento haya terminado. Las cuentas que no se hayan podido poner en cola aparecen en failedIds y success tiene el valor false. Consulta periódicamente el endpoint de detalles hasta que requestMatchesStatus tenga el valor MATCH_COMPLETED antes de leer las sugerencias; hacerlo cada 15 segundos con un bucle limitado mantiene el plan Launch dentro de su límite de 10 solicitudes por minuto.

Consultar las sugerencias de conexión

GET /connected-accounts/{connectedAccountId}/connection-suggestions

Devuelve los emparejamientos propuestos por el proceso de emparejamiento: tu ubicación por un lado (locationInfo, con locationId como su databaseId) y la ficha de la plataforma de publicación por el otro (suggestedLocationInfo). La paginación se basa en desplazamientos y utiliza los parámetros de consulta page y perPage sin anidar; el orden es fijo y ascendente según la información de la ubicación.

NombreEnObligatorioNotas
connectedAccountIdpathsíUUID de la cuenta.
pagequerynoNúmero de página a partir de 1. El valor predeterminado es 1.
perPagequerynoRegistros por página. El valor predeterminado es 20.
Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectionSuggestionsForAccount": {      "pageInfo": { "hasNextPage": false, "totalPages": 1, "totalRecords": 2 },      "records": [        {          "accountType": "GMB",          "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc",          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "locationId": "73415",          "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" },          "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } }        }      ]    }  }}

Una sugerencia no tiene id. Conserva matchedDataDatabaseId y accountType juntos; confirm-matches necesita ambos para construir su id. Si consultas demasiado pronto, antes de MATCH_COMPLETED, el endpoint devuelve records: [] con totalRecords: 0, una respuesta idéntica a la que indica que no se encontró ninguna coincidencia.

accountTypePlataforma de publicaciónTipo de registro de emparejamiento
GMBGoogle Business ProfileGmbLocationMatchedData
FBFacebook PagesFbLocationMatchedData
APPLEApple Business ConnectAppleLocationMatchedData

Confirmar los emparejamientos

POST /connected-accounts/confirm-matches

Acepta las sugerencias que apruebas y crea los vínculos activos. Cada id es la codificación en base64 de <MatchRecordType>:<matchedDataDatabaseId>, con el tipo elegido de la tabla anterior. La cuenta se deduce de los registros, por lo que no hay ningún campo connectedAccountId; un campo desconocido dentro de input se rechaza con un 400.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor. Solo se declara matchRecordIds.
input.matchRecordIdsbodysíArray de ids de registros de emparejamiento codificados en base64. Al menos uno.
Confirm matches
# base64 of GmbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M="] } }'
JSON
{  "data": {    "confirmConnectMatches": {      "success": true,      "failedIds": null    }  }}

failedIds contiene los valores decodificados de matchedDataDatabaseId que no se pudieron confirmar, como un registro ya utilizado o una ubicación archivada desde el emparejamiento, así que busca los registros de sugerencias correspondientes a esos valores. Las sugerencias no enviadas se dejan intactas. La confirmación vincula la ubicación a la ficha; por sí sola, no envía datos a la plataforma de publicación.

Conectar una ficha a una ubicación

POST /connected-accounts/connect-listing

Vincula una única ficha que ya has elegido a una única ubicación, sin pasos de sugerencia ni de confirmación. Úsalo cuando el emparejamiento sea ambiguo, por ejemplo, si hay dos establecimientos cercanos con nombres similares y un operador elige el correcto entre las fichas de la cuenta.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.locationIdbodysíId de la ubicación codificado en base64.
input.connectedAccountIdbodysíUUID de la cuenta propietaria de la ficha.
input.connectedAccountListingIdbodysíEl id de un registro del endpoint de fichas de la cuenta. No listingId.
Connect listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "connectListing": {      "success": true,      "message": null    }  }}

Un intento de vinculación fallido devuelve success: false con un message distinto de null, por ejemplo, Listing record not found cuando no se encuentra la ficha correspondiente al id, o una nota que indica que la ficha ya está conectada a otra ubicación. En ambos SDK, este método pertenece al recurso de fichas, no al de cuentas conectadas.

Desconectar una ficha de una ubicación

POST /connected-accounts/disconnect-listing

Elimina el vínculo entre una ubicación y una plataforma de publicación. La ubicación y sus datos se conservan; solo se detiene la sincronización de salida hacia esa plataforma de publicación. Este endpoint no admite operaciones en lote, así que recorre las ubicaciones con un bucle. Para vincular un establecimiento a otra cuenta de Google, desconéctalo aquí primero y después realiza el emparejamiento o la conexión en la nueva cuenta.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.locationIdbodysíId codificado en base64 de la única ubicación.
input.sitebodyuno deGOOGLE, FACEBOOK o APPLE. Obligatorio salvo que se envíe providerId.
input.providerIdbodyuno deEl identificador de cuenta propio de la plataforma de publicación, en lugar de site.
Disconnect listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE" } }'
JSON
{  "data": {    "disconnectConnectedAccountsLocations": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

Si no envías ni site ni providerId, se devuelve SY10056. Si una ubicación no tiene una conexión activa con ese sitio, se devuelve SY10057 en lugar de indicar éxito sin más, por lo que success: true sí significa que se ha eliminado un vínculo. Los SDK solo aceptan site y lo convierten a mayúsculas.

Crear una ubicación a partir de una ficha

POST /connected-accounts/create-location-from-listing

La coincidencia solo empareja fichas con ubicaciones que ya tienes. Para una ficha sin ubicación, esta operación crea una a partir de los datos de la plataforma de publicación y la vincula de inmediato con la ficha. Google importa el nombre, la dirección, las coordenadas, el teléfono, el sitio web, la descripción, los horarios habituales y especiales, las categorías, la fecha de apertura, el código de tienda y la zona horaria, además de los métodos de pago y los enlaces a redes sociales derivados de los atributos de Google de la ficha. Facebook importa el nombre, la ubicación, los horarios, las categorías, la descripción y los datos de contacto.

En una importación desde Google, los datos no se vuelven a enviar a Google, por lo que su ficha permanece en IN_PROGRESS hasta que publiques en ella la primera actualización de la ubicación. Los datos se envían con normalidad a todas las demás plataformas de publicación, y este endpoint no acepta un ámbito de sitios, por lo que la ubicación se crea para el conjunto completo de plataformas de publicación de tu cuenta. Restringe ese conjunto con enabledSiteIds justo después de la creación y envía esa actualización de inmediato: los elementos del pedido para las demás plataformas de publicación se generan poco después de la creación, y la actualización no retira los que ya se hayan generado.

Ninguno de los dos SDK incluye todavía un método para este endpoint, por lo que los ejemplos de Python y Node llaman a REST con la misma cabecera.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.connectedAccountIdbodysíUUID de la cuenta a la que pertenece la ficha.
input.connectedAccountListingIdbodysíEl id de un registro del endpoint de fichas de la cuenta. No listingId.
Create from listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "createLocationFromConnectedAccountListing": {      "success": true,      "locationId": 88277,      "errors": null    }  }}

locationId es el databaseId sin codificar de la nueva ubicación. En caso de error, success es false, locationId es null y errors contiene un código que indica el motivo, como SY81067 (no se encontró la ficha correspondiente al id); otras causas son una ficha ya vinculada a otra ubicación o una cuenta cuyas credenciales hayan caducado. Una vez creada, gestiona la ubicación como cualquier otra.

Listar las carpetas de una cuenta de Google

GET /connected-accounts/{connectedAccountId}/folders

Devuelve los grupos de cuentas de Google Business Profile (carpetas) a los que puede acceder la cuenta de Google conectada. Úsalo antes de crear una ficha de GMB para que el nuevo perfil se cree en el grupo que espera el propietario. La respuesta es un array simple en getFoldersUnderGoogleAccount, no una página. La ruta solo es válida para conexiones de tipo GoogleAccount.

NombreEnObligatorioNotas
connectedAccountIdpathsíUUID de una cuenta de tipo Google.
Folders
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/folders \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getFoldersUnderGoogleAccount": [      { "folderId": "accounts/104890024806530350198", "folderName": "Bright Smile Dental", "locationCount": null }    ]  }}

Usa folderId sin modificarlo; es la cadena accounts/{id}, no un número. locationCount puede ser null cuando Google no lo proporciona, así que trátalo como opcional.

Crear un Google Business Profile para una ubicación

POST /locations/create/gmb-listing

Crea una ficha de Google completamente nueva para una ubicación que no tiene ninguna, en una cuenta de Google conectada y, opcionalmente, dentro de una carpeta. Se diferencia de connect-listing, que vincula una ficha ya existente. La ubicación ya debe tener nombre, dirección y teléfono, y solo puede existir una ficha de Google por ubicación.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.locationIdbodysíId de la ubicación en Base64.
input.connectedAccountIdbodysíUUID de la cuenta de Google en la que se creará la ficha.
input.folderIdbodynoCadena accounts/{id} del endpoint de carpetas. Omítela para usar la raíz de la cuenta.
Create GMB listing
curl -X POST https://listingsapi.com/api/v4/locations/create/gmb-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "folderId": "accounts/104890024806530350198"  }}'
JSON
{  "data": {    "createGmbListingForLocation": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

La creación es asíncrona: success: true significa que se aceptó la solicitud, y Google revisa los perfiles nuevos antes de que se publiquen. Cuando success es false, errors indica el motivo: faltan campos obligatorios, ya existe una ficha de Google, la ubicación está archivada o la cuenta está inactiva.

Desconectar una cuenta de Google completa

POST /connected-accounts/disconnect-google

Elimina la conexión de toda la cuenta: todas las ubicaciones vinculadas a través de ella dejan de sincronizarse. No hay ningún campo locationIds; para desvincular una sola ubicación y conservar la cuenta, usa disconnect-listing. Usa esta opción cuando un cliente se dé de baja o cuando no puedas eliminar una autorización defectuosa y quieras empezar de nuevo con un enlace de conexión nuevo.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.connectedAccountIdbodysíUUID de la cuenta de Google. Se desconecta toda la cuenta.
Disconnect Google
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'
JSON
{  "data": {    "gmbBulkDisconnect": {      "success": true    }  }}

Se devuelve success: true incluso si connectedAccountId es desconocido, por lo que significa "se ha procesado la solicitud", no "se ha eliminado una conexión activa". Vuelve a consultar la lista de cuentas conectadas si necesitas confirmarlo.

Desconectar una cuenta de Facebook completa

POST /connected-accounts/disconnect-facebook

La operación equivalente para Facebook, con el mismo cuerpo. Las páginas vinculadas a través de la cuenta dejan de sincronizarse y las interacciones de Facebook dejan de aparecer.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.connectedAccountIdbodysíUUID de la cuenta de Facebook. Se desconecta toda la cuenta.
Disconnect Facebook
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'
JSON
{  "data": {    "fbBulkDisconnect": {      "success": true    }  }}

La clave de la respuesta es fbBulkDisconnect. Al igual que con Google, success: true para un id desconocido significa que se ha procesado la solicitud, no que se haya eliminado la conexión.

Desconectar una ubicación de una plataforma de publicación

POST /locations/oauth-disconnect

La parte de desconexión del flujo OAuth por ubicación. Es la misma operación que disconnect-listing, disponible a través de una segunda ruta: un cuerpo input idéntico y la misma clave de respuesta disconnectConnectedAccountsLocations. Elige la ruta que resulte más clara en tu integración.

NombreEnObligatorioNotas
inputbodysíObjeto contenedor.
input.locationIdbodysíid en Base64 de la única ubicación.
input.sitebodyuno de ellosGOOGLE, FACEBOOK o APPLE. Obligatorio salvo que se envíe providerId.
input.providerIdbodyuno de ellosEl identificador de cuenta propio de la plataforma de publicación, en lugar de site.
OAuth 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": "GOOGLE" } }'
JSON
{  "data": {    "disconnectConnectedAccountsLocations": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

Se aplican las mismas reglas de SY10056 y SY10057, y una solicitud con una clave sin permiso para operar sobre esta ubicación recibe un 403 con SY90003. La desconexión deja intactos la ubicación y sus datos; solo se detiene la sincronización saliente hacia esa plataforma de publicación. Para vincular la ficha correcta después, vuelve a dirigir al propietario a la URL de conexión o ejecuta la búsqueda de coincidencias y connect-listing.

Errores que verás

Las solicitudes mal formadas y las claves no válidas devuelven un 4xx con un errors[] de nivel superior cuyo message empieza por el código. Las operaciones de escritura también pueden devolver 200 con success: false y el motivo dentro de data.<operation>, así que comprueba el cuerpo de la respuesta de cada operación de escritura. La lista completa está en Códigos de error.

Código o estadoSignificadoSolución
SY90016 (400)Se ha usado una clave Read en un POST.Usa una clave Write.
SY90003 (403)La clave no tiene permiso para conectar o desconectar esta ubicación.Usa una clave con acceso a la ubicación.
SY10056 (200)La solicitud de desconexión no ha enviado ni site ni providerId.Envía uno de ellos.
SY10057 (200)La ubicación no tiene ninguna conexión activa para ese sitio.No hay nada que eliminar; comprueba las fichas de la ubicación.
SY81067 (200)No se ha podido resolver connectedAccountListingId en create-from-listing.Vuelve a obtener las fichas de la cuenta y usa el id de un registro.
400, Variable "$input" ... was not providedEl cuerpo no estaba contenido en input o faltaba un campo obligatorio.Anida el cuerpo dentro de input; usa connectedAccountListingId, no listingId.
400, invalid enumSe ha reutilizado el estado CONNECTED de un registro como filtro status de la lista.Filtra con Connected, NotConnected o ConnectionIssue.
429Se ha superado el límite de solicitudes.Espera el tiempo indicado por Retry-After; consulta Límites de solicitudes.

Siguientes pasos