Listings APIListings API
로그인
POST/api/v4/locations/oauth_connect_url

Apple Business Connect에 사업장 연결

사업장 1개의 Apple Business Connect OAuth 링크를 생성하여 ListingsAPI가 소유자의 인증된 Apple Business 계정을 통해 해당 사업장을 Apple Maps에 게시하도록 합니다.

API 키가 필요합니다. 헤더 형식과 키 교체는 인증을 참고하세요.

매개변수

본문

이름유형필수설명
inputobject필수Wrapper object. The entire request body must be nested under `input`.
input.locationIdstring필수Location to connect. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID.
input.sitestring필수Set to `APPLE`.
input.successUrlstring필수Absolute URL in your application the owner returns to after granting access.
input.errorUrlstring필수Absolute URL in your application the owner returns to if they cancel or the grant fails.

요청 예시

바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.

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

응답

200A single-use link to send the owner to. `errors` is `null` on success. The `url` shown is a placeholder; send the owner 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`).

사업장 소유자에게 인증된 Apple Business 조직 계정이 있는 경우 사용합니다. 소유자를 url로 안내하면 소유자는 Apple Business Connect에 로그인하고 액세스를 허용한 후 설정한 successUrl로 돌아옵니다. 이후 ListingsAPI는 소유자의 계정을 통해 해당 사업장의 이름, 카테고리, 주소, 전화번호, 웹사이트 및 영업시간을 Apple Maps에 게시합니다. 소유자가 취소하거나 액세스 권한 부여에 실패하면 errorUrl로 돌아오며 아무것도 연결되지 않습니다.

소유자에게 인증된 Apple Business 조직 계정이 없으면 이 호출을 건너뜁니다. ListingsAPI는 자체 Apple Business Connect 계정을 통해 사업장을 게시하며, Apple은 게시 전에 제출 내용을 검증합니다.

Apple은 링크 1개당 사업장 1개를 연결합니다. 여러 사업장을 연결하려면 각 사업장에 대한 링크를 생성합니다. 리디렉션 URL 2개는 모두 절대 URL이어야 하며, 상대 URL이거나 파싱할 수 없는 값이면 url이 null인 채로 success: true가 반환되므로 리디렉션하기 전에 url을 확인합니다. 링크는 1회용이므로 시도할 때마다 새 링크를 생성합니다.

연결 확인

소유자가 successUrl로 돌아오면 publisher=AppleAccount를 사용하여 연결된 계정 목록 조회를 호출합니다. status가 CONNECTED이면 소유자의 계정을 통해 업데이트가 이루어집니다. MATCH_IN_PROGRESS 또는 CONNECTIVITY_ISSUE이면 소유자가 새 연결 링크를 열어야 합니다.

소유자의 계정을 통한 게시를 중단하려면 Apple Business Connect에서 사업장 연결 해제를 사용합니다. Apple Maps 등록 정보를 확인하는 방법을 포함한 전체 절차는 Apple Business Connect 연결을 참조합니다.

이 페이지는 사업장 1개의 OAuth 연결 URL 생성 중 site: "APPLE"인 경우를 설명합니다.

이 엔드포인트는 실제 OAuth 자격 증명을 생성합니다. 위의 샘플 요청과 응답은 예시입니다.

Request
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"    }  }'
Run in playground