/api/v4/locations/oauth_connect_url사업장 1개의 OAuth 연결 URL 생성
사업장 1개를 연결하는 게시 플랫폼 OAuth 링크를 생성하며, 성공 및 오류 리디렉션 URL을 직접 지정합니다.
매개변수
본문
| 이름 | 유형 | 필수 | 설명 |
|---|---|---|---|
| input | object | 필수 | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | 필수 | 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 | 필수 | Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`. |
| input.successUrl | string | 필수 | Absolute URL the publisher returns the user to after they grant access. |
| input.errorUrl | string | 필수 | Absolute URL the publisher returns the user to if they cancel or the grant fails. |
요청 예시
바로 붙여 넣을 수 있는 본문입니다. 예시 ID와 값을 실제 값으로 바꾸세요.
{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE", "successUrl": "https://app.example.com/locations/1800289/connected", "errorUrl": "https://app.example.com/locations/1800289/connect-failed" }}응답
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.
{ "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`).
사업장 1개로 범위가 한정된 게시 플랫폼 OAuth URL을 반환합니다. 최종 사용자를 url로 이동시키면, 사용자가 절차를 완료한 후 게시 플랫폼에서 지정한 successUrl(또는 errorUrl)로 리디렉션하고, 생성된 자격 증명이 연결된 계정으로 해당 사업장에 연결됩니다.
이 엔드포인트는 계정 전체에 적용되는 링크를 생성한 다음 매칭을 통해 등록 정보를 연결하는 일괄 처리 흐름인 Google 계정 일괄 연결 및 Facebook 계정 일괄 연결에 대응하는 단일 사업장용 엔드포인트입니다. 사용자가 연결할 사업장을 이미 알고 있고 사용자를 자체 제품 내 해당 사업장 페이지로 돌아오게 하려면 이 엔드포인트를 사용합니다.
리디렉션 URL은 2개 모두 필수이며 절대 URL이어야 합니다. 상대 URL이거나 파싱할 수 없는 값을 지정하면 url이 null인 채로 success: true가 반환되므로, success만 확인하지 말고 url을 확인해야 합니다. 링크는 일회용이며 지정한 사업장에 연결되므로, 캐싱하지 말고 시도할 때마다 새 링크를 생성합니다.
사용 사례: 자체 앱에서 매장 1곳 연결
사용자가 앱에서 매장 1곳을 연결할 때는 사업장 ID, site: "GOOGLE", 앱으로 돌아오는 리디렉션 URL을 포함하여 이 엔드포인트에 POST 요청을 보냅니다. 팝업이나 전체 페이지 리디렉션으로 사용자를 url로 이동시킵니다. 사용자가 돌아오면 연결된 계정 세부 정보 조회 또는 사업장의 연결 정보를 조회하여 연결이 완료되었는지 확인한 다음 앱에 연결된 상태를 표시합니다. 사용자가 절차를 중단하면 errorUrl로 이동하고 아무것도 연결되지 않으므로, 새 링크를 생성하여 다시 시도할 수 있게 합니다.
사용 사례: 소유자의 Apple Business 계정을 통한 게시
사업장 1개를 소유자의 인증된 Apple Business 조직 계정에 연결하려면 site: "APPLE"을 보냅니다. 소유자는 url을 열고 해당 계정에 로그인한 다음 접근 권한을 부여합니다. 이후 ListingsAPI는 소유자의 계정을 통해 해당 사업장의 Apple Maps 데이터를 게시합니다.
소유자에게 인증된 Apple Business 조직 계정이 없으면 이 절차를 건너뜁니다. ListingsAPI는 자체 Apple Business Connect 계정을 통해 사업장을 게시하며, Apple은 게시 전에 제출 내용을 검증합니다. 각 사업장은 개별적으로 연결되므로, 하나의 계정에 두 유형의 사업장이 모두 있을 수 있습니다.
소유자가 successUrl로 돌아오면 publisher=AppleAccount를 사용하여 연결된 계정 목록 조회를 호출하고 계정의 status가 CONNECTED인지 확인합니다. Apple Maps 등록 정보를 확인하는 방법을 포함한 전체 절차는 Apple Business Connect 연결을 참조합니다.
이 엔드포인트는 실제 OAuth 자격 증명을 생성합니다. 위의 샘플 요청과 응답은 예시입니다.
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" } }'