# Google 연동 요청 — BizSpring Google OAuth 연동 API

>  description: 클라이언트 계정으로 발급 받은 인증 토큰을 사용해 API 를 호출합니다. Google 연동 요청 연동고객사 플랫폼과 Google 간의 연동 절차에 대해 설명합니다. 이 과정은 연동 시작을 위한 자사 URL 호출부터 연동 완료 후 UI 업데이트까지 단계별로 진행됩

## 핵심 요약
- 고객사 플랫폼과 Google 간 OAuth 연동 절차를 4단계로 설명하는 API 문서입니다.
- 먼저 자사 API(/media/oauth2/{MEDIA_CODE})를 GET 호출해 Google 인증 URL을 발급받습니다.
- 발급받은 인증 URL을 팝업 창으로 열어 클라이언트가 로그인·권한 승인을 직접 진행합니다.
- 인증 완료 후 팝업이 postMessage로 부모창에 연동 결과(status, code)를 전달하고 닫힙니다.
- 부모창은 수신한 메시지를 바탕으로 연동 상태를 확인하고 UI 업데이트 등 후속 작업을 수행합니다.

---
description: 클라이언트 계정으로 발급 받은 인증 토큰을 사용해 API 를 호출합니다.
---

# Google 연동 요청

연동고객사 플랫폼과 Google 간의 연동 절차에 대해 설명합니다. 이 과정은 연동 시작을  위한 자사 URL 호출부터 연동 완료 후 UI 업데이트까지 단계별로 진행됩니다.



## Google 연동 프로세스

Google 연동은 다음과 같은 단계로 진행됩니다.



### 1. 자사 URL 호출

연동을 시작하기 위한 첫 단계로, Google의 인증을 위해 필요한 **인증 URL** 을 반환받기 위해 자사 API URL을 호출합니다.

{% hint style="info" %}
MEDIA\_CODE

* GOOGLE : 구글
{% endhint %}



#### 요청URL

<pre class="language-http"><code class="lang-http"><strong>https://growthplatform.ai/media/oauth2/{MEDIA_CODE}
</strong></code></pre>



#### 프로토콜

HTTPS



#### **HTTP 메서드**

GET



#### 헤더

<table><thead><tr><th width="173">필드</th><th>설명</th></tr></thead><tbody><tr><td>Content-type</td><td>요청 데이터 타입. application/json 으로 고정</td></tr><tr><td>x-authorization</td><td>사용자 인증 수단, 인증 토큰.   Bearer <a data-footnote-ref href="#user-content-fn-1">{</a><a data-footnote-ref href="#user-content-fn-2">AUTH TOKEN</a>}</td></tr></tbody></table>

* 요청 예시

```http
GET /media/oauth2/GOOGLE
HEADER
Content-Type: application/json
x-authorization: BEARER {AUTH TOKEN}
```

* 응답 결과 예시

<pre class="language-http"><code class="lang-http"><strong>HTTP/1.1 200 OK
</strong>Content-Type: application/json;charset=UTF-8

{
    "status": "OK",
    "message": "https://accounts.google.com/o/oauth2/v2/auth?acce......2111003%22%7D"
}
</code></pre>



### 2. 팝업 창을 통한 인증 URL 호출

고객사 플랫폼은 자사 서버로부터 반환 받은 인증 URL을 팝업 창 형식으로 호출합니다. 이 팝업 창은 클라이언트가 매체사와의 연동 절차(예: 로그인, 권한 승인 등)을 직접 수행할 수 있는 환경을 제공합니다.



### 3. 연동 완료 후 메시지 송신 및 팝업 창 닫기

클라이언트가 매체사의 인증 절차를 완료하면, 팝업 창에 연동 결과와 함께 닫기 버튼이 표시됩니다.  클라이언트가 닫기 버튼을 클릭하면, 팝업 창이 닫히면서 부모창(고객사 플랫폼)으로 연동 결과 메시지를 송신합니다.



응답 데이터 항목

<table><thead><tr><th width="169" align="center">파라미터</th><th width="153" align="center">타입</th><th>설명</th></tr></thead><tbody><tr><td align="center">status</td><td align="center">string</td><td><p>매체 연동 결과</p><ul><li>authorized  :  연동 성공</li><li>unauthorized : 연동 실패 </li></ul></td></tr><tr><td align="center">code</td><td align="center">string</td><td>사용자 고유 식별 키</td></tr></tbody></table>

* 서버 측 코드 예시

```html
// 매체 연동 로직 처리
// 매체 토큰 발생 (callback)

.....
    
// 연동 완료 후 부모창에 메시지 송신 및 팝업창 닫기
<script>
   window.opener.postMessage('authorized', location.origin);  // 성공, 실패 시 unauthorized
   window.close();
   
   $(document).ready(function() {
     // 확인 클릭 시 부모 창에 연동 결과를 메시지로 보내고 팝업을 닫음
     $('#confirmLink').click(function(e) {
       e.preventDefault();
        
       // 부모 창에 메시지 전송       
       // 연동 성공
       window.opener.postMessage('{"status": "authorized", "code": "10135....90241"}', '*');
       // 연동 실패
       window.opener.postMessage('{"status": "unauthorized"}', '*');
        
       // 팝업 창 닫기
       window.close();
     });
   });
  
</script>
```



### 4. 연동 상태에 따른 UI 업데이트 (verified 속성 참고)

부모창(고객사 플랫폼)은 수신 된 메시지를 바탕으로 연동 상태를 확인하고, 필요한 후속 작업(예: UI 업데이트, 데이터 동기화 등)을 수행할 수 있습니다.

&#x20;



[^1]: 인증 토큰

[^2]: 인증 토크ㄴ


## FAQ
**Q. Google 연동을 시작하려면 어떤 API를 호출해야 하나요?**

A. https://growthplatform.ai/media/oauth2/{MEDIA_CODE} 를 HTTPS GET 방식으로 호출합니다. MEDIA_CODE는 구글의 경우 GOOGLE로 지정합니다.

**Q. API 호출 시 인증은 어떻게 처리하나요?**

A. 헤더의 x-authorization 필드에 Bearer {AUTH TOKEN} 형식으로 인증 토큰을 담아 전달해야 합니다. Content-Type은 application/json으로 고정합니다.

**Q. 연동 성공 여부는 어떻게 확인할 수 있나요?**

A. 팝업 창에서 인증이 완료되면 window.opener.postMessage를 통해 status 값(authorized 또는 unauthorized)과 code가 부모창으로 전달됩니다. 부모창은 이 메시지를 바탕으로 연동 성공 여부를 판단할 수 있습니다.

**Q. 연동 완료 후 팝업 창은 자동으로 닫히나요?**

A. 클라이언트가 인증 절차를 완료하면 팝업 창에 결과와 닫기 버튼이 표시되며, 닫기 버튼을 클릭하면 팝업이 닫히면서 부모창으로 결과 메시지가 전송됩니다.

**Q. 연동 결과를 받은 후 고객사 플랫폼에서 해야 할 작업은 무엇인가요?**

A. 수신한 메시지의 연동 상태를 확인하여 UI 업데이트나 데이터 동기화 같은 필요한 후속 작업을 수행하면 됩니다.

---
출처: https://bizspring.ai/kb/ref/manual/bizspring-google-oauth-연동-api-google-연동-요청 · 최종 갱신 2026-08-28T09:46:33.982+00:00