자동화 레시피

EasterAd Core API를 활용하여 사내 시스템과 연동할 때 가장 널리 쓰이는 5대 실무 자동화 레시피입니다. 모든 예제는 사전에 발급된 API 키 환경 변수($KEY)와 대상 조직의 24자리 ID($ORG)를 기반으로 작성되었습니다.

API 권한과 403 오류 주의

각 엔드포인트를 호출하려면 조직에 해당 기능(과금, 캠페인 등)이 활성화되어 있어야 하며, API 키에 연결된 역할에 필요 권한이 부여되어 있어야 합니다. 권한이 부족하면 403 Forbidden, 조직에 기능이 없으면 404 NotFound가 반환됩니다.

---

1. 광고주 지갑 잔액 모니터링 및 저잔액 알림

광고주의 가용 잔액을 주기적으로 확인하여 설정한 임계치(예: 100,000원) 미만으로 떨어졌을 때 사내 메신저(Slack, Teams 등)로 충전 알림을 발송하는 파이프라인입니다.

cURL 호출

curl -s -X GET "https://www.easterad.com/api/core/organization/$ORG/balance" \
  -H "Authorization: Bearer $KEY" \
  -H "Accept: application/json"

응답 샘플

{
  "balance": 85000,
  "balanceSpent": 415000,
  "cur": "CURRENCY_KRW"
}

• 핵심 필드: balance (현재 즉시 집행 가능한 가용 예산)
• 필수 전제 조건:
  • 조직 기능: 과금(Billing) 기능 활성화
  • 역할 권한: 잔액 조회 (balance:read) 권한
• 활용 팁: 5분~10분 주기의 Cron 배치로 실행하며, 잔액이 부족하면 충전 가이드에 따라 입금 요청을 진행하도록 자동화할 수 있습니다.

---

2. 충전 이력 수집 및 ERP 회계 대사 (Reconciliation)

ERP 회계 시스템과 EasterAd 지갑 충전 내역을 대사하기 위해 충전 이력 전체를 수집하는 레시피입니다.

cURL 호출 (최대 100건 조회)

curl -s -X GET "https://www.easterad.com/api/core/organization/$ORG/balance-history?limit=100&offset=0" \
  -H "Authorization: Bearer $KEY" \
  -H "Accept: application/json"

응답 샘플

{
  "history": [
    {
      "_id": "65b0123456789abcdef01234",
      "amount": 500000,
      "type": "CHARGED_PAID",
      "memo": "세금계산서 202609-0012 발행 완료",
      "createdAt": "2026-09-01T09:30:00.000Z"
    }
  ],
  "total": 142,
  "limit": 100,
  "offset": 0
}

• 핵심 필드:
  • type: 유상 충전(CHARGED_PAID)과 무상 보너스(CHARGED_PROMOTION)를 구분하여 회계 계정과목 분개에 활용합니다.
  • memo: 운영팀이 입력한 입금 참조 번호 또는 세금계산서 승인 번호가 기록됩니다.
• 필수 전제 조건:
  • 조직 기능: 과금(Billing) 기능 활성화
  • 역할 권한: 잔액 조회 (balance:read) 권한

---

3. 일일 과금 현황 요약 리포트

대시보드 메인 화면의 4대 과금 지표 카드와 동일한 종합 데이터를 조회하여 일일 경영 리포트를 생성하는 레시피입니다.

cURL 호출

curl -s -X GET "https://www.easterad.com/api/core/organization/$ORG/billing" \
  -H "Authorization: Bearer $KEY" \
  -H "Accept: application/json"

응답 샘플

{
  "balance": 1500000,
  "balanceSpent": 8500000,
  "totalSpent": 3200000,
  "campaignsCount": 12,
  "activeCampaigns": 4
}

권한 조합에 따른 데이터 왜곡 주의

/billing 엔드포인트는 복합 집계 API입니다. API 키에 캠페인 목록 조회 권한이 누락된 경우, 오류 대신 campaignsCount, activeCampaigns, totalSpent 필드가 실제 값과 관계없이 0으로 계산되어 반환됩니다. 정확한 재무 집계를 위해서는 반드시 조직 조회, 잔액 조회, 멤버 목록, 캠페인 목록 권한이 모두 포함된 역할을 부여하세요.

---

4. 캠페인 라이브 현황 및 예산 소진율 모니터링

운영 중인 광고 캠페인의 집행 상태를 모니터링하고 배정 예산 대비 소진 속도를 추적하는 레시피입니다.

cURL 호출

curl -s -X GET "https://www.easterad.com/api/core/organization/$ORG/campaign" \
  -H "Authorization: Bearer $KEY" \
  -H "Accept: application/json"

응답 샘플

