Crea un Google Business Profile para una ubicación sin ficha

Solicita un nuevo Google Business Profile para una ubicación con una cuenta Google conectada y sigue la verificación en la ubicación, fichas y webhooks.

La búsqueda de coincidencias y la vinculación solo funcionan cuando ya existe una ficha de Google. Un establecimiento nuevo no tiene ninguna, así que debes pedir a la API que cree una en una cuenta de Google conectada. La creación es asíncrona y Google verifica el perfil según sus propios plazos, por lo que la mayor parte de esta guía trata sobre cómo supervisar el resultado.

1. Confirma que la ubicación no tenga ninguna ficha de Google

Consulta las fichas prémium de la ubicación y busca la fila cuyo site.name sea Google Maps. Una ubicación sin presencia en Google muestra REQUIRING_ACTION con un connectedAccountId con valor null.

Google row

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

JSON

{  "site": { "name": "Google Maps", "url": "maps.google.com" },  "syncStatus": "REQUIRING_ACTION",  "displayStatus": "Connect your account to sync the listing",  "listingUrl": null,  "connectedAccountId": null,  "verified": false}

Si la fila ya está en SYNCED o connectedAccountId tiene un valor establecido, la ubicación tiene una ficha de Google y esta guía no es aplicable. En ese caso, vincúlala o actualízala.

2. Elige una carpeta (opcional)

Google organiza las fichas de una cuenta en carpetas, también llamadas grupos de cuentas. Obtén la lista de carpetas de la cuenta conectada y pasa una como folderId si el propietario quiere que el perfil nuevo esté dentro de un grupo específico. Omite este paso para crearlo en la raíz de la cuenta.

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. El endpoint solo es válido para conexiones GoogleAccount.

3. Crea la ficha

Envía el id de la ubicación en base64 y la cuenta, además de la carpeta si has elegido una. La respuesta indica que la solicitud se ha aceptado, nada más.

Create 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 }  }}

success: true significa que se ha iniciado la creación, no que el perfil esté publicado. Google revisa cada perfil nuevo antes de publicarlo, y eso puede tardar días. Cuando success es false, errors indica el motivo: a la ubicación le faltan campos obligatorios, ya tiene una ficha de Google, está archivada o la cuenta conectada ya no está activa.

4. Supervisa el estado de verificación de la ubicación

Cada consulta de la ubicación devuelve googleVerificationStatus con un status y un message. Vuelve a consultar la ubicación para ver en qué punto del proceso se encuentra Google.

Verification status

curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "id": "TG9jYXRpb246MTgwMDI4OQ==",  "databaseId": 1800289,  "googleVerificationStatus": { "status": "PENDING_VERIFICATION", "message": null }}

`status`	Significado	Final
`NOT_CONNECTED`	Todavía no hay ninguna ficha de Google asociada. Este es el estado esperado antes de que surta efecto el paso 3.	No
`NOT_VERIFIED`	La ficha existe, pero la verificación no ha comenzado.	No
`PENDING_VERIFICATION`	Google está verificando el perfil.	No
`UNDER_REVIEW`	Google está revisando el perfil.	No
`VERIFIED`	El perfil está publicado.	Sí
`SUSPENDED`	Google ha suspendido el perfil.	Sí
`DUPLICATE`	Google ha determinado que es un duplicado de un perfil existente.	Sí
`ERROR_WHILE_FETCHING`	No se ha podido obtener el estado de Google. Vuelve a intentarlo más tarde.	Sí

Una consulta diaria basta para un proceso que se mide en días. Respeta Retry-After al recibir un 429 si consultas muchas ubicaciones a la vez.

5. Supervisa la fila de Google en las fichas

La fila de las fichas prémium del paso 1 permite seguir el mismo progreso desde la perspectiva de la ficha. Vuelve a ejecutar la llamada del paso 1 y consulta syncStatus, verified y listingUrl.

`syncStatus`	Significado
`REQUIRING_ACTION`	Todavía no se ha creado nada o la cuenta necesita atención. Consulta `displayStatus`.
`IN_PROGRESS`	Enviada a Google, a la espera de una respuesta.
`PENDING_APPROVAL`	A la espera de la aprobación de Google.
`SYNCED`	Publicada. `listingUrl` tiene un valor y `connectedAccountId` indica el nombre de la cuenta.
`FAILED`	Google ha rechazado la solicitud. `syncIssue` indica el motivo.

6. Escucha los webhooks de verificación

Si hay una URL de webhook configurada en el panel, dos eventos cubren los estados finales, por lo que no tienes que realizar consultas periódicas. Ambos incluyen location_id y siempre tienen data.connected_account_id: null.

Evento	Se activa cuando	Campos de `data`
`connection.google_verification_verified`	El perfil alcanza `VERIFIED`.	`platform: "google"`
`connection.google_verification_failed`	El perfil alcanza `SUSPENDED` o `DUPLICATE` (`failure_type: "rejected"`) o `ERROR_WHILE_FETCHING` (`failure_type: "transient"`).	`platform`, `failure_type`, `reason`

JSON

{  "event": "connection.google_verification_failed",  "timestamp": "2026-08-25T14:52:31Z",  "account_id": 11073,  "location_id": "279381",  "data": { "platform": "google", "connected_account_id": null, "failure_type": "rejected", "reason": "This profile is suspended." }}

Solo vale la pena reintentar los fallos de tipo transient. Los estados en curso no emiten ningún evento, por lo que el silencio no es una señal: mientras haya una verificación en curso, consulta googleVerificationStatus como en el paso 4.

Siguientes pasos

Conecta Google e importa ubicaciones: conecta la cuenta de la que depende esta guía.
Consulta el estado de las fichas y los enlaces activos: una vista más amplia de cada fila de plataforma de publicación.
Reacciona a los eventos con webhooks: recibe los eventos de verificación en lugar de realizar consultas periódicas.
Referencia: Crea una ficha de GMB para una ubicación, Enumera las carpetas de GMB, Obtén fichas prémium, Enumera las ubicaciones.