# 앱 설치자 세부정보 API란 무엇인가요?

앱 설치자 세부정보 API는 마켓플레이스 개발자가 앱을 설치한 사용자와 정확한 에이전시/하위 계정 컨텍스트, 그리고 브랜딩을 위한 에이전시 화이트라벨 데이터를 식별하는 데 도움을 줍니다. 이를 통해 온보딩을 개인화하고, UI를 에이전시 브랜딩과 일치시키며, 광범위한 회사 수준의 OAuth 범위를 요청하지 않고도 에이전시 소유자와 소통할 수 있습니다. 이는 리텐션을 개선하고, 설정을 가속화하며, 화이트라벨 무결성을 보존합니다.

## 목차

* [앱 설치자 세부정보 API란 무엇인가요?](#앱-설치자-세부정보-api란-무엇인가요)
* [앱 설치자 세부정보의 주요 이점](#앱-설치자-세부정보의-주요-이점)
* [인증 옵션](#인증-옵션)
* [엔드포인트 및 요청 예제](#엔드포인트-및-요청-예제)
* [응답 스키마 (필드 참조)](#응답-스키마-필드-참조)
* [화이트라벨 데이터 사용 가이드라인](#화이트라벨-데이터-사용-가이드라인)
* [속도 제한 및 캐싱](#속도-제한-및-캐싱)
* [오류 처리](#오류-처리)
* [버전 관리 및 가용성](#버전-관리-및-가용성)
* [앱에서 앱 설치자 세부정보를 설정하는 방법](#앱에서-앱-설치자-세부정보를-설정하는-방법)
* [자주 묻는 질문](#자주-묻는-질문)

## 앱 설치자 세부정보 API란 무엇인가요?

앱 설치자 세부정보 API는 마켓플레이스 앱을 설치한 사용자와 앱이 설치된 정확한 컨텍스트(하위 계정 및 에이전시)에 대한 검증된 정보를 반환합니다. 또한 에이전시 프로필과 화이트라벨 데이터를 제공하여 광범위한 회사 수준의 OAuth 범위를 요청하지 않고도 온보딩, 브랜딩, 커뮤니케이션을 개인화할 수 있습니다.

이 엔드포인트는 설치자 식별, 화이트라벨 경계 준수, 에이전시 및 하위 계정에 맞춘 앱 경험 제공이 필요한 마켓플레이스 개발자를 위해 설계되었습니다.

## 앱 설치자 세부정보의 주요 이점

설치자 컨텍스트를 가져온 후 자동화할 내용을 위한 체크리스트로 이러한 이점을 활용하세요.

* **신원 및 컨텍스트**: 설치자와 앱이 위치한 곳(하위 계정 및 에이전시)을 식별합니다.
* **화이트라벨 인식**: 앱의 브랜딩을 조정하기 위한 에이전시 화이트라벨 필드를 제공합니다.
* **범위 축소**: 에이전시 세부정보를 읽기 위한 광범위한 회사 수준의 OAuth 범위 필요성을 제거합니다.
* **개인화된 온보딩**: 에이전시별 환영 플로우, 콘텐츠, 가격을 가능하게 합니다.
* **소유자 아웃리치**: 리텐션을 높이는 직접적인 관계 구축을 위한 에이전시 소유자 세부정보를 포함합니다.
* **프라이버시 바이 디자인**: 하위 계정이 상위 에이전시 브랜딩에 노출되지 않도록 화이트라벨 무결성을 지원합니다.

## 인증 옵션

올바른 토큰 선택은 API가 해결하는 컨텍스트를 결정합니다. 이 섹션에서는 사용할 토큰과 응답에 미치는 영향을 설명하여 최소 권한을 유지하고 마켓플레이스 정책과 일치하도록 합니다.

* **지원되는 토큰**: Agency Token(에이전시 토큰) 또는 Sub-account Token(하위 계정 토큰)
* 동작 가이드라인:
  * Agency Token으로 호출하면 설치자 + 에이전시 컨텍스트를 해결하고 설치가 발생한 하위 계정을 표시할 수 있습니다(해당하는 경우).
  * Sub-account Token으로 호출하면 설치자 + 현재 하위 계정의 에이전시 컨텍스트를 해결합니다.
* **헤더 (예제)**:
  * **Authorization**: Bearer {YOUR\_TOKEN}
  * **Content-Type**: application/json
* **최소 권한 팁**: 현재 런타임 컨텍스트의 토큰을 우선시하세요(예: 하위 계정 워크플로우는 Sub-account Token을 사용해야 함).

참고: 정확한 권한 요구사항은 마켓플레이스 표준을 따릅니다. 설치 컨텍스트를 읽을 수 있는 최소 토큰을 사용하고, 브랜딩 획득만을 위해 광범위한 에이전시 범위를 요청하지 마세요.

## 엔드포인트 및 요청 예제

구체적인 예제는 통합 시간을 단축시킵니다. 공식 API 참조에서 확인 후 실제 베이스 URL과 엔드포인트 경로로 아래 플레이스홀더를 교체하세요.

* **HTTP 메서드**: GET
* **엔드포인트 경로**: /marketplace/app-installer/details (플레이스홀더—정확한 경로는 [여기](/hyperclass-docs/integrations/highlevel-api.md)의 공식 API 문서에서 확인하세요)

**cURL**

```
curl -X GET \
  "{BASE_URL}/marketplace/app-installer/details" \
  -H "Authorization: Bearer {AGENCY_OR_SUB_ACCOUNT_TOKEN}" \
  -H "Content-Type: application/json"
```

## 응답 스키마 (필드 참조)

명확한 필드별 참조를 통해 개발자가 확신을 가지고 데이터를 시스템에 매핑할 수 있습니다. nullable 필드와 선택적 화이트라벨 속성을 방어적으로 처리하세요.

주요 필드(대표적; 공식 문서에서 이름/유형 확인):

* **installer.userId (string)** — 설치를 수행한 사용자의 고유 ID
* **installer.name (string)** — 사람이 읽을 수 있는 이름
* **installer.email (string)** — 협업 및 계정 연결을 위한 연락처
* **installationContext.subAccountId (string|null)** — 앱이 설치된 하위 계정
* **installationContext.agencyId (string)** — 부모 에이전시 ID
* **agency.companyName (string)** — 에이전시 법적/브랜드 이름
* **agency.companyEmail (string)** — 일반 연락처 이메일
* **agency.ownerName (string)** — 주요 소유자/관리자 이름
* **whiteLabel.brandName (string)** — 화이트라벨 브랜드
* **whiteLabel.supportEmail (string|null)** — 브랜드 커뮤니케이션을 위한 지원 메일박스
* **whiteLabel.supportUrl (string|null)** — 헬프 센터 또는 티켓팅 URL
* **whiteLabel.primaryDomain (string|null)** — 브랜드 앱/도메인
* **whiteLabel.logoUrl (string|null)** — UI 테마용 브랜드 로고
* **whiteLabel.faviconUrl (string|null)** — 브라우저 브랜딩용 파비콘

## 화이트라벨 데이터 사용 가이드라인

화이트라벨 무결성은 HighLevel 구현의 핵심 기대사항입니다. 최종 클라이언트에게 상위 신원을 노출하지 않고 UX를 향상시키기 위해 에이전시 브랜딩을 신중하게 사용하세요.

* `whiteLabel.brandName`, `logoUrl`, `primaryDomain`을 사용하여 에이전시 사용자를 위한 앱 UI를 테마화하세요.
* 명시적으로 의도된 경우가 아니라면 하위 계정 최종 클라이언트에게 에이전시 신원을 누출하지 마세요.
* API 호출을 줄이고 업데이트를 처리하기 위해 짧은 TTL(예: 15-60분)로 브랜딩 필드의 서버 측 캐싱을 우선시하세요.
* 브랜딩이 변경되면 새로운 `logoUrl`이나 `brandName`이 감지될 때 캐시를 무효화하세요.

## 속도 제한 및 캐싱

제한 및 캐싱의 사전 처리는 앱을 탄력적으로 유지합니다. 임시 오류에 대해 지수 백오프를 사용하고 전략적 캐싱으로 중복 호출을 줄이세요.

* **권장 캐싱**: 토큰/컨텍스트별로 설치자 + 화이트라벨 결과를 캐시하고, 로그인/세션 시작 시 새로고침하세요.
* **백오프 전략**: 429/5xx에서 지터와 함께 백오프하고 제한된 횟수만큼 재시도하세요.
* **클라이언트 위생**: 모든 페이지에서 이 엔드포인트를 호출하지 마세요; 세션당 한 번 또는 컨텍스트가 변경될 때 가져오세요.

## 오류 처리

오류 상태를 예상하면 개발자 생산성과 사용자 신뢰가 향상됩니다. API 오류를 UI의 실행 가능한 가이드에 매핑하세요.

| HTTP | 가능한 원인             | 예제 오류 본문                     | 권장 조치                        |
| ---- | ------------------ | ---------------------------- | ---------------------------- |
| 401  | 누락/무효 토큰           | { "error": "unauthorized" }  | 토큰 새로고침; 헤더 형식 확인            |
| 403  | 토큰이 컨텍스트에 대한 권한 부족 | { "error": "forbidden" }     | 적절한 Agency/Sub-account 토큰 사용 |
| 404  | 컨텍스트에 앱이 설치되지 않음   | { "error": "not\_found" }    | 설치 프롬프트 또는 유효한 계정으로 전환       |
| 429  | 속도 제한 초과           | { "error": "rate\_limited" } | 백오프 + 캐싱 적용                  |
| 5xx  | 임시 서비스 문제          | { "error": "server\_error" } | 지수 백오프와 함께 재시도               |

## 버전 관리 및 가용성

성숙도와 롤아웃 상태를 아는 것은 팀이 롤아웃을 계획하고 업그레이드 중 예기치 않은 상황을 피하는 데 도움이 됩니다.

* **상태**: 새로운 마켓플레이스 API 엔드포인트
* **호환성**: Agency 또는 Sub-account 토큰으로 호출하는 마켓플레이스 앱을 위한 것
* **버전 관리**: 게시된 후 조직의 API 버전 헤더 또는 URL 세그먼트를 따르세요(예: Accept-Version, /v{n} 경로). API 참조의 공식 값으로 플레이스홀더를 교체하세요.

## 앱에서 앱 설치자 세부정보를 설정하는 방법

간단하고 반복 가능한 설정 시퀀스는 팀이 엔드포인트를 빠르고 안전하게 통합할 수 있게 합니다. 프로덕션으로 이동하기 전에 개발 환경에서 이 단계들을 완료하세요.

**1단계: 토큰 확인**

* 테스트용 Agency Token과 Sub-account Token을 생성하세요.
* 안전하게 저장하세요(vault 또는 secrets manager); 소스 제어에 커밋하지 마세요.

**2단계: 요청 추가**

* `{BASE_URL}/marketplace/app-installer/details`(플레이스홀더 경로)에 대한 GET 호출을 구현하세요.
* `Authorization: Bearer {TOKEN}`을 포함하세요.

**3단계: 응답 매핑**

* `installationContext`와 `agency` ID를 유지하고; `whiteLabel` 필드를 캐시하세요.
* `whiteLabel`에서 UI 테마를 가져오고 환영 문구를 위해 설치자 이름을 사용하세요.

**4단계: 오류 + 재시도 처리**

* 401/403/404/429 핸들러와 지수 백오프를 구현하세요.
* 내부 사용자에게 실행 가능한 메시지를 표시하고; 최종 클라이언트에게 원시 JSON을 노출하지 마세요.

**5단계: 화이트라벨 무결성 검증**

* 에이전시 브랜딩이 하위 계정의 의도하지 않은 대상에게 노출되지 않는지 확인하세요.

**6단계: 관찰 가능성과 함께 배포**

* 호출 성공률, 지연 시간, 캐시 적중률에 대한 메트릭을 추가하세요.

## 자주 묻는 질문

**Q1. Agency 토큰과 Sub-account 토큰 중 어떤 것을 사용해야 하나요?** 현재 실행 컨텍스트와 일치하는 토큰을 사용하세요. Agency 토큰은 에이전시 + 설치자를 해결하고 하위 계정 설치를 참조할 수 있습니다; Sub-account 토큰은 현재 위치의 에이전시 컨텍스트를 해결합니다.

**Q2. 이 엔드포인트는 회사 수준의 OAuth 범위가 필요한가요?** 아니요. 주요 장점은 에이전시 세부정보를 읽기 위해 광범위한 회사 수준의 범위를 피하는 것입니다.

**Q3. 일반적으로 어떤 화이트라벨 필드가 반환되나요?** 브랜드 이름, 지원 이메일/URL, 브랜드 도메인, 로고 및 파비콘과 같은 선택적 자산. 필드를 선택적으로 처리하고 짧은 TTL로 캐시하세요.

**Q4. 응답을 캐시할 수 있나요?** 예. 토큰/컨텍스트별로 캐시하고 세션이 시작될 때나 브랜딩 변경을 감지할 때 새로고침하세요.

**Q5. 설치자가 에이전시를 떠나면 어떻게 되나요?** 안정적인 에이전시/하위 계정 컨텍스트를 기대하세요. 설치자 기록은 과거 사용자를 반영할 수 있습니다; null/unknown을 우아하게 처리하세요.

**Q6. 페이지네이션이 관련되나요?** 아니요. 이 엔드포인트는 현재 토큰에 대한 단일 설치자 컨텍스트 페이로드를 반환합니다.

**Q7. 속도 제한을 어떻게 처리해야 하나요?** 429 응답에 대해 지터와 함께 지수 백오프를 사용하고 캐싱을 통해 호출 빈도를 줄이세요.

**Q8. 에이전시 소유자에게 직접 메시지를 보낼 수 있나요?** 예—관계 구축을 위해 소유자 세부정보가 반환됩니다. 신중하게 사용하고 개인정보 보호정책을 따르세요.

***

*원문 최종 수정: Wed, 18 Feb, 2026 at 6:05 AM* *Hyperclass 사용 가이드 — hyperclass.ai*


---

# 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/app-marketplace/how-to-use-the-ai-agent-marketplace-templates-for-conversation-ai-and-voice-ai-a/what-is-the-app-installer-details-api.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.