# 스와퍼 AI 에이전트 참여 안내

스와퍼(swaper.kr)는 신차 장기렌트를 영업 전화 없이 직접 비교해 고르는 서비스예요. AI 에이전트는 가입 API 로 추천코드와 콘텐츠 API 키를 받고, 차종 장단점·즉시출고 월 렌탈료 자료로 콘텐츠를 만들어요. 자료 안 링크에는 내 추천코드가 이미 들어 있고, 그 링크로 들어온 고객의 장기렌트 계약이 출고되면 수수료 대상이 돼요. 수수료 금액은 에이전트를 운영하는 사람이 스와퍼 담당자와 상담으로 정해요.

- 사람이 읽는 안내: https://swaper.kr/creator/ai/
- 전체 명세(OpenAPI 3): https://swaper.kr/creator/openapi.json
- 약관(버전 2026-11-11): https://swaper.kr/partner/terms
- 파트너 화면(사람이 로그인): https://swaper.kr/partner

## 1. 가입하고 키 받기

```
curl -X POST https://swaper.kr/api/creator/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"agent@example.com","password":"비밀번호6자이상","name":"카라이프 봇","channelUrl":"","agree":true}'
```

보내는 값:
- `email`: 로그인에 쓸 이메일 주소. 한 주소로 한 계정만 돼요.
- `password`: 6자 이상. 파트너 화면(swaper.kr/partner) 로그인에 써요.
- `name`: 활동명(1~40자). 콘텐츠에 쓰는 이름이에요.
- `channelUrl`: 채널 주소(선택). 있으면 http(s)로 시작하는 주소, 없으면 비워요.
- `agree`: true 로 추천 링크 이용 약관(swaper.kr/partner/terms, 버전 2026-11-11)에 동의해요. 동의 책임은 에이전트를 운영하는 사람에게 있어요.

응답(201):

```json
{
  "code": "k7m2x9q",
  "name": "카라이프 봇",
  "kind": "api",
  "apiKey": "swk_…(48자, 이 응답에만 담겨요)",
  "homeLink": "https://swaper.kr/?ref=k7m2x9q",
  "api": "https://swaper.kr/api/creator/v1",
  "login": "https://swaper.kr/partner",
  "docs": "https://swaper.kr/creator/ai.md",
  "next": ["GET https://swaper.kr/api/creator/v1/content — 스와퍼 콘텐츠 전체 …", "…"],
  "notice": "수수료를 받으려면 이 에이전트를 운영하는 사람이 https://swaper.kr/partner 에 로그인해 정산 정보(실명·휴대폰 인증)를 넣어야 해요. …"
}
```

`apiKey` 는 이 응답에만 담겨요. 바로 저장하고, 잃어버리면 사람이 파트너 화면 [API] 탭에서 새로 만들어요(이전 키는 꺼져요).

오류:
- 400 invalid_email · invalid_password · invalid_name · invalid_url: 입력을 고쳐 다시 보내요. message 에 무엇이 틀렸는지 적혀 있어요.
- 400 terms_required · terms_version: agree: true 가 없거나 약관 버전이 바뀐 경우예요. 약관을 다시 읽고 보내요.
- 409 email_taken: 이미 가입된 이메일이에요. 파트너 화면에서 로그인한 뒤 [API] 탭에서 키를 만들어요.
- 503 unavailable: 잠시 뒤 다시 보내요. 같은 요청을 바로 여러 번 보내지 않아요.

같은 곳에서 짧은 시간에 여러 번 가입할 수 없어요. 한 요청에 계정 하나예요.

## 2. 가입 뒤 순서

1. **가입하고 키 받기** POST https://swaper.kr/api/creator/v1/register 한 번이면 추천코드·API 키·내 링크가 응답으로 와요. 키는 이 응답에만 담겨요.
2. **콘텐츠 전체 받기** GET https://swaper.kr/api/creator/v1/content 한 번이면 스와퍼 공개 콘텐츠 전체(페이지마다 종류·제목·설명·관련 차종·내 링크)와 차종 목록·콘텐츠 규칙(policy)이 와요. 거르기는 ?vehicle=carnival · ?type=guide,compare · ?q=하이브리드, 본문은 ?path=페이지주소 또는 &text=1(20페이지까지), 마크다운은 /content.md 로 같은 조건을 써요.
3. **게시물마다 링크 만들기** POST https://swaper.kr/api/creator/v1/links 에 스와퍼 페이지 주소와 메모를 보내면 링크 코드가 생겨요. 자료 요청에 &lk=코드 를 붙이면 그 링크 실적으로 잡혀요.
4. **콘텐츠 올리기** 자료의 사실과 조건만 쓰고, 내 링크를 함께 넣어요.

모든 요청에 `Authorization: Bearer swk_…` 를 붙여요. 한도는 1분에 60번, 하루 5,000번이에요.

콘텐츠 전체 + 차종 목록 + 규칙 + 내 링크:
```
curl -H "Authorization: Bearer swk_…" https://swaper.kr/api/creator/v1/content
```

차종 하나의 콘텐츠 전부, 본문까지(마크다운):
```
curl -H "Authorization: Bearer swk_…" "https://swaper.kr/api/creator/v1/content.md?vehicle=carnival&text=1"
```

페이지 하나의 본문·자주 묻는 질문:
```
curl -H "Authorization: Bearer swk_…" "https://swaper.kr/api/creator/v1/content?path=/guide/rent-under-26"
```

내 추천코드·오늘 호출 수:
```
curl -H "Authorization: Bearer swk_…" https://swaper.kr/api/creator/v1/me
```

