개요

Core API로 게임·캠페인 관리, 지갑 잔액 조회와 충전 이력 수집을 자동화합니다. 서버에서 API 키로 호출합니다.

1. Base URL 및 통신 규약

모든 Core API 요청은 HTTPS 프로토콜로 전송합니다.

Base URL: https://www.easterad.com
엔드포인트 경로 구조: Core API는 /api/core/... 경로로 호출하며, 조직에 속한 리소스는 /api/core/organization/{organizationId}/... 경로를 사용합니다.
데이터 포맷: 일반 요청·응답은 application/json입니다. 동의 전문 조회는 HTML을 반환합니다.
인증 방식: HTTP 표준 Authorization: Bearer <API_KEY> 헤더를 사용합니다.

2. 첫 API 호출하기

API 키를 발급받아 조직 목록과 지갑 잔액을 조회하는 첫 호출 절차는 다음과 같습니다.

flowchart LR
    A["1. API 키 발급 (조회 권한)"] --> B["2. 조직 목록 호출 (인증 확인)"]
    B --> C["3. 지갑 잔액 호출 (비즈니스 연동)"]

1단계: API 키 및 조직 ID 준비

EasterAd 콘솔에 로그인한 뒤 조직 설정 → 멤버 관리 → API 키 탭으로 이동합니다.
조직 조회와 지갑 잔액 조회 권한(organization_balance:read)이 있는 역할을 선택해 API 키를 생성합니다. 잔액을 조회할 조직에는 과금(Billing) 기능이 켜져 있어야 합니다.

발급된 시크릿 키(ea_...)는 생성 시점에 단 1회만 화면에 노출되므로 안전한 곳에 즉시 복사하여 보관합니다.
콘솔의 조직 설정 → 조직 정보에서 24자리 조직 ID를 확인합니다.

2단계: 인증 테스트 (내 조직 목록 조회)

조직 목록 엔드포인트를 호출하여 API 키가 정상 작동하는지 확인합니다.

curl -X GET "https://www.easterad.com/api/core/organization" \
  -H "Authorization: Bearer ea_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_****************" \
  -H "Accept: application/json"

HTTP 200 OK와 함께 속한 조직 목록이 JSON 배열로 반환되면 인증이 완료된 것입니다.

3단계: 비즈니스 데이터 조회 (지갑 잔액 확인)

확인한 조직 ID(organizationId)를 경로에 넣어 잔액 엔드포인트를 호출합니다.

curl -X GET "https://www.easterad.com/api/core/organization/{organizationId}/balance" \
  -H "Authorization: Bearer ea_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx_****************" \
  -H "Accept: application/json"

{
  "balanceMicros": "100000000000",
  "balanceSpentMicros": "250000000000",
  "cur": "CURRENCY_KRW"
}

balanceMicros: 아직 캠페인에 배정하지 않은 지갑 잔액입니다.
balanceSpentMicros: 캠페인에 배정한 금액에서 반환된 잔여 예산을 뺀 값입니다. 실제 광고 소진액과 구분합니다.
cur: 기본 통화 단위입니다 (CURRENCY_KRW 또는 CURRENCY_USD).

금액은 통화의 1/1,000,000 단위 정수 문자열입니다. 예시의 balanceMicros는 100,000원입니다.

3. 작업별 API 안내

Core API 연동에 필요한 세부 가이드는 다음 문서에서 확인합니다.

인증 가이드: Bearer 키 전달과 보안 설정
오류 코드 카탈로그: 표준 에러 응답 구조와 403/409/429 등 상황별 대응법
페이지네이션 및 명명 규약: 3가지 목록 응답 패턴과 ISO 8601/Enum 데이터 규약
요청 제한(Rate Limits): 호출 한도와 재시도 방법
자동화 레시피: 잔액 알림 봇, 충전 이력 회계 대사, 캠페인 소진율 모니터링 스크립트
안정성 및 호환성 정책: 하위 호환성 보장 원칙과 변경 공지 주기
엔드포인트 레퍼런스: 좌측 사이드바의 각 리소스별 상세 스펙 및 요청/응답 스키마를 참조합니다.

소재 업로드 안내

광고 소재는 캠페인 만들기의 콘솔 절차에 따라 등록합니다. API로 자동화할 작업은 좌측 사이드바의 엔드포인트 레퍼런스에서 선택합니다.