Apple Business Connect 연결

소유자의 인증된 Apple Business 계정을 통해, 또는 해당 계정이 없으면 ListingsAPI 계정을 통해 사업장을 Apple Maps에 게시한 다음, 등록 정보를 확인하고 고객이 서비스를 해지하면 연결을 해제합니다.

ListingsAPI는 2가지 방법 중 하나로 사업장의 이름, 카테고리, 주소, 전화번호, 웹사이트, 영업시간을 Apple Maps와 Siri에 게시합니다.

OAuth는 site를 APPLE로 설정하여 한 번에 하나의 사업장을 연결합니다.

1. 연결 링크 생성 및 소유자 리디렉션

소유자에게 인증된 Apple Business 조직 계정이 없으면 1단계와 2단계를 건너뜁니다.

POST /locations/oauth_connect_url은 하나의 사업장으로 범위가 제한된 OAuth URL을 반환합니다. 사업장 ID와 리디렉션 URL 2개를 포함하여 site: "APPLE"을 보냅니다. 참조: 사업장을 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"  }}'

응답은 success, url, errors를 포함하는 data.createConnectUrl입니다. 소유자를 url로 리디렉션합니다. 소유자가 인증된 Apple Business 조직 계정에 로그인하여 접근 권한을 부여하면 지정한 successUrl로 리디렉션되며, 소유자가 취소하거나 권한 부여에 실패하면 errorUrl로 리디렉션됩니다.

링크는 일회용이므로 시도할 때마다 새로 생성합니다. 리디렉션 URL이 상대 URL이거나 파싱할 수 없는 경우 success: true와 함께 url이 null로 반환되므로, 리디렉션하기 전에 url을 확인합니다. 이 사업장에 접근할 권한이 없는 키를 사용하면 SY90003을 포함하는 403이 반환됩니다.

2. 연결 확인

소유자가 지정한 successUrl로 돌아오면 Apple로 필터링하여 연결된 계정 목록을 조회합니다. 이는 records[]와 pageInfo.totalRecords로 구성된 오프셋 기반 페이지이며, page와 perPage로 페이지를 나눕니다.

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

connectedAccountId를 보관합니다. status는 CONNECTED, MATCH_IN_PROGRESS 또는 CONNECTIVITY_ISSUE이며, CONNECTED가 아닌 경우 소유자가 새 연결 링크를 열어야 해당 계정을 통해 업데이트를 전송할 수 있습니다.

3. Apple Maps 등록 정보 확인

이 단계는 소유자의 계정 연결 여부와 관계없이 동일합니다. GET /locations/{locationId}/listings/premium은 요금제에 포함된 프리미엄 게시 플랫폼마다 레코드 1개를 반환합니다. Apple Maps 레코드의 site.url은 business.apple.com으로 설정됩니다.

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

Apple이 장소 카드를 게시하기 전까지 레코드는 SYNCED가 아니며 listingUrl은 null입니다. ListingsAPI 계정을 통해 사업장을 제출한 경우, Apple은 제출 내용을 검증한 후 게시합니다. Apple이 게시하면 레코드는 SYNCED가 되고 listingUrl은 실제 공개된 Apple Maps URL로 설정됩니다. 전체 상태 표는 등록 정보 상태 및 공개 URL 확인을 참조하세요.

Siri 결과는 사업장의 Apple Maps 등록 정보에서 가져옵니다. 해당 결과의 상태는 GET /locations/{locationId}/voice-assistants가 SIRI voiceIdentifier 아래에 반환합니다.

4. 추천 일치 항목 확정

연결 추천에 Apple 레코드가 포함되어 있으면 해당 레코드의 accountType은 APPLE이며, 연결 일치 항목 확정을 위해 인코딩하는 일치 레코드 유형은 AppleLocationMatchedData입니다. AppleLocationMatchedData:<matchedDataDatabaseId>를 base64로 인코딩하여 ID를 생성하고 matchRecordIds에 담아 전송합니다.

5. 고객이 떠나면 사업장 연결 해제

이 단계는 OAuth로 연결된 사업장에만 적용됩니다. POST /locations/oauth-disconnect는 사업장 1개와 소유자의 Apple Business 계정 간 연결을 해제합니다. site: "APPLE"을 전송합니다. 사업장은 계정에 그대로 유지되며 다른 게시 플랫폼과의 연결은 영향을 받지 않습니다. 참조: 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" } }'

응답은 data.disconnectConnectedAccountsLocations이며 success와 errors를 포함합니다. 사업장에 활성 Apple 연결이 없으면 SY10057이 반환되고, 요청에 site와 providerId가 모두 없으면 SY10056이 반환됩니다.

6. 이후 진행 과정

Apple에는 connection.* 웹훅 이벤트가 없습니다. 소유자가 OAuth로 연결했다면 계정 목록을 조회하여 연결을 확인합니다(2단계). 두 경우 모두 Apple Maps 레코드를 조회하여 게시 상태를 확인합니다(3단계). listing.submission 이벤트는 각 게시 플랫폼에 대한 제출이 최종 상태에 도달하면 이를 알립니다.

이후 연결 상태가 CONNECTIVITY_ISSUE로 보고되면 새 연결 링크를 생성하고(1단계) 소유자에게 다시 로그인하도록 요청합니다.

다음 단계

• 등록 정보 상태 및 공개 URL 확인: Apple Maps 제출 상태를 확인하고 공개 URL을 수집합니다.
• 등록 정보 오류 찾기 및 수정: REQUIRING_ACTION 및 FAILED 행을 바탕으로 오류를 수정합니다.
• SDK 참조: Python 연결된 계정 및 Node 연결된 계정.
• 참조: Apple Business Connect에 사업장 연결, Apple Business Connect에서 사업장 연결 해제, 사업장 1개의 OAuth 연결 URL 생성, 연결된 계정 목록 조회, 프리미엄 등록 정보 조회, 게시 플랫폼에서 사업장 1개 연결 해제.