> For the complete documentation index, see [llms.txt](https://www.analytics-docs.laplacetec.com/guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.analytics-docs.laplacetec.com/guide/startguide/connect/ad/toss-ads.md).

# 토스애즈 연결

라플라스에 토스애즈를 연결하는 방법입니다. 토스애즈 광고주센터에서 API 키(Client ID, Client Secret)를 발급하고 라플라스에 입력해 광고 성과 데이터를 연결하는 순서와 연결 오류 해결 방법을 안내합니다.

이 가이드는 토스애즈 광고 성과 데이터를 라플라스에 연결하는 방법을 안내합니다. 토스애즈 광고주센터에서 발급받은 API 키(Client ID, Client Secret)를 라플라스에 입력하면 연결돼요.

## 연결 절차 개요 <a href="#overview" id="overview"></a>

1. 토스애즈 광고주센터에서 API 키를 발급받아요. 발급 화면에 Client ID와 Client Secret이 보여요.
2. 라플라스 **토스애즈 연결** 화면에서 **데이터 연결**을 눌러 API 키를 입력하고 **연결하기**를 눌러요. 키가 확인되면 **토스애즈 연결이 완료되었습니다.** 안내가 보여요.
3. **데이터 소스 선택** 창에서 광고계정을 고르고 **데이터 연결**을 눌러요. 수집이 시작되고 **연결된 데이터** 표에 그 광고계정이 보여요.

## 사전 준비 <a href="#ready" id="ready"></a>

* 토스애즈 광고주센터의 **계정장** 권한 (API 키는 계정장만 발급할 수 있어요)
* 토스애즈 광고주센터에서 발급받은 Client ID, Client Secret
* 라플라스 계정

{% hint style="info" %}
**API 키 하나는 광고계정 하나에 연결돼요.** 광고계정이 여러 개라면 광고계정마다 API 키를 발급받아 하나씩 연결해 주세요.
{% endhint %}

***

## Step 1. 토스애즈 광고주센터에서 API 키 발급 <a href="#api-key" id="api-key"></a>

API 키는 광고계정마다 따로 발급하고, 그 광고계정의 **계정장**만 발급할 수 있어요. 발급받은 키를 라플라스에 입력하는 사람은 계정장이 아니어도 돼요.

### 1-1. 내가 계정장인지 확인

1. 토스애즈 [광고주센터](https://ads-platform.toss.im/advertiser/api-key)에 로그인합니다.
2. **내 광고계정** 목록에서 라플라스에 연결할 광고계정을 엽니다.
3. **광고계정 구성원** 탭에서 내 권한이 **계정장**인지 확인합니다.

계정장이 아니라면 그 광고계정의 계정장에게 아래 1-2 순서대로 API 키를 발급해 Client ID와 Client Secret을 전달해 달라고 요청해 주세요.

### 1-2. API 키 발급

1. 연결할 광고계정 안에서 **광고도구** > **API 키**로 이동합니다.
2. API 키를 발급합니다. 발급할 때 권한(범위)을 고르는 칸이 보이면 리포트 조회 권한(ads:report.read)을 꼭 포함해 주세요. 이 권한이 없으면 라플라스가 광고 성과를 가져올 수 없어요.
3. 발급된 **Client ID**와 **Client Secret**을 바로 복사해 안전한 곳에 보관합니다.

{% hint style="warning" %}
**Client Secret은 발급할 때 한 번만 확인할 수 있어요.** 창을 닫기 전에 Client Secret을 꼭 따로 저장해 주세요. Client Secret은 비밀번호와 같은 역할이니 공개된 곳에 올리지 말고, 키를 입력할 담당자에게만 전달해 주세요.
{% endhint %}

### 광고계정이 여러 개라면

* 광고계정 하나에 API 키 하나가 묶여요. 연결할 광고계정마다 1-2를 반복해 키를 따로 발급해 주세요.
* 라플라스에서도 키마다 [Step 2](#step2)를 한 번씩 진행하면 광고계정이 하나씩 연결돼요.

### Client Secret을 잃어버렸다면

* 같은 광고계정에서 API 키를 새로 발급해 주세요.
* 이미 라플라스에 연결한 광고계정이라면 새 키를 [인증 갱신](#reauth)으로 입력해 주세요.
* 예전 키를 광고주센터에서 폐기하면 그 키로 된 연결은 멈춰요. 인증 갱신을 먼저 마친 뒤 예전 키를 폐기해 주세요.

***

## Step 2. 라플라스에서 토스애즈 연결 <a href="#step2" id="step2"></a>

1. 왼쪽 레일의 **데이터 연결**을 누른 뒤, 탐색 패널의 **커넥터 검색**에 토스애즈를 입력하거나 **광고 채널 연결** 카테고리에서 **토스애즈 연결**을 눌러 주세요(1). **토스애즈 연결** 화면 머리글 오른쪽의 **데이터 연결**을 눌러 연결 창을 열어 주세요(2).

   ![토스애즈 연결 화면과 머리글의 데이터 연결 버튼](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-1bb1622d05551d3c9df0e85a869e3adb72c07a29%2Fstartguide__connect__ad__toss-ads__01.png?alt=media)
2. **토스애즈 데이터 연결** 창의 **API 키 정보**에 Step 1에서 보관한 **Client ID**와 **Client Secret**을 입력하고(1) **연결하기**를 눌러 주세요(2). 키를 확인하는 동안 **새로운 토스애즈 커넥션을 추가하는 중입니다.** 창이 잠시 보여요. 창 위쪽 연결 순서에서 지금 단계를 확인할 수 있어요.

   ![토스애즈 데이터 연결 창 Client ID·Client Secret 입력](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-bd2b88b53fcb40ec1ebc43fd047c8cdf7490e990%2Fstartguide__connect__ad__toss-ads__02.png?alt=media)
3. 키가 확인되면 **토스애즈 연결이 완료되었습니다.** 안내와 함께 **데이터 소스 선택** 창이 열려요. 그 키에 연결된 광고계정을 선택하고(1) **데이터 연결**을 눌러 수집을 시작해 주세요(2).

   ![데이터 소스 선택에서 광고계정 선택 후 데이터 연결](https://2146870105-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVMM5rubRDzSVhvd8yr0%2Fuploads%2Fgit-blob-cffa47a492b915b1cb0377019d57d1ef40554a60%2Fstartguide__connect__ad__toss-ads__03.png?alt=media)

* **데이터 연결**을 누르기 전에 창을 닫았다면 **연결된 데이터** 표에서 그 광고계정 행의 ⋯ 버튼 > **데이터 소스 추가**를 눌러 같은 창을 다시 열고 **데이터 연결**을 눌러 주세요.
* 연결한 계정은 **토스애즈 연결** 화면의 **연결된 데이터** 표에 보여요. 행 오른쪽 ⋯ 버튼에서 **최신화**, **데이터 소스 추가**, **인증 갱신**, **삭제**를 할 수 있습니다.

{% hint style="info" %}
**데이터 연동이 왜 오래 걸리나요?**

👉 라플라스에서는 토스애즈의 데이터를 가져오기만 하는 것이 아니라 가져온 데이터를 정제하고 차트를 그려주는 작업을 해주기 때문이에요. 소요되는 시간 또한 데이터의 양이 많을수록 오래 걸릴 수도 있어요.

💬 진행 상황은 상단 바 오른쪽 **작업 · 데이터 상태**에서 확인할 수 있고, 연동이 완료되면 이메일로도 알려 드려요. 라플라스를 종료해도 수집은 계속되니 안심하시고 종료하셔도 됩니다.
{% endhint %}

***

## 연결이 되지 않을 때 <a href="#error" id="error"></a>

**연결하기**를 누른 뒤 **데이터 연결 오류** 창이 열리면 창에 보이는 문구에 따라 아래처럼 해 주세요.

* **Client ID 또는 Client Secret이 올바르지 않습니다. 다시 확인해 주세요.**
  * 원인: Client ID 또는 Client Secret이 잘못 입력됐거나, 광고주센터에서 폐기한 키, 일시 차단된 키예요.
  * 조치: 창에 함께 보이는 확인 항목대로 해 주세요. 광고주센터에서 발급받은 Client ID와 Client Secret을 앞뒤 공백 없이 그대로 다시 입력하고, 키를 폐기했거나 새로 발급받았다면 광고주센터 **광고도구** > **API 키**에서 지금 쓰는 키를 확인해 주세요. Client Secret을 잃어버렸다면 새로 발급받아 입력해 주세요. 키가 일시 차단됐다면 토스애즈 [채널톡](https://toss-business.channel.io/)으로 차단 해제를 문의해 주세요.
* **이 API 키에는 리포트 조회 권한(ads:report.read)이 없습니다. 토스애즈 광고주센터에서 권한을 포함해 키를 다시 발급받아 입력해 주세요.**
  * 원인: 입력한 API 키에 광고 성과(리포트) 조회 권한이 없어요.
  * 조치: 광고주센터 **광고도구** > **API 키**에서 리포트 조회 권한을 포함해 키를 다시 발급받아 입력해 주세요.
* **토스애즈 API 요청이 많습니다. 잠시 후에 다시 시도해 주세요.**
  * 원인: 짧은 시간에 같은 API 키로 요청이 많이 들어갔어요.
  * 조치: 잠시 기다린 뒤 다시 **연결하기**를 눌러 주세요.
* **토스애즈 서버가 일시적으로 응답하지 않습니다. 잠시 후 다시 시도해 주세요.**
  * 원인: 토스애즈 쪽에 일시적인 문제가 있어요.
  * 조치: 잠시 후 다시 시도해 주세요. 계속되면 담당 매니저에게 문의해 주세요.
* **이미 연결된 토스애즈 광고 계정입니다.**
  * 원인: 이 키의 광고계정이 다른 소유자의 라플라스 프로젝트에 이미 연결돼 있어요.
  * 조치: 그 광고계정을 연결한 담당자에게 확인해 주세요. 그 데이터를 함께 보려면 그 프로젝트에 멤버로 초대받아 주세요. 누가 연결했는지 모르겠다면 아래 채팅 상담으로 문의해 주세요.

***

## 인증 갱신 <a href="#reauth" id="reauth"></a>

연결한 뒤에는 따로 갱신할 필요가 없어요. 라플라스가 연결을 유지합니다.

{% hint style="danger" %}
연결에 쓴 API 키를 광고주센터에서 폐기하면 라플라스가 데이터를 가져올 수 없어요. 같은 광고계정의 API 키를 새로 발급받았다면 **연결된 데이터** 표에서 그 광고계정 행의 ⋯ 버튼 > **인증 갱신**을 눌러 주세요. 바로 **연결된 토스애즈 광고 계정의 Client ID와 Client Secret을 다시 입력해 주세요. 다른 광고 계정의 키로는 이 연결을 다시 인증할 수 없습니다.** 안내와 함께 입력 창이 열려요. 새 Client ID와 Client Secret을 입력하고 **연결하기**를 눌러 주세요. 키가 확인되면 그 연결이 다시 인증되고 창이 닫혀요.
{% endhint %}

{% hint style="warning" %}
**인증 갱신 창에는 이 연결의 광고계정에서 발급한 키를 넣어 주세요.** 다른 광고계정의 키를 넣으면 기존 연결은 다시 인증되지 않고, 그 키의 광고계정이 새 연결로 추가돼요. 이때 **다른 광고 계정의 키입니다** 창이 열려요.

1. **닫기**를 눌러 창을 닫아 주세요.
2. 잘못 추가된 연결은 **연결된 데이터** 표에서 그 광고계정 행의 ⋯ 버튼 > **삭제**를 눌러 지워 주세요. 그 광고계정도 연결해 둘 생각이라면 그대로 두셔도 돼요.
3. 다시 인증할 연결의 광고계정에서 발급한 API 키를 준비해, 그 연결 행의 ⋯ 버튼 > **인증 갱신**에 다시 입력해 주세요.
   {% endhint %}

***

## 연결 해제 <a href="#disconnect" id="disconnect"></a>

연결 해제는 라플라스의 **토스애즈 연결** 화면에서 해 주세요. **연결된 데이터** 표에서 해제할 광고계정 행의 ⋯ 버튼 > **삭제**를 누르면 돼요. 토스애즈 광고주센터의 API 키는 라플라스에서 지워지지 않으니, 더 쓰지 않는다면 광고주센터에서 직접 폐기해 주세요.

***

## 전담 매니저에게 요청하기

토스애즈 연결에 어려움이 있으신가요?

하단의 문의하기 혹은 홈페이지의 채팅 상담을 통해 문의하세요. 담당 매니저가 도움을 드리도록 하겠습니다.

> 💬 [채팅으로 문의하기](https://laplacetec.channel.io/lounge)
>
> 💬 [홈페이지에서 문의하기](https://www.analytics.laplacetec.com/contact)

**이메일 문의:** [**product@laplacetec.com**](mailto:product@laplacetec.com)

API 키 발급 메뉴나 토스애즈 광고계정에 관한 문의는 토스애즈 [채널톡](https://toss-business.channel.io/)으로 해 주세요.
