콘텐츠로 이동
EasterAdEasterAdDocs

페이지네이션과 규약

EasterAd Core API는 엔드포인트에 따라 3가지 목록 응답 패턴을 사용합니다. 대상 엔드포인트의 응답 스키마를 확인하고 적절한 파싱 방식을 적용합니다.

1. 목록 응답 3가지 패턴

섹션 제목: “1. 목록 응답 3가지 패턴”
패턴 유형 응답 JSON 구조 적용 엔드포인트 예시 순회 및 수집 방식
A. 배열 직접 반환 [ { ... }, { ... } ] GET /organization, GET /campaign 단일 호출로 전체 배열을 한 번에 수신합니다.
B. 완료 플래그 객체 { "items": [ ... ], "complete": true } GET .../sdk-key items와 조회 완료 여부인 complete를 함께 확인합니다.
C. 오프셋 페이지네이션 { "history": [ ... ], "total": 137, "limit": 20, "offset": 0 } GET .../balance-history offset을 증가시키며 여러 페이지를 반복 수집합니다.

2. 충전 이력 오프셋 페이지네이션 (/balance-history)

섹션 제목: “2. 충전 이력 오프셋 페이지네이션 (/balance-history)”

지갑 충전 이력 엔드포인트(GET .../balance-history)는 오프셋 기반 페이지네이션 쿼리를 지원합니다.

쿼리 파라미터 규격

섹션 제목: “쿼리 파라미터 규격”
파라미터 타입 기본값 허용 범위 및 설명
limit number 20 한 번에 가져올 항목 수를 1~100 사이의 정수로 입력합니다.
offset number 0 조회 시작 기준점입니다. 0부터 시작하는 건수 인덱스를 입력합니다.
type string (전체) 충전 유형 필터입니다. CHARGE_TYPE_PAID(유상 충전) 또는 CHARGE_TYPE_PROMOTION(무상 프로모션)을 지정합니다. 생략하면 전체를 조회합니다.
startDate string (전체) 조회 시작 일시입니다. ISO 8601 형식으로 입력하며 생략하면 전체를 조회합니다.
endDate string (전체) 조회 종료 일시입니다. ISO 8601 형식으로 입력하며 생략하면 전체를 조회합니다.

전체 이력 수집 알고리즘 예시 (JavaScript)

섹션 제목: “전체 이력 수집 알고리즘 예시 (JavaScript)”
async function fetchAllBalanceHistory(orgId, apiKey) {
    const limit = 100; // 네트워크 호출 최적화를 위해 최대 100 지정
    let offset = 0;
    let allRecords = [];


    while (true) {
        const url = `https://www.easterad.com/api/core/organization/${orgId}/balance-history?limit=${limit}&offset=${offset}`;
        const res = await fetch(url, {
            headers: { 'Authorization': `Bearer ${apiKey}` }
        });
        const data = await res.json();


        allRecords.push(...data.history);


        // 전체 건수(total)에 도달하면 순회 종료
        if (offset + limit >= data.total || data.history.length === 0) {
            break;
        }
        offset += limit;
    }


    return allRecords;
}

3. 공통 필드 및 명명 규칙

섹션 제목: “3. 공통 필드 및 명명 규칙”

EasterAd Core API의 모든 요청 본문과 응답 JSON은 다음 규약을 준수합니다.

금액 필드에는 통화 단위의 백만분의 일(micros)을 나타내는 정수를 JSON 문자열로 전달합니다. 예를 들어 10,000원의 JSON 값은 "10000000000"입니다. JavaScript에서 금액을 계산할 때는 BigInt를 사용합니다.

금액 상한은 int64의 최댓값인 9,223,372,036,854,775,807 micros입니다. 입력값과 계산 결과는 이 범위 이내로 유지합니다.

  • 필드명 케이싱: 모든 JSON 속성 이름에는 lowerCamelCase를 사용합니다. (예: balanceSpentMicros, startAt, activeCampaigns)
  • 리소스 식별자:
    • 시스템 고유 식별자는 _id 또는 id 필드로 표현합니다.
    • 조직·게임·광고 단위·캠페인 ID는 24자리 16진수 문자열입니다. 조직 공용 SDK 키 관리용 ID는 UUID 문자열입니다. (예: 65a123456789abcdef012345)
  • 일시 포맷: 모든 시간 정보는 UTC 기준의 ISO 8601 확장 포맷 문자열입니다. (예: 2026-09-05T09:00:00.000Z)
  • 열거형(Enum) 값: 일반 요청·응답에서는 대문자 스네이크 케이스 문자열을 사용합니다. 403 응답의 authorization.reason과 authorization.condition은 숫자이며, 값의 의미는 권한 및 기능 거절 정보에서 확인합니다.
    • 통화 코드: "CURRENCY_KRW" (원화), "CURRENCY_USD" (달러)
    • 충전 구분: "CHARGE_TYPE_PAID" (유상 결제), "CHARGE_TYPE_PROMOTION" (프로모션 지급)
    • 캠페인 상태: "CAMPAIGN_STATUS_PENDING", "CAMPAIGN_STATUS_STARTING", "CAMPAIGN_STATUS_RUNNING", "CAMPAIGN_STATUS_PAUSING", "CAMPAIGN_STATUS_PAUSED", "CAMPAIGN_STATUS_TERMINATING", "CAMPAIGN_STATUS_TERMINATED"
  • 수치 타입: 금액을 나타내는 ...Micros 필드는 위 규칙에 따라 정수 문자열로 전달합니다. 그 밖의 수치는 각 필드의 스키마에 지정된 타입을 따릅니다.

다음 단계

섹션 제목: “다음 단계”