콘텐츠로 이동
EasterAdEasterAdDocs

페이지네이션과 규약

EasterAd Core API는 일관성 있는 개발자 경험을 제공하기 위해 표준화된 데이터 직렬화 규칙과 명명 규약을 따릅니다. 엔드포인트의 데이터 특성에 따라 3가지 목록 응답 패턴을 사용하므로, 클라이언트는 대상 엔드포인트의 스키마를 확인하고 적절한 파싱 방식을 적용해야 합니다.

1. 목록 응답 3가지 패턴

섹션 제목: “1. 목록 응답 3가지 패턴”

Core API의 목록(List) 엔드포인트는 데이터 양과 조회 특성에 따라 3가지 형태로 반환됩니다.

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

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

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

지갑 충전 이력 엔드포인트는 회계 데이터의 무결성과 대용량 조회를 지원하기 위해 오프셋 기반 페이지네이션 쿼리를 지원합니다.

쿼리 파라미터 규격

섹션 제목: “쿼리 파라미터 규격”
파라미터 타입 기본값 허용 범위 및 설명
limit number 20 한 번에 가져올 최대 항목 수 (최대 100)
offset number 0 조회 시작 기준점 (0부터 시작하는 건수 인덱스)
type string (전체) 충전 유형 필터 (CHARGED_PAID: 유상 충전, CHARGED_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은 아래의 통일된 규약을 준수합니다.

  • 필드명 케이싱: 모든 JSON 속성 이름은 lowerCamelCase를 사용합니다. (예: balanceSpent, startAt, activeCampaigns)
  • 리소스 식별자:
    • 시스템 고유 식별자는 _id 또는 id 필드로 표현됩니다.
    • 모든 리소스 ID는 24자리 16진수 문자열입니다. (예: 65a123456789abcdef012345)
  • 일시 포맷: 모든 시간 정보는 UTC 기준의 ISO 8601 확장 포맷 문자열입니다. (예: 2026-09-05T09:00:00.000Z)
  • 열거형(Enum) 값: Enum 속성은 정수 숫자가 아닌 대문자 스네이크 케이스 문자열을 사용합니다.
    • 통화 코드: "CURRENCY_KRW" (원화), "CURRENCY_USD" (달러)
    • 충전 구분: "CHARGED_PAID" (유상 결제), "CHARGED_PROMOTION" (프로모션 지급)
    • 캠페인 상태: "CAMPAIGN_STATUS_PENDING", "CAMPAIGN_STATUS_STARTING", "CAMPAIGN_STATUS_RUNNING", "CAMPAIGN_STATUS_PAUSING", "CAMPAIGN_STATUS_PAUSED", "CAMPAIGN_STATUS_TERMINATING", "CAMPAIGN_STATUS_TERMINATED"
  • 금액 및 수치: 통화 금액과 카운트는 문자열이 아닌 Number 정수 또는 부동소수점으로 전달됩니다.

4. 소재 접수와 준비 상태

섹션 제목: “4. 소재 접수와 준비 상태”

POST /api/core/organization/{organizationId}/ad/assets는 multipart/form-data로 파일 하나(file)와 광고 형식(productType)을 받습니다. productType은 이 업로드 예외에서만 숫자를 문자열로 전송합니다: 디스플레이 이미지 1, H5 전면 2, H5 리워드 3, H5 배너 4.

HTTP 202는 접수 성공입니다. assetId, status, statusPath를 저장하고 상태 경로를 조회하세요. QUEUED·PROCESSING이면 기다리고, READY이면 result의 배포 URL·크기·형식·용량과 영상 길이를 사용합니다. 준비 전에는 원본이나 배포 URL이 노출되지 않습니다.

FAILED이면 errorReason, errorMessage, retryable을 확인합니다. retryable: true일 때 POST .../ad/assets/{assetId}/retry로 같은 원본을 재사용할 수 있습니다. DELETE .../ad/assets/{assetId}는 소재를 사용 불가로 만들며 저장 파일 정리는 비동기로 이어집니다.

캠페인 요청의 각 이미지·영상에는 assetId 또는 기존 url 중 하나만 넣습니다. assetId는 동일 조직에서 해당 광고 형식으로 준비된 소재여야 합니다. 준비 전 연결은 HTTP 409와 reason: CREATIVE_NOT_READY로 거절됩니다.

다음 단계

섹션 제목: “다음 단계”