Conecte o Apple Business Connect

Publique no Apple Maps via conta verificada do dono no Apple Business ou ListingsAPI, se não tiver uma. Confira a listagem e desconecte se o cliente sair.

A ListingsAPI publica o nome, a categoria, o endereço, o telefone, o site e os horários de um local no Apple Maps e na Siri de uma das duas maneiras.

O OAuth conecta um local por vez, com site definido como APPLE.

1. Crie o link de conexão e redirecione o proprietário

Pule as etapas 1 e 2 se o proprietário não tiver uma conta de organização verificada no Apple Business.

POST /locations/oauth_connect_url retorna uma URL OAuth com escopo limitado a um local. Envie site: "APPLE" com o ID do local e suas duas URLs de redirecionamento. Referência: Conecte um local ao Apple Business Connect.

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": "APPLE",    "successUrl": "https://app.example.com/locations/1800289/apple/connected",    "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed"  }}'

A resposta é data.createConnectUrl com success, url e errors. Redirecione o proprietário para url. Ele faz login em sua conta de organização verificada no Apple Business, concede acesso e é redirecionado para seu successUrl; se ele cancelar ou a concessão de acesso falhar, será redirecionado para errorUrl.

O link é de uso único, então crie um novo a cada tentativa. Uma URL de redirecionamento relativa ou que não possa ser interpretada resulta em success: true com um url com valor null, então verifique url antes de redirecionar. Uma chave sem permissão para acessar esse local recebe 403 com SY90003.

2. Confirme a conexão

Depois que o proprietário retornar ao seu successUrl, liste as contas conectadas filtrando pela Apple. Esta é uma página com paginação por deslocamento: records[] mais pageInfo.totalRecords, paginada com page e perPage.

curl "https://listingsapi.com/api/v4/connected-accounts?publisher=AppleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

Guarde o connectedAccountId. status é CONNECTED, MATCH_IN_PROGRESS ou CONNECTIVITY_ISSUE; qualquer valor diferente de CONNECTED significa que o proprietário precisa abrir um novo link de conexão antes que as atualizações possam ser feitas por meio da conta dele.

3. Verifique a listagem no Apple Maps

Esta etapa é a mesma, independentemente de o proprietário ter conectado uma conta. GET /locations/{locationId}/listings/premium retorna um registro por plataforma de publicação premium incluída no plano. O registro do Apple Maps tem site.url definido como business.apple.com.

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

O registro não é SYNCED e listingUrl é null até que a Apple publique o cartão do local. Quando o local é enviado por meio da conta da ListingsAPI, a Apple verifica o envio antes de publicar. Assim que a Apple publica, o registro é SYNCED com listingUrl definido como a URL da listagem publicada no Apple Maps. Para consultar a tabela completa de status, veja Verifique o status das listagens e os links publicados.

Os resultados da Siri vêm da listagem do local no Apple Maps. O status desses resultados é retornado por GET /locations/{locationId}/voice-assistants no voiceIdentifier SIRI.

4. Confirme as correspondências sugeridas

Se as sugestões de conexão incluírem registros da Apple, o accountType desses registros será APPLE, e o tipo de registro de correspondência que você codifica para Confirme as correspondências de conexão será AppleLocationMatchedData. Crie o ID codificando AppleLocationMatchedData:<matchedDataDatabaseId> em base64 e envie-o em matchRecordIds.

5. Desconecte o local quando um cliente sair

Esta etapa se aplica apenas a um local conectado com OAuth. POST /locations/oauth-disconnect remove a conexão entre um local e a conta do Apple Business do proprietário. Envie site: "APPLE". O local permanece na sua conta, e suas conexões com outras plataformas de publicação não são afetadas. Referência: Desconectar um local do Apple Business Connect.

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

A resposta é data.disconnectConnectedAccountsLocations com success e errors. Um local sem conexão ativa com a Apple retorna SY10057, e uma solicitação sem site nem providerId retorna SY10056.

6. O que acontece em seguida

Não há evento de webhook connection.* para a Apple. Se o proprietário se conectou com OAuth, confirme a conexão listando as contas (etapa 2). Em ambos os casos, verifique o status de publicação lendo o registro do Apple Maps (etapa 3). O evento listing.submission informa cada envio a uma plataforma de publicação quando ele atinge um estado final.

Se a conexão posteriormente informar CONNECTIVITY_ISSUE, crie um novo link de conexão (etapa 1) e peça ao proprietário que faça login novamente.

Próximas etapas

• Verificar o status da listagem e os links ativos: verifique o status do envio ao Apple Maps e obtenha a URL ativa.
• Encontrar e corrigir erros de listagem: transforme as linhas REQUIRING_ACTION e FAILED em correções.
• Referências dos SDKs: Contas conectadas em Python e Contas conectadas em Node.
• Referência: Conectar um local ao Apple Business Connect, Desconectar um local do Apple Business Connect, Criar uma URL de conexão OAuth para um local, Listar contas conectadas, Obter listagens premium, Desconectar um local de uma plataforma de publicação.