API Reference

개요

ad.ded에서 제공하는 API를 연동하는데 필요한 인증, 응답 형식, 에러 처리 등의 기본적인 가이드를 설명합니다.

인증

API 인증은 OAuth2 기반으로 Basic과 Bearer 방식을 제공합니다.

Bearer 정적 키 (권장)

Authorization: Bearer <publisher_secret> 또는 <provider_secret>. secret은 1회 발급 이후 만료되지 않으며 관리자가 수동으로 만료시킬 수 있습니다.

bash

curl -H "Authorization: Bearer {publisher_secret}" \
     https://added.blomics.net/api/v1/postbacks?limit=10

Basic (호환)

Authorization: Basic base64(publisher_id:publisher_secret). secret이 만료되지 않기에 동일하게 만료없이 사용 가능합니다.

bash

curl -u "{publisher_id}:{publisher_secret}" \
     https://added.blomics.net/api/v1/postbacks?limit=10

엔드포인트

ad.ded API 는 개발(dev) 과 운영(prod) 두 가지 환경을 제공합니다. 통합·검증 단계에서는 개발 환경을, 실서비스 트래픽은 운영 환경을 사용합니다.

환경별 도메인

개발(dev) — https://added-dev.blomics.net
운영(prod) — https://added.blomics.net

접근 제어

방화벽이 적용된 환경에서는 ad.ded 와의 통신에 대해 Inbound · Outbound 방화벽 정책을 사전에 등록해야 합니다. Blomics 측에서는 별도의 방화벽 정책을 적용하지 않으므로, 네트워크 또는 보안 담당자에게 등록을 요청해주세요.

환경별 IP

들어오는 트래픽(Inbound) 과 나가는 트래픽(Outbound) 의 IP 가 분리되어 있습니다. 포트는 443 (HTTPS) 만 지원합니다. 매체사·콘텐츠사 측 방화벽 정책은 아래 IP 들로 등록해주세요.

개발

Server IP — 43.155.169.149. ad.ded 서버의 공인 진입 IP. 매체사·콘텐츠사 Outbound 방화벽에 등록.
NAT IP — 119.28.160.11. ad.ded → 매체사·콘텐츠사 호출 시 출발 IP. 매체사·콘텐츠사 Inbound 방화벽에 등록.

운영

Server IP — <미정>. 매체사·콘텐츠사 Outbound 방화벽에 등록.
NAT IP — <미정>. 매체사·콘텐츠사 Inbound 방화벽에 등록.

응답 형식

응답은 성공과 에러 두 가지 형식으로 구분됩니다. HTTP 상태 코드로 성공·에러를 판단하고, 본문 형식은 아래와 같이 다릅니다.

성공

HTTP 200 · 201 응답의 본문은 엔드포인트별 데이터 객체를 그대로 반환합니다. 별도의 envelope 으로 감싸지 않습니다. HTTP 204 는 본문이 없습니다.

json

// HTTP 200 — 콘텐츠 상세 조회 응답 예시
{
  "content_id": "0193a1b2-3c4d-5e6f-7890-abcdef012345",
  "name": "퀴즈 챔피언",
  "status": "ACTIVE"
}

에러

HTTP 4xx · 499 · 5xx 응답의 본문은 { code, message, data } 표준 envelope 을 사용합니다.

code — 에러 종류 식별 코드 (예: INVALID_PARAM).
message — 사람이 읽을 수 있는 에러 메시지.
data — 에러 부가 정보 객체 또는 null.

json

// HTTP 400 — 클라이언트 오류 (data 에 검증 실패 항목 포함)
{
  "code": "INVALID_PARAM",
  "message": "validation failed",
  "data": [
    { "name": "limit",  "validate": "max",      "type": "integer" },
    { "name": "offset", "validate": "min",      "type": "integer" },
    { "name": "status", "validate": "in",       "type": "enum"    }
  ]
}

// HTTP 401 — 인증 실패
{ "code": "UNAUTHORIZED", "message": "invalid secret", "data": null }

// HTTP 499 — 비즈니스 룰 거부
{ "code": "DAILY_LIMIT_EXCEEDED", "message": "daily limit reached", "data": null }

// HTTP 500 — 서버 오류
{ "code": "INTERNAL_ERROR", "message": "unexpected error", "data": null }

에러 코드

200 / 201 / 204 — 성공
400 INVALID_PARAM — payload 형식 오류
401 UNAUTHORIZED / HMAC_MISMATCH — 인증 실패
403 FORBIDDEN — 권한 부족
404 NOT_FOUND — 리소스 없음 (소유권 위반 시 404 로 은닉)
409 ALREADY_EXISTS / DUPLICATE_POSTBACK — 중복
429 TOO_MANY_REQUESTS — rate limit
499 — 비즈니스 룰 거부
- 한도 초과 — DAILY_LIMIT_EXCEEDED · USER_LIMIT_EXCEEDED · TOTAL_LIMIT_EXCEEDED
- 캠페인 상태 — CAMPAIGN_EXPIRED · CAMPAIGN_PAUSED
500 INTERNAL_ERROR — 서버 오류