# 개발자 마켓플레이스 시작 가이드

CRM 마켓플레이스의 OAuth API는 개발자에게 두 가지 접근 방식을 제공합니다: 로케이션 레벨 액세스(Location Level Access, 하위 계정이라고도 함)와 에이전시 레벨 액세스(Agency Level Access, 회사라고도 함)입니다. 이러한 접근 레벨은 개별 로케이션이나 에이전시 전체 수준에서 로케이션 데이터를 포괄적으로 제어할 수 있게 해줍니다. 로케이션 레벨 액세스를 통해 개발자는 하위 계정에 특화된 작업을 수행할 수 있고, 에이전시 레벨 액세스는 전체 에이전시의 데이터를 관리할 수 있게 합니다. 이러한 구분을 통해 효율적인 데이터 처리와 향상된 CRM 마켓플레이스 API v2.0 상호 운용성을 보장합니다.

개발자 지원 링크: [https://developers.gohighlevel.com/support](/hyperclass-docs/developer/how-to-get-started-with-the-developer-s-marketplace.md)

개발자 지원 티켓을 생성할 때는 항상 모든 세부 정보와 가능한 경우 Loom 영상을 제공해주세요.

**목차**

* [용어 해설](#용어-해설)
* [개발자 마켓플레이스의 OAuth 플로우란?](#개발자-마켓플레이스의-oauth-플로우란)
* [PKCE를 사용한 OAuth 2.0 (Proof Key for Code Exchange)](#pkce를-사용한-oauth-20-proof-key-for-code-exchange)
* [OAuth V2를 사용하여 앱에 웹훅을 구성하는 방법](#oauth-v2를-사용하여-앱에-웹훅을-구성하는-방법)
* \[마켓플레이스에서 판매: 자동 생성 개발자 계정 (에이전시 관리자)]\(#마켓플레이스에서-판매:-자동-생성-개발자-계정-(에이전시-관리자)
* [자주 묻는 질문](#자주-묻는-질문)

## 용어 해설

* **GoHighLevel**: GoHighLevel은 비즈니스가 성장하고 운영을 간소화할 수 있도록 마케팅, 영업, 자동화 도구를 제공하는 종합 플랫폼입니다. GoHighLevel 웹사이트
* **개발자 마켓플레이스(Developer's Marketplace)**: 개발자 마켓플레이스는 GoHighLevel 내의 플랫폼으로, 개발자가 GoHighLevel API를 사용하여 애플리케이션과 도구를 구축하고 통합할 수 있게 해줍니다. GoHighLevel 개발자 문서
* **API (Application Programming Interface)**: API는 서로 다른 소프트웨어 애플리케이션이 서로 통신할 수 있게 하는 규칙과 프로토콜의 집합입니다. 개발자 마켓플레이스 맥락에서 GoHighLevel API는 개발자가 GoHighLevel의 기능과 데이터에 액세스하고 상호작용할 수 있게 해줍니다.
* **액세스 토큰(Access Token)**: 액세스 토큰은 앱이 사용자나 계정의 보호된 리소스에 액세스하기 위해 사용하는 자격 증명입니다. 개발자 마켓플레이스에서 개발자는 OAuth 프로세스를 통해 액세스 토큰을 획득하며, 이를 통해 앱이 GoHighLevel에 인증된 API 요청을 할 수 있게 됩니다. 액세스 토큰은 보통 API 요청의 Authorization 헤더에 포함됩니다. 액세스 토큰 이해하기
* **AppID** - 마켓플레이스 애플리케이션의 고유 식별자입니다. 앱 이름 아래에서 찾을 수 있습니다.

![앱 ID 위치](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155001343880/original/sruOBgrJNZSpZPOl6voCkffehXwOI3cbiw.png?1687202766)

* **대화 공급자 ID(Conversation Provider ID)** - 사용자가 설치하는 공급자 유형의 고유 식별자입니다. 앱에 대화 공급자를 생성한 경우 대화 공급자 이름 아래에서 찾을 수 있습니다.

![대화 공급자 ID 위치](https://s3.amazonaws.com/cdn.freshdesk.com/data/helpdesk/attachments/production/155001343982/original/0M9QmyhmbfmOKZ2lEeT0H_GqBZFjVm05VA.png?1687203031)

* **리프레시 토큰(Refresh Token)**: 리프레시 토큰은 사용자가 앱을 다시 승인할 필요 없이 새로운 액세스 토큰을 얻는 데 사용할 수 있는 자격 증명입니다. 더 오래 지속되는 인증 메커니즘을 제공하고 GoHighLevel 리소스에 대한 지속적인 액세스를 유지하는 데 도움이 됩니다. 액세스 토큰이 만료되면 리프레시 토큰을 사용하여 새로운 토큰을 얻을 수 있습니다.
* **OAuth (Open Authorization)**: OAuth는 보안 앱 인증 및 인증을 가능하게 하는 업계 표준 프로토콜입니다. 사용자가 로그인 자격 증명을 공유하지 않고도 앱이 GoHighLevel 데이터에 액세스할 수 있도록 권한을 부여할 수 있게 해줍니다. OAuth에는 사용자가 GoHighLevel로 리디렉션되어 인증하고 앱에 액세스 권한을 부여하는 인증 프로세스가 포함됩니다. OAuth 2.0 소개
* **리디렉트 URI(Redirect URI)**: 리디렉트 URI는 사용자가 앱의 액세스를 승인한 후 GoHighLevel이 사용자를 보낼 URL입니다. OAuth 프로세스 중에 사용자는 권한을 부여한 후 인증 코드나 액세스 토큰이 리디렉트 URI에 추가되어 앱으로 리디렉션됩니다. OAuth 2.0 리디렉트 URI
* **인증 코드(Authorization Code)**: OAuth 프로세스에서 인증 코드는 사용자가 앱을 성공적으로 승인한 후 얻는 단기 자격 증명입니다. 앱은 이 코드를 액세스 토큰과 리프레시 토큰으로 교환합니다. OAuth 2.0 인증 코드 부여
* **스코프(Scopes)**: 스코프는 앱이 GoHighLevel과 상호작용하기 위해 필요한 특정 권한과 액세스 권한을 정의합니다. 앱을 생성할 때 개발자는 앱의 기능에 맞는 필요한 스코프를 지정합니다. 스코프에는 GoHighLevel 내의 다양한 리소스에 대한 읽기, 쓰기 또는 관리 권한이 포함될 수 있습니다. OAuth 2.0 스코프 및 GoHighLevel의 OAuth 스코프를 위한 리소스
* **엔드포인트(Endpoint)**: 엔드포인트는 API 리소스나 기능을 나타내는 특정 URL이나 URI입니다. GoHighLevel의 API는 개발자가 특정 작업을 수행하거나 특정 데이터를 검색하기 위해 액세스할 수 있는 다양한 엔드포인트를 노출합니다.
* **요청(Request)**: 요청은 앱이 GoHighLevel API에 보내는 통신입니다. HTTP 메소드(예: GET, POST), URL 또는 엔드포인트, 헤더, 필요한 매개변수나 데이터를 포함합니다.
* **응답(Response)**: 응답은 앱이 보낸 요청에 대한 서버의 회신입니다. 요청된 데이터, 수행된 작업의 확인, 적절한 상태 코드를 포함합니다.
* **상태 코드(Status Code)**: 상태 코드는 HTTP 요청의 결과를 나타내기 위해 서버가 반환하는 세 자리 숫자입니다. 일반적인 상태 코드에는 200(성공), 400(잘못된 요청), 401(권한 없음), 422(처리할 수 없는 엔터티)가 있습니다. HTTP 상태 코드
* **배포 유형(Distribution Type)**: 배포 유형은 앱이 GoHighLevel 사용자에게 배포되거나 제공되는 방법을 나타냅니다. 에이전시 또는 하위 계정일 수 있습니다. 에이전시 배포는 에이전시 계정 내의 모든 로케이션에서 앱을 사용할 수 있게 하고, 하위 계정 배포는 특정 하위 계정이나 개별 로케이션으로 사용을 제한합니다.
* **로케이션 ID(Location ID)**: 로케이션 ID는 GoHighLevel 계정 내의 특정 로케이션에 할당된 고유 식별자입니다. 로케이션 레벨에서 액세스를 구별하고 관리하는 데 사용됩니다.
* **회사 ID(Company ID)**: 회사 ID는 GoHighLevel 회사나 계정에 할당된 고유 식별자입니다. 회사 레벨에서 액세스를 구별하고 관리하는 데 도움이 됩니다.
* **해시된 회사 ID(Hashed Company ID)**: 해시된 회사 ID는 GoHighLevel 회사나 계정과 연결되었던 더 이상 사용되지 않는 식별자입니다. 더 이상 사용되지 않으며 단계적으로 폐지되고 있습니다.
* **라이브 서버(Live Server)**: 라이브 서버는 앱이 GoHighLevel의 API와 실제 사용자 데이터와 상호작용하는 실제 프로덕션 환경을 나타냅니다. 앱이 배포되고 사용자가 액세스할 수 있는 서버입니다.
* **SDK (Software Development Kit)**: SDK는 개발자가 특정 플랫폼이나 프레임워크를 위한 애플리케이션을 구축하는 데 사용하는 도구, 라이브러리, 문서의 집합입니다. GoHighLevel은 사용자 정의 앱과 API 통합을 용이하게 하는 SDK를 제공합니다.
* **인증 헤더(Authorization Header)**: 인증 헤더는 액세스 토큰과 같은 인증 자격 증명을 API 요청에 포함하는 HTTP 헤더입니다. 일반적으로 "Authorization: Bearer {access\_token}" 형식을 취합니다. 인증 헤더 이해하기
* **API 키(API Key)**: API 키는 개발자에게 API 액세스 권한을 부여하는 고유 식별자나 코드입니다. API 요청을 할 때 인증의 한 형태로 작용합니다.
* **콜백 URL(Callback URL)**: 콜백 URL은 앱이 콜백이나 응답을 받을 것으로 예상하는 곳입니다. 개발자 마켓플레이스 맥락에서 콜백 URL은 OAuth 프로세스 중 사용자가 권한을 부여한 후 인증 코드나 액세스 토큰을 받는 엔드포인트입니다. 콜백 URL에 대해 자세히 알아보기
* **JSON (JavaScript Object Notation)**: JSON은 사람이 읽고 쓰기 쉽고 기계가 파싱하고 생성하기 쉬운 가벼운 데이터 교환 형식입니다. API 요청과 응답에서 데이터를 구조화하는 데 일반적으로 사용됩니다. JSON 소개
* **매개변수(Parameters)**: 매개변수는 특정 지침을 제공하거나 원하는 데이터를 필터링하기 위해 API 요청에 포함되는 추가 값입니다. 매개변수는 검색 기준, 정렬 기본 설정 또는 페이지네이션 옵션을 지정하는 데 사용할 수 있습니다. API 매개변수 이해하기
* **페이지네이션(Pagination)**: 페이지네이션은 큰 데이터 세트를 페이지라고 하는 더 작고 관리하기 쉬운 부분으로 나누는 것입니다. API 응답에는 페이지당 항목 수와 총 페이지 수와 같은 페이지네이션 정보가 포함되어 개발자가 데이터를 점진적으로 검색할 수 있게 합니다. API에서 페이지네이션 구현
* **속도 제한(Rate Limiting)**: 속도 제한은 API가 특정 기간 내 클라이언트나 사용자의 요청을 제한하는 메커니즘입니다. API 성능을 유지하고 남용을 방지하는 데 도움이 됩니다.
* **웹훅(Webhooks)**: 웹훅은 특정 이벤트나 트리거가 발생할 때 하나의 애플리케이션에서 다른 애플리케이션으로 보내지는 HTTP 콜백이나 알림입니다. 개발자 마켓플레이스 맥락에서 개발자는 웹훅을 구성하여 새로운 리드나 연락처 정보와 같은 GoHighLevel로부터 실시간 업데이트나 데이터를 받을 수 있습니다.
* **이벤트(Event)**: 이벤트는 애플리케이션이나 시스템 내에서 발생하는 특정 사건이나 작업을 나타냅니다. 웹훅 맥락에서 이벤트는 웹훅 알림 전송을 유발하는 트리거입니다.
* **요청(Request)**: 요청은 클라이언트(예: 애플리케이션)에서 서버(예: API)로 보내져 작업을 시작하거나 데이터를 검색하는 HTTP 메시지입니다. 요청된 URL, 메소드(GET, POST 등), 헤더, 선택적 본문과 같은 정보를 포함합니다. HTTP 요청 메소드
* **응답(Response)**: 응답은 클라이언트의 요청에 대한 회신으로 서버가 클라이언트에게 반환하는 HTTP 메시지입니다. 요청된 데이터를 포함하거나 요청의 상태와 결과를 나타냅니다. HTTP 응답 상태 코드
* **GET**: GET은 서버에서 데이터를 검색하는 데 사용되는 HTTP 메소드입니다. API에서 리소스나 정보를 가져오는 데 일반적으로 사용됩니다. HTTP의 GET 메소드
* **POST**: POST는 서버에 데이터를 제출하는 데 사용되는 HTTP 메소드입니다. 일반적으로 새 리소스를 생성하거나 API에서 처리할 데이터를 보내는 데 사용됩니다. HTTP의 POST 메소드
* **PUT**: PUT은 서버의 기존 데이터를 업데이트하거나 교체하는 데 사용되는 HTTP 메소드입니다. 요청에 제공된 새 데이터로 전체 리소스를 교체합니다. HTTP의 PUT 메소드
* **DELETE**: DELETE는 서버에서 리소스를 제거하거나 삭제하는 데 사용되는 HTTP 메소드입니다. 서버에 지정된 리소스를 삭제하도록 지시합니다. HTTP의 DELETE 메소드
* **프론트엔드 개발(Front-End Development)**: 프론트엔드 개발은 소프트웨어 애플리케이션의 사용자 대면 구성 요소를 구축하는 것을 포함합니다. 일반적으로 개발자가 상호작용적이고 시각적으로 매력적인 인터페이스를 만들기 위해 HTML, CSS, JavaScript를 사용하는 것을 포함합니다.
* **백엔드 개발(Back-End Development)**: 백엔드 개발은 소프트웨어 애플리케이션의 서버 측 구성 요소에 중점을 둡니다. 애플리케이션의 기능을 지원하는 데 필요한 로직, 데이터 저장소, 처리를 구현하는 것을 포함합니다.

## 개발자 마켓플레이스의 OAuth 플로우란?

영상에서 언급된 GitHub 저장소는 여기에서 액세스할 수 있습니다. Postman 도구 GoHighLevel 개발자 마켓플레이스 GoHighLevel 개발자 커뮤니티

개발자 마켓플레이스의 OAuth 플로우는 일반적으로 다음 단계들로 구성됩니다:

**앱 등록**: 개발자는 개발자 마켓플레이스에 애플리케이션을 등록하여 필요한 세부 정보를 제공하고 스코프를 정의합니다. 애플리케이션의 고유 식별자인 클라이언트 ID와 클라이언트 시크릿을 받습니다.

**인증 요청**: 애플리케이션은 사용자를 (일반적으로 브라우저를 통해) 마켓플레이스의 인증 서버로 안내합니다. 인증 요청에는 클라이언트 ID, 요청된 스코프, 그리고 인증 후 사용자가 전송될 애플리케이션 내의 위치인 리디렉트 URL이 포함됩니다.

**사용자 동의**: 사용자가 마켓플레이스에 로그인하고 (스코프에 의해 정의된) 특정 세부 정보에 액세스하려는 애플리케이션의 요청을 검토합니다. 사용자가 동의하면 인증 코드가 쿼리 매개변수로 추가된 제공된 리디렉트 URL로 리디렉션됩니다.

**인증 부여**: 애플리케이션이 인증 코드를 받고 확인합니다. 그런 다음 애플리케이션은 인증 코드, 클라이언트 ID, 클라이언트 시크릿을 포함하여 인증 서버에 POST 요청을 보냅니다.

**액세스 토큰 발급**: 제출된 모든 세부 정보가 정확하고 인증 코드가 유효한 경우, 인증 서버는 애플리케이션에 액세스 토큰을 발급합니다. 이제 애플리케이션은 이 액세스 토큰을 사용하여 앞서 정의된 스코프로 제한된 사용자를 대신하여 API에 요청을 할 수 있습니다.

**API 호출**: 애플리케이션은 API 호출을 할 때 헤더에 액세스 토큰을 포함합니다. 액세스 토큰이 유효하고 필요한 스코프를 가지고 있으면 서버는 요청된 작업을 허용합니다.

**토큰 새로고침**: 액세스 토큰은 수명이 제한되어 있으며 리프레시 토큰(인증 서버에서 제공하는 경우)을 사용하여 주기적으로 새로고침해야 합니다. 애플리케이션은 리프레시 토큰으로 서버에 요청하고, 유효한 경우 새로운 액세스 토큰이 발급됩니다.

OAuth는 애플리케이션이 사용자의 자격 증명을 요구하지 않고 사용자를 대신하여 작업해야 하는 시나리오에서 유용한 위임 프로토콜입니다. 실제 플로우는 마켓플레이스의 구현에 따라 약간 다를 수 있지만, 기본 원칙은 동일합니다.

## PKCE를 사용한 OAuth 2.0 (Proof Key for Code Exchange)

HighLevel 마켓플레이스는 외부 인증을 위한 PKCE를 사용한 OAuth 2.0도 지원합니다. 통합이 공용 클라이언트(예: 브라우저 기반 또는 모바일 앱)를 사용하거나 OAuth 공급자가 PKCE를 요구하는 경우 PKCE를 활성화하세요.

PKCE가 활성화되면 인증 요청에는 `code_challenge`와 `code_challenge_method` (`S256`)가 포함되고, 토큰 요청에는 일치하는 `code_verifier`가 포함됩니다.

마켓플레이스의 구성 세부사항은 다음을 참조하세요:

[https://marketplace.gohighlevel.com/docs/oauth/ExternalAuthentication/index.html](/hyperclass-docs/developer/how-to-get-started-with-the-developer-s-marketplace.md)

**사용 사례:**

* **연락처 관리**: 연락처 관리 API를 사용하여 연락처를 생성, 업데이트, 검색, 삭제하여 효율적인 고객 관계 관리를 가능하게 합니다.
* **대화 관리**: 대화 API를 구현하여 대화를 검색, 업데이트, 삭제하여 간소화된 고객 커뮤니케이션을 허용합니다.
* **메시지 자동화**: 메시징 API를 활용하여 자동화된 이메일과 SMS 메시지를 발송하고 예약하여 고객 참여와 리드 육성을 향상시킵니다.
* **폼 제출**: 폼 API를 구현하여 폼 제출을 캡처하고 관리하여 리드 생성과 데이터 수집을 가능하게 합니다.
* **링크 관리**: 링크 API를 사용하여 링크를 생성, 업데이트, 삭제하여 URL 링크의 효과적인 추적과 관리를 허용합니다.
* **로케이션 태깅**: 로케이션 태그 API를 활용하여 다양한 로케이션에 태그를 할당하고 관리하여 체계적인 분류와 필터링을 용이하게 합니다.
* **커스텀 필드 관리**: 커스텀 필드 API를 구현하여 커스텀 필드를 생성, 업데이트, 삭제하여 유연한 데이터 조직과 사용자 정의를 가능하게 합니다.
* **커스텀 값 관리**: 커스텀 값 API를 사용하여 연락처와 연관된 커스텀 값을 생성, 업데이트, 삭제하여 데이터 개인화를 향상시킵니다.
* **템플릿 관리**: 이메일과 SMS 템플릿 API를 활용하여 템플릿을 생성, 검색, 업데이트하여 일관되고 효율적인 메시징을 용이하게 합니다.
* **기회 관리**: 기회 API를 활용하여 기회를 생성, 업데이트, 삭제하여 효과적인 영업 파이프라인 관리를 가능하게 합니다.
* **노트 생성**: 노트 생성 API를 구현하여 고객 프로필에 노트를 추가하여 쉬운 문서화와 정보 공유를 용이하게 합니다.
* **할 일 관리**: 할 일 API를 사용하여 할 일을 생성, 업데이트, 삭제하여 효율적인 작업 추적과 워크플로우 관리를 가능하게 합니다.
* **예약 스케줄링**: 예약 API를 활용하여 예약을 생성하고 업데이트하여 쉬운 스케줄링과 캘린더 관리를 용이하게 합니다.
* **주문 처리**: 주문 API를 활용하여 고객 주문을 생성, 업데이트, 관리하여 주문 처리 프로세스를 간소화합니다.
* **고객 관리**: 고객 API를 구현하여 고객 프로필을 생성, 업데이트, 삭제하여 포괄적인 고


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hyperclass.gitbook.io/hyperclass-docs/developer/how-to-get-started-with-the-developer-s-marketplace.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.