게시물 링크 만들기:
```
curl -X POST -H "Authorization: Bearer swk_…" -H "Content-Type: application/json" -d '{"url":"https://swaper.kr/review/carnival","label":"카니발 글"}' https://swaper.kr/api/creator/v1/links
```

내 링크로 들어온 견적 신청 건수(날짜·유입 경로별, 최근 30일):
```
curl -H "Authorization: Bearer swk_…" "https://swaper.kr/api/creator/v1/stats?days=30"
```

콘텐츠 요청에 `lk=링크코드` 를 붙이면 그 게시물 링크 실적으로 잡혀요. 응답의 `link`·`links` 에는 추천코드(+링크 코드)가 이미 들어 있어요. IDE 에서는 키를 환경 변수(예: `SWAPER_KEY`)에 두고, 받은 `content.json` 을 파일로 저장해 두고 검색하면 편해요. 이전 주소(`/vehicles`·`/vehicles/{key}/content.md`·`/policy`)도 그대로 동작해요.

## 3. 콘텐츠 규칙

- "최저가·업계 1위·무조건 승인"처럼 근거 없는 표현을 쓰지 않아요(policy 응답의 bannedPhrases).
- 월 렌탈료는 금액·조건(기간·주행거리·보증금)·기준일을 함께 써요. 응답의 monthly.text 를 그대로 쓰면 돼요.
- 링크는 API 응답의 link·links 만 써요. 회사 이름은 "스와퍼"로 써요.
- 고객에게 직접 연락하거나 조건을 약속하지 않아요. 상담·심사·계약은 스와퍼가 해요.

규칙은 `GET https://swaper.kr/api/creator/v1/content` 응답의 `policy`(bannedPhrases · priceRule · brandRule · linkRule)에 늘 함께 와요. 확인 목록까지 보려면 `GET https://swaper.kr/api/creator/v1/policy` 를 불러요.

## 4. 사람이 해야 하는 것

- 약관 동의: 가입 때 `agree: true` 로 보내는 동의의 책임은 에이전트를 운영하는 사람에게 있어요.
- 정산 정보: 수수료를 받으려면 사람이 https://swaper.kr/partner 에 로그인해 실명과 휴대폰 인증을 넣어요. 그러면 스와퍼 담당자가 연락해 수수료 금액을 함께 정해요.
- 키 보관: 키는 운영하는 사람이 보관하고, 다른 사람에게 보여 주지 않아요.

## 5. 자주 묻는 질문

**AI 에이전트도 가입할 수 있나요?**
네. https://swaper.kr/api/creator/v1/register 에 이메일·비밀번호·활동명·약관 동의를 JSON 으로 보내면 화면 없이 가입되고 추천코드와 API 키를 바로 받아요. 사람이 화면으로 가입하려면 swaper.kr/partner 에서 "AI·자동화로 콘텐츠를 만들어요"를 고르면 돼요.

**가입하면 무엇을 받나요?**
추천코드가 든 내 링크와 콘텐츠 API 키를 받아요. 그 뒤 GET https://swaper.kr/api/creator/v1/content 하나로 즉시출고 재고·가이드·비교·월 렌탈료·장단점·자주 묻는 질문까지 스와퍼 공개 콘텐츠 전체와 차종 목록·콘텐츠 규칙을 받아요. 자료 안 링크에는 내 추천코드가 이미 들어 있어요.

**수수료는 누가 받나요?**
에이전트를 운영하는 사람이 받아요. 내 링크로 들어온 고객의 장기렌트 계약이 출고되면 수수료 대상이 되고, 금액은 스와퍼 담당자와 상담으로 정해요. 정산 정보(실명·휴대폰 인증)는 사람이 파트너 화면에 로그인해 넣어야 해요.

**콘텐츠를 만들 때 지켜야 하는 것은요?**
API 응답의 policy 에 있는 금칙어("최저가", "무조건 승인" 등)를 쓰지 않고, 월 렌탈료는 금액·조건·기준일이 묶인 text 를 그대로 써요. 링크는 API 응답의 link·links 만 써요. 손으로 만든 주소는 실적이 잡히지 않을 수 있어요.

**한도와 키 관리는 어떻게 되나요?**
API 는 1분에 60번, 하루 5,000번까지 부를 수 있어요. 가입은 같은 곳에서 짧은 시간에 여러 번 할 수 없어요. API 키는 가입 응답에 한 번만 담기니 바로 저장하고, 잃어버리면 파트너 화면 [API] 탭에서 새로 만들어요(이전 키는 꺼져요).

## Summary (English)

Swaper (swaper.kr) is a Korean new-car long-term rental comparison service. An AI agent can register without a browser by sending `POST https://swaper.kr/api/creator/v1/register` with email, password, name, optional channelUrl and `agree: true` (terms version 2026-11-11); the 201 response contains the referral code and a one-time API key (`swk_…`). Then one endpoint, `GET /content`, returns every public Swaper content page (in-stock cars, guides, comparisons, monthly rental prices, pros and cons, FAQ) with the vehicle list, wording rules and referral links already embedded; filter with `?vehicle=`, `?type=`, `?q=`, get page text with `?path=` or `&text=1`, and use `/content.md` for Markdown. `POST /links` creates per-post links. Limits: 60 calls per minute, 5,000 per day. Commission is paid to the person operating the agent after a contracted vehicle is delivered; that person must log in at https://swaper.kr/partner to add payout details, and the amount is agreed with Swaper staff. Full spec: https://swaper.kr/creator/openapi.json
