Listings APIListings API
Entrar

Crie um Google Business Profile para um local sem perfil

Envie um novo Google Business Profile para um local em uma conta Google conectada e acompanhe a verificação pelo local, suas listagens e webhooks.

A correspondência e a vinculação só funcionam quando já existe uma listagem no Google. Um estabelecimento novo não tem nenhuma, então você solicita à API que crie uma em uma conta do Google conectada. A criação é assíncrona e o Google verifica o perfil no próprio ritmo, por isso a maior parte deste guia trata de acompanhar o resultado.

1. Confirme que o local não tem uma listagem no Google

Consulte as listagens premium do local e encontre a linha cujo site.name seja Google Maps. Um local sem presença no Google mostra REQUIRING_ACTION com connectedAccountId igual a 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}

Se a linha já estiver como SYNCED, ou se connectedAccountId estiver definido, o local tem uma listagem no Google e este guia não se aplica. Nesse caso, vincule ou atualize a listagem existente.

2. Escolha uma pasta (opcional)

O Google organiza as listagens de uma conta em pastas, também chamadas de grupos de contas. Liste as pastas da conta conectada e informe uma como folderId se o proprietário quiser o novo perfil em um grupo específico. Pule esta etapa para criá-lo na raiz da conta.

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

Use folderId sem alterações; trata-se da string accounts/{id}, não de um número. locationCount pode ser null quando o Google não o informa. O endpoint só é válido para conexões GoogleAccount.

3. Crie a listagem

Envie o id do local em base64 e a conta, além da pasta, se você tiver escolhido uma. A resposta informa apenas que a solicitação foi aceita.

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 a criação foi iniciada, não que um perfil esteja publicado. O Google analisa cada novo perfil antes de publicá-lo, e isso pode levar dias. Quando success é false, errors informa o motivo: faltam campos obrigatórios no local, ele já tem uma listagem no Google, está arquivado ou a conta conectada não está mais ativa.

4. Acompanhe o status de verificação do local

Toda consulta ao local retorna googleVerificationStatus com um status e um message. Consulte o local novamente para ver em que etapa do processo o Google está.

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 }}
statusSignificadoTerminal
NOT_CONNECTEDNenhuma listagem no Google está vinculada ainda. Esse é o estado esperado antes de a etapa 3 surtir efeito.Não
NOT_VERIFIEDA listagem existe, mas a verificação não começou.Não
PENDING_VERIFICATIONO Google está verificando o perfil.Não
UNDER_REVIEWO Google está analisando o perfil.Não
VERIFIEDO perfil está publicado.Sim
SUSPENDEDO Google suspendeu o perfil.Sim
DUPLICATEO Google considerou o perfil uma duplicata de um perfil existente.Sim
ERROR_WHILE_FETCHINGNão foi possível consultar o status no Google. Tente novamente mais tarde.Sim

Uma consulta diária é suficiente para um processo que leva dias. Respeite Retry-After ao receber um 429 se você consultar muitos locais de uma vez.

5. Acompanhe a linha do Google nas listagens

A linha das listagens premium da etapa 1 acompanha o mesmo progresso pela perspectiva da listagem. Execute novamente a chamada da etapa 1 e consulte syncStatus, verified e listingUrl.

syncStatusSignificado
REQUIRING_ACTIONNada foi criado ainda, ou a conta precisa de atenção. Consulte displayStatus.
IN_PROGRESSEnviada ao Google, aguardando uma resposta.
PENDING_APPROVALAguardando a aprovação do Google.
SYNCEDPublicada. listingUrl está preenchido e connectedAccountId identifica a conta.
FAILEDO Google rejeitou o envio. syncIssue informa o motivo.

6. Escute os webhooks de verificação

Se uma URL de webhook estiver definida no painel, dois eventos cobrem os estados finais, para que você não precise fazer consultas periódicas. Ambos incluem location_id e sempre têm data.connected_account_id: null.

EventoÉ disparado quandoCampos de data
connection.google_verification_verifiedO perfil atinge VERIFIED.platform: "google"
connection.google_verification_failedO perfil atinge SUSPENDED ou DUPLICATE (failure_type: "rejected") ou 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." }}

Só vale a pena tentar novamente em caso de falhas transient. Os estados em andamento não emitem nenhum evento, portanto o silêncio não é um sinal: enquanto uma verificação estiver em andamento, leia googleVerificationStatus como na etapa 4.

Próximas etapas