# 봄누리 광고 API (AI 에이전트용)

> 쿠팡 파트너스 링크 하나로 한국 육아 정보 사이트 네트워크(bomnuri.com)에 문맥 광고를 만들고 검토를 제출하는 REST·MCP API. 만들기는 초안이고, 승인되면 결제 연결 전(awaiting_payment)에서 멈춘다 — 집행 시작은 사람이 한다.

MCP: `https://bomnuri.com/mcp` (Streamable HTTP, 버전 2026-07-28 · 2025-11-25 · 2025-06-18). REST: `https://bomnuri.com/api/ads/v1`. 인증은 둘 다 `Authorization: Bearer pcads_…` — 광고주가 콘솔에서 발급한다.

헤더를 넣을 수 없는 클라이언트(claude.ai·ChatGPT 커넥터)는 MCP 주소만 넣으면 OAuth 2.1(PKCE S256 · 동적 등록 · 클라이언트 ID 메타데이터 문서)로 연결된다 — 보호 리소스 메타데이터 `https://bomnuri.com/.well-known/oauth-protected-resource/mcp`.

연결 예(Claude Code):

```
claude mcp add --transport http bomnuri-ads https://bomnuri.com/mcp --header "Authorization: Bearer pcads_…"
```

규칙: 링크는 쿠팡 파트너스 주소(link.coupang.com/a/… · coupa.ng/…)만. 타기팅은 문맥(사이트·주제·키워드·육아 단계)만 — 사람 정보는 없다. 모든 광고에 「광고」 표시와 대가성 문구가 붙는다. 노출·클릭에서 봇·AI 활동은 뺀다. 분유(영아용 조제유)·의약품 광고는 받지 않는다.

## 문서

- [OpenAPI 3.1](https://bomnuri.com/api/ads/v1/openapi.json): 모든 작업의 입력 스키마·오류·스코프
- [개발자 안내](https://bomnuri.com/ads/developers/): 키 발급·연결·예시 대화(사람용)

## 읽기 도구 (스코프 ads:read)

- `get_account` — GET /api/ads/v1/account: 이 API 키가 묶인 광고주, 키 권한(스코프), 한도, 광고 집행 순서를 돌려준다. 처음 연결했을 때 먼저 부르세요.
- `list_placements` — GET /api/ads/v1/placements: 광고가 들어갈 수 있는 지면과 추천 이유·기대 효과·조건. 지면을 고르지 않으면 맞는 지면 전체에 나간다.
- `list_targeting_options` — GET /api/ads/v1/targeting-options: 타기팅에 쓸 수 있는 사이트(slug·주제)와 육아 단계. 사람 정보(나이·성별·관심사·위치)로는 타기팅하지 않는다.
- `estimate_reach` — POST /api/ads/v1/estimate: 타기팅 조건의 예상 하루 노출(최근 7일 실제 서빙 수 평균, 봇·AI 제외). 주제·키워드로 좁히면 상한값이다.
- `check_policy` — POST /api/ads/v1/policy/check: 문안·링크를 제출 전에 검사한다. issues 의 code·message 로 고친 뒤 다시 검사하세요. 저장하지 않는다.
- `suggest_ad_copy` — POST /api/ads/v1/copy/suggest: 상품명·키워드(·쿠팡 파트너스 링크)로 광고 제목·설명 초안 최대 3개와 추천 지면을 만든다. 정책 검사를 통과한 초안만 돌려준다. 20~40초 걸릴 수 있고 광고주당 하루 20회.
- `list_campaigns` — GET /api/ads/v1/campaigns: 이 광고주의 캠페인(보관 제외)과 상태·오늘 노출·클릭.
- `get_campaign_status` — GET /api/ads/v1/campaigns/{campaignId}: 캠페인 상태, 소재별 검토 결과(정책 코드·사유), 사람에게 전할 다음 단계 문장(nextStep).
- `get_report` — GET /api/ads/v1/campaigns/{campaignId}/report: 일별 노출(served)·보임(viewable)·클릭·CTR·예상 비용. 봇·AI 활동은 빼고 센다(filtered 는 따로). 기본 최근 7일, 최대 92일.

## 쓰기 도구 (스코프 ads:write)

- `create_campaign_draft` — POST /api/ads/v1/campaigns: 캠페인을 초안(draft)으로 만든다. 돈은 나가지 않는다 — 검토·결제 전에는 노출되지 않는다. 다음은 add_creative_from_coupang_url.
- `add_creative_from_coupang_url` — POST /api/ads/v1/campaigns/{campaignId}/creatives: 쿠팡 파트너스 링크(link.coupang.com/a/… 또는 coupa.ng/…)로 소재를 추가한다. headline 을 비우면 AI 문안 도우미가 채운다. 정책에 걸리면(422) 저장하지 않고 issues 를 돌려준다.
- `update_creative` — PATCH /api/ads/v1/creatives/{creativeId}: 거절됐거나 고칠 소재의 문안·링크를 바꾼다. 내용이 바뀌면 그 소재만 다시 검토한다. status 로 소재를 켜고 끈다(active|paused).
- `submit_for_review` — POST /api/ads/v1/campaigns/{campaignId}/submit: 캠페인을 검토에 제출한다. 자동 정책 검사 뒤 운영팀이 사람 검토를 한다(자동 승인 없음). 승인되면 awaiting_payment(결제 연결 전)에서 멈춘다.
- `pause_campaign` — POST /api/ads/v1/campaigns/{campaignId}/pause: 집행 중(active)인 캠페인을 멈춘다. 다시 켜는 것은 사람이 콘솔에서 한다.

## Optional

- 오류 형식: `{error, detail, message, issues?}` — message 는 사람에게 그대로 전해도 되는 한국어 문장. 422 policy 는 issues 의 code 로 고친다.
- 한도: 키당 분당 60요청·쓰기 20(`RateLimit-*` 헤더, 429 면 `Retry-After`). 쓰기는 `Idempotency-Key` 로 안전하게 재시도.
- 문의: contact@bomnuri.com