[
  {
    "_id": "65c9876543210fedcba54321",
    "name": "2026_가을_신작_프로모션",
    "status": "CAMPAIGN_STATUS_RUNNING",
    "budget": 1000000,
    "budgetRemain": 240000,
    "cur": "CURRENCY_KRW",
    "startAt": "2026-09-01T00:00:00.000Z",
    "endAt": "2026-09-30T23:59:59.000Z"
  }
]

• 소진율 계산 공식: $$\text{예산 소진율(%)} = \frac{\text{budget} - \text{budgetRemain}}{\text{budget}} \times 100$$
• 필수 전제 조건:
  • 조직 기능: 캠페인(Campaign) 기능 활성화
  • 역할 권한: 캠페인 목록 조회 (campaign:list) 권한

---

5. 캠페인 상태 변경과 처리 완료 확인

캠페인 일시정지(CAMPAIGN_ACTION_PAUSE), 재개(CAMPAIGN_ACTION_RESTART), 종료(CAMPAIGN_ACTION_TERMINATE) 등의 액션을 요청할 수 있습니다. 일시정지 및 종료 요청의 경우 직전 송출 광고의 노출 처리가 마무리될 때까지 처리 중 상태를 거치므로, 조회를 통해 최종 상태를 확인하는 레시피입니다.

1단계: 상태 변경 요청 (cURL)

curl -s -X PUT "https://www.easterad.com/api/core/organization/$ORG/campaign/$CAMPAIGN_ID/CAMPAIGN_ACTION_PAUSE" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "정기 점검 일시정지"}'

1단계 응답 샘플 (CampaignActionHistory)

{
  "_id": "65d123456789abcdef012345",
  "organizationId": "65a123456789abcdef012345",
  "campaignId": "65c9876543210fedcba54321",
  "action": "CAMPAIGN_ACTION_PAUSE",
  "statusFrom": "CAMPAIGN_STATUS_RUNNING",
  "statusTo": "CAMPAIGN_STATUS_PAUSING",
  "reason": "정기 점검 일시정지",
  "createdAt": "2026-09-05T09:00:00.000Z"
}

• 요청 접수와 처리 중 상태: 상태 변경 API 호출이 성공(200 OK)하면 변경 이력(CampaignActionHistory)이 반환됩니다. 일시정지 요청 직후에는 직전 송출 건의 노출 처리가 마무리될 때까지 statusTo가 처리 중 상태인 CAMPAIGN_STATUS_PAUSING으로 표시됩니다. (종료 요청 시에는 CAMPAIGN_STATUS_TERMINATING)

2단계: 최종 완료 상태 조회 (cURL)

curl -s -X GET "https://www.easterad.com/api/core/organization/$ORG/campaign/$CAMPAIGN_ID" \
  -H "Authorization: Bearer $KEY" \
  -H "Accept: application/json"

2단계 응답 샘플 (Campaign)

{
  "_id": "65c9876543210fedcba54321",
  "name": "2026_가을_신작_프로모션",
  "status": "CAMPAIGN_STATUS_PAUSED",
  "budget": 1000000,
  "budgetRemain": 240000,
  "cur": "CURRENCY_KRW",
  "startAt": "2026-09-01T00:00:00.000Z",
  "endAt": "2026-09-30T23:59:59.000Z"
}

• 기존 송출 건의 처리가 마무리되어 status가 최종 상태인 CAMPAIGN_STATUS_PAUSED(종료 시 CAMPAIGN_STATUS_TERMINATED)로 변경되었는지 확인합니다.
• CAMPAIGN_STATUS_PAUSED 상태로 변경이 완료된 이후에만 캠페인 설정 수정이나 재개가 가능합니다.
• 필수 전제 조건:
  • 조직 기능: 캠페인(Campaign) 기능 활성화
  • 역할 권한: 일시정지 예제 실행 시 캠페인 일시정지 (campaign:pause) 및 캠페인 조회 (campaign:read) 권한이 필요합니다. (조직 및 캠페인 대상 범위)
  • 참고: 캠페인 재개 시에는 campaign:restart(및 campaign:update), 종료 시에는 campaign:terminate 권한이 각각 필요합니다.

하우스 캠페인 및 크로스 프로모션 API 호출 시 참고

• 하우스 캠페인을 생성할 때는 budget이 필수이며(원화 1원 이상의 양의 정수), 수정 시 budget을 생략하면 기존 예산이 유지됩니다.
• 하우스 캠페인의 ads[].cpm은 생략 시 0으로 설정되므로 실제 노출 경쟁에 반영하려면 송출 단가를 지정해야 합니다.
• 크로스 프로모션은 공유 스키마에 ads[].cpm이 나타나지만 0 또는 생략만 허용됩니다.

---

다음 단계

• 안정성 및 버전 정책: API 하위 호환성 원칙과 스키마 업데이트 규칙을 확인합니다.
• 엔드포인트 상세 레퍼런스: 모든 공개 엔드포인트의 파라미터와 스키마를 확인합니다.