콘텐츠로 이동
EasterAdEasterAdDocs

자동화 레시피

EasterAd Core API를 활용하여 사내 시스템과 연동하는 실무 자동화 레시피입니다. 모든 예제는 사전에 발급된 API 키 환경 변수($KEY)와 대상 조직의 24자리 ID($ORG)를 사용합니다.

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

섹션 제목: “1. 광고주 지갑 잔액 모니터링 및 저잔액 알림”

광고주의 가용 잔액을 주기적으로 확인하여 지정한 임계치(예: 100,000원) 미만으로 내려가면 사내 메신저(Slack, Teams 등)로 충전 알림을 발송하도록 연동합니다.

  • 선행 조건:
    • 조직 기능: 과금(Billing) 기능 활성화
    • 역할 권한: 잔액 조회(organization_balance:read) 권한

cURL 호출

섹션 제목: “cURL 호출”
터미널 창
curl -s -X GET "https://www.easterad.com/api/core/organization/$ORG/balance" \
  -H "Authorization: Bearer $KEY" \
  -H "Accept: application/json"

응답 샘플

섹션 제목: “응답 샘플”
{
  "balanceMicros": "85000000000",
  "balanceSpentMicros": "415000000000",
  "cur": "CURRENCY_KRW"
}
  • 핵심 필드: balanceMicros (새 캠페인에 배정할 수 있는 가용 예산). 금액 단위 규약에 따라 통화 단위로 환산합니다.
  • 충전 준비에 필요한 시간을 고려해 조회 주기와 알림 기준을 정합니다. 예를 들어 5~10분마다 잔액을 조회해 충전 알림을 보낼 수 있습니다. 충전은 지갑 충전 절차를 따릅니다.

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

섹션 제목: “2. 충전 이력 수집 및 ERP 회계 대사 (Reconciliation)”

ERP 회계 시스템과 대사할 지갑 충전 이력을 조회합니다. 다음 예제로 첫 100건을 조회한 뒤 전체 이력 수집 예제에 따라 나머지를 수집합니다.

  • 선행 조건:
    • 조직 기능: 과금(Billing) 기능 활성화
    • 역할 권한: 잔액 조회(organization_balance:read) 권한

cURL 호출 (최대 100건 조회)

섹션 제목: “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",
      "creditedAmountMicros": "500000000000",
      "serviceFeeMicros": "50000000000",
      "paidAmountMicros": "550000000000",
      "currency": "CURRENCY_KRW",
      "type": "CHARGE_TYPE_PAID",
      "memo": "세금계산서 202609-0012 발행 완료",
      "createdAt": "2026-09-01T09:30:00.000Z"
    }
  ],
  "total": 142,
  "limit": 100,
  "offset": 0
}
  • 핵심 필드:
    • type: 유상 충전(CHARGE_TYPE_PAID)과 무상 보너스(CHARGE_TYPE_PROMOTION)를 구분하여 회계 계정과목 분개에 활용합니다.
    • memo: 입금 참조 번호 또는 세금계산서 승인 번호가 기록됩니다.

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

섹션 제목: “3. 일일 과금 현황 요약 리포트”

조직의 종합 과금 데이터를 조회하여 일일 경영 리포트를 생성합니다.

cURL 호출

섹션 제목: “cURL 호출”
터미널 창
curl -s -X GET "https://www.easterad.com/api/core/organization/$ORG/billing" \
  -H "Authorization: Bearer $KEY" \
  -H "Accept: application/json"

응답 샘플

섹션 제목: “응답 샘플”
{
  "balanceMicros": "1500000000000",
  "balanceSpentMicros": "8500000000000",
  "totalSpentMicros": "3200000000000",
  "campaignsCount": 12,
  "activeCampaigns": 4
}

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

섹션 제목: “4. 캠페인 라이브 현황 및 예산 소진율 모니터링”

운영 중인 광고 캠페인의 집행 상태를 모니터링하고 배정 예산 대비 소진율을 추적합니다.

  • 선행 조건:
    • 조직 기능: 캠페인(Campaign) 기능 활성화
    • 역할 권한: 캠페인 목록 조회(campaign:list) 권한

cURL 호출

섹션 제목: “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",
    "budgetMicros": "1000000000000",
    "budgetRemainMicros": "240000000000",
    "cur": "CURRENCY_KRW",
    "startAt": "2026-09-01T00:00:00.000Z",
    "endAt": "2026-09-30T23:59:59.000Z"
  }
]
  • 운영 중인 캠페인의 소진율 계산: 잔여 예산 반환 전 캠페인에 적용합니다. 종료·반환 후 실제 광고비는 과금 지표에서 확인합니다. 예산 소진율(%) = (budgetMicros − budgetRemainMicros) ÷ budgetMicros × 100

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

섹션 제목: “5. 캠페인 상태 변경과 처리 완료 확인”

캠페인 일시정지(CAMPAIGN_ACTION_PAUSE), 재개(CAMPAIGN_ACTION_RESTART), 종료(CAMPAIGN_ACTION_TERMINATE) 등의 액션을 요청한 뒤 캠페인을 조회해 최종 상태를 확인합니다.

  • 선행 조건:
    • 조직 기능: 캠페인(Campaign) 기능 활성화
    • 역할 권한: 상태 확인에는 캠페인 조회(campaign:read) 권한(조직 및 캠페인 대상 범위)이 필요합니다. 실행할 작업에 따라 일시정지(campaign:pause), 재개(campaign:restart 및 campaign:update), 종료(campaign:terminate) 권한도 준비합니다. 권한 추가는 조직 관리자에게 요청합니다.

대상 캠페인 ID를 환경 변수 $CAMPAIGN_ID에 설정합니다.

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

섹션 제목: “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)

섹션 제목: “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 호출이 성공하면 변경 이력(CampaignActionHistory)이 반환됩니다. 일시정지 요청 직후에는 statusTo가 CAMPAIGN_STATUS_PAUSING으로 표시됩니다. 종료 요청 시에는 CAMPAIGN_STATUS_TERMINATING으로 표시됩니다.

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

섹션 제목: “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)

섹션 제목: “2단계 응답 샘플 (Campaign)”
{
  "_id": "65c9876543210fedcba54321",
  "name": "2026_가을_신작_프로모션",
  "status": "CAMPAIGN_STATUS_PAUSED",
  "budgetMicros": "1000000000000",
  "budgetRemainMicros": "240000000000",
  "cur": "CURRENCY_KRW",
  "startAt": "2026-09-01T00:00:00.000Z",
  "endAt": "2026-09-30T23:59:59.000Z"
}
  1. status가 CAMPAIGN_STATUS_PAUSED(종료 시 CAMPAIGN_STATUS_TERMINATED)로 변경되었는지 확인합니다.
  2. CAMPAIGN_STATUS_PAUSED 상태로 변경이 완료된 뒤에만 캠페인 설정을 수정하거나 재개할 수 있습니다. 캠페인 상태와 편집 가능 여부는 캠페인 만들기를 참고합니다.

다음 단계

섹션 제목: “다음 단계”