Criar uma URL de conexão OAuth para um local

Parâmetros

Corpo

Nome	Tipo	Obrigatório	Descrição
input	object	obrigatório	Wrapper object. The entire request body must be nested under `input`.
input.locationId	string	obrigatório	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	obrigatório	Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`.
input.successUrl	string	obrigatório	Absolute URL the publisher returns the user to after they grant access.
input.errorUrl	string	obrigatório	Absolute URL the publisher returns the user to if they cancel or the grant fails.

Exemplo de requisição

Corpo pronto para colar. Substitua os IDs e valores de exemplo pelos seus.

Request body

{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}

Respostas

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.

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`).

Retorna uma URL OAuth da plataforma de publicação com escopo limitado a um local. Encaminhe o usuário final para url; quando ele concluir, a plataforma de publicação o redirecionará para successUrl (ou errorUrl), e as credenciais resultantes serão vinculadas ao local como uma conta conectada.

Esta é a alternativa para um único local aos fluxos em massa, Conectar contas do Google em massa e Conectar contas do Facebook em massa, que criam um link com escopo de toda a conta e depois dependem da correspondência para vincular listagens. Use esta rota quando você já souber qual local o usuário está conectando e quiser que ele retorne à página desse local no seu próprio produto.

As duas URLs de redirecionamento são obrigatórias e devem ser absolutas; um valor relativo ou que não possa ser interpretado é retornado como success: true com um null url, portanto, verifique url e não apenas success. O link é de uso único e está vinculado ao local que você especificou, portanto, crie um novo a cada tentativa em vez de armazená-lo em cache.

Caso de uso: conectar uma loja pelo seu próprio aplicativo

Quando um usuário conectar uma loja pelo seu aplicativo, faça uma solicitação POST a esta rota com o ID do local, site: "GOOGLE" e URLs de redirecionamento que levem de volta ao seu aplicativo. Encaminhe o usuário para url em uma janela pop-up ou por meio de um redirecionamento de página inteira. Quando ele retornar, consulte Obter detalhes da conta conectada ou as informações de conexão do local para confirmar que o vínculo foi estabelecido e, em seguida, mostre o estado conectado no seu aplicativo. Se o usuário abandonar o fluxo, ele será encaminhado para errorUrl e nada será vinculado, portanto, crie um novo link e permita que ele tente novamente.

Caso de uso: publicar por meio da conta Apple Business do proprietário

Envie site: "APPLE" para conectar um local à conta de organização verificada do proprietário no Apple Business. O proprietário abre url, faz login nessa conta e concede acesso. A partir daí, a ListingsAPI publica os dados desse local no Apple Maps por meio da conta do proprietário.

Se o proprietário não tiver uma conta de organização verificada no Apple Business, pule este fluxo. A ListingsAPI publica o local por meio de sua própria conta Apple Business Connect, e a Apple verifica o envio antes de publicá-lo. Cada local é conectado separadamente, portanto, uma conta pode ter os dois tipos de local.

Depois que o proprietário retornar para successUrl, chame Listar contas conectadas com publisher=AppleAccount e verifique se o valor de status da conta é CONNECTED. Para ver o fluxo completo, incluindo como verificar a listagem no Apple Maps, consulte Conectar o Apple Business Connect.

Este endpoint cria credenciais OAuth reais. A solicitação e a resposta de exemplo acima são ilustrativas.

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" } }'