제휴사 연동
AI로 구현하기
Claude·ChatGPT·Cursor 같은 AI 코딩 도구에 붙여넣으면 규약대로 구현하도록 만든 통합 프롬프트와 AI용 문서 경로입니다.
AI 코딩 도구로 연동을 구현한다면 이 페이지부터 쓰세요. 아래 통합 프롬프트 하나에 연동 규약, 틀리기 쉬운 점, 완료 기준을 모두 담았습니다. 문서를 일일이 읽히지 않아도 AI 가 같은 기준으로 구현합니다.
사용 방법
프롬프트 복사
아래 코드 블록 오른쪽 위의 복사 버튼을 누릅니다.
맨 위 "우리 환경" 채우기
언어·프레임워크, 로그인 방식(ⓐ/ⓑ), 회원·구매 테이블 이름을 적습니다. 모르는 칸은 비워 두면 AI 가 먼저 물어봅니다.
AI 도구에 붙여넣기
Claude Code·Cursor·Codex 처럼 저장소를 읽는 도구라면 저장소 루트에서 실행하세요. AI 가 기존 회원·주문 코드를 찾아 거기에 맞춰 구현합니다.
통합 프롬프트
# 과제: 쏠브(Solve) 제휴사 연동 구현
## 우리 환경 (채워서 사용)
- 언어/프레임워크:
- 로그인 방식: ⓐ 자격증명 API / ⓑ 호스팅 로그인 페이지 (소셜 로그인이 하나라도 있으면 ⓑ)
- 회원 테이블과 불변 회원번호 컬럼:
- 구매(주문) 테이블과 "현재 이용 가능" 판정 기준(환불·만료 제외):
## 배경
쏠브는 전자책 학습 앱이다. 우리 사이트에서 책을 산 회원이 쏠브 앱에서 우리 계정으로 로그인하면,
쏠브 서버가 우리 API 를 호출해 구매 목록을 받아 책장에 책을 넣는다.
**쏠브가 호출하는 쪽이고, 우리가 API 를 구현하는 쪽**이다.
전체 규약 원문: https://developers.solve.im/llms-full.txt (필요하면 읽어라)
## 구현할 것
1. 로그인 (둘 중 하나)
ⓐ 자격증명 로그인 API — POST, JSON 요청 {"id": string, "password": string}
- 성공: 200 {"user_key": string}
- 아이디·비밀번호 불일치: 4xx (쏠브 앱이 "비밀번호 불일치"로 안내, 재시도 안 함)
- 서버 오류: 5xx (쏠브가 최대 2번 재시도)
ⓑ 호스팅 로그인 페이지 — 쏠브 앱 웹뷰가 우리 "쏠브 전용 로그인 URL"을 쿼리 파라미터 없이 연다
- 회원이 로그인에 성공하면 우리 **서버에서** 쏠브 콜백 호출:
POST {SOLVE_CALLBACK_URL} JSON {"id": string, "platform_type": number}
헤더 Authorization: Bearer {SOLVE_CALLBACK_SECRET} (쏠브 발급, 401 이면 재시도 금지)
- 응답 200 {"redirect_url": string} → 같은 웹뷰에서 그 URL 로 302 이동 (새 창·외부 브라우저 금지, URL 수정 금지 — 서명 포함)
- 소셜 로그인으로 외부에 다녀오는 경우 세션에 "쏠브 연동 중" 표시를 유지했다가 완료 시 콜백
- SOLVE_CALLBACK_URL, SOLVE_PLATFORM_TYPE, SOLVE_CALLBACK_SECRET 은 쏠브가 전달하는 값 → 환경변수로
2. 구매내역 API — POST, JSON 요청 {"user_key": string}
- 200 {"item_list": [{"item_code": string, "item_name": string(선택)}]}
- 선택 필드 (없어도 된다. 기존 구현은 수정 없이 유효): 항목마다 price · paid_at · access_type · valid_from · valid_until 을 더 담을 수 있다
· price: 결제 금액(원). 0 이상 정수(숫자) 또는 숫자만으로 된 문자열(1~12자리)
· paid_at: ISO 8601. 오프셋(Z, +09:00)이 있으면 그대로, 없으면 한국 시간(+09:00), 날짜만이면 그날 00:00 한국 시간
· access_type: 생략 또는 "permanent" 는 영구 소장, "rental" 은 대여. 그 밖의 값은 쏠브가 그 책을 열지 못하게 막는다
· valid_from: 이용 시작 시각 (영구 소장·대여 모두). ISO 8601, 오프셋이 없으면 한국 시간, 날짜만이면 그날 00:00 한국 시간부터. 이 시각 전에는 책장에 보이지만 열리지 않고 "○년 ○월 ○일 ○시부터 볼 수 있습니다" 를 안내한다. 시각이 지나면 다시 조회하지 않아도 열린다. 없으면 바로 열린다. 읽을 수 없는 값(자유 표기)은 막지 않고 기록만 한다
· 대여 항목의 valid_until 이 valid_from 과 같거나 앞서거나, 없거나 읽을 수 없으면 쏠브가 이용 기간을 확인할 수 없어 그 책을 열지 못하게 막는다 (시작 안내도 하지 않는다)
· 사전판매(오픈일 전 판매)는 항목에 valid_from 으로 오픈 시각을 넣는다. 쏠브는 조회마다 valid_from 을 새 값으로 바꾸므로, 오픈을 바꾸려면 새 시각을, 바로 열려면 valid_from 을 빼거나 지난 시각을 보낸다
· valid_until: 영구 소장 항목에서는 1~32자 문자열을 그대로 기록만 한다. 대여 항목에서는 ISO 8601 이용 종료 시각이다 (오프셋이 없으면 한국 시간, 날짜만이면 그날 23:59:59.999 한국 시간까지)
· 영구 소장 항목의 선택 필드는 형식이 틀리면 그 필드만 무시한다 (책 지급에는 영향 없음)
· 영구 소장 항목은 price 를 안 보내거나 0 이면 파트너 어드민에 등록한 가격으로 정산한다. 대여 항목의 price 는 결제 금액(원)이며 필수다
· 영구 소장 항목은 valid_until 이 지나도 자동으로 빠지지 않는다. 회수는 목록에서 빼는 것뿐이다
- 대여: 판매와 같은 item_code 를 쓰고 항목에 access_type "rental" 을 넣는다. paid_at · valid_until · price 가 모두 필수다. 그중 valid_until 이 없거나 읽을 수 없으면 쏠브가 이용 기간을 확인할 수 없어 그 책을 열지 못하게 막는다
· 대여 기간이 끝나도 책은 책장에 남고, 열려고 하면 끝난 날짜를 안내하며 열리지 않는다. 다시 대여하면 다시 열린다
· 끝난 대여 항목도 목록에 계속 보낸다 (목록에서 빼면 책장에서 빠진다)
· item_code 당 항목은 한 개만, 가장 최근 대여의 paid_at 과 valid_until 로 보낸다. 연장도 결제가 있으면 새 paid_at 으로 보낸다
· 같은 책에 영구 소장 항목이 하나라도 있으면 열린다. 없으면 valid_until 이 지나지 않은 대여 항목이 있을 때 열린다
- **현재 이용 가능한 구매만** 담는다. 환불과 회수할 영구 소장 항목은 뺀다 (끝난 대여 항목은 계속 담는다)
- 구매가 없거나 회원이 없으면 200 {"item_list": []}
- 조회 실패·장애는 반드시 5xx. 예외를 삼키고 200 을 보내지 마라 (일부만 조회된 목록이면 빠진 책이 회수된다)
- 페이지네이션 없이 한 번에 전부
3. 공통
- HTTPS, Content-Type: application/json, 10초 안에 응답 (쏠브 타임아웃 10초)
- 쏠브는 우리가 발급한 시크릿을 헤더에 담아 보낸다. 헤더 이름은 우리가 정한다 (기본값: X-Solve-Secret)
- 시크릿은 환경변수로 두고(비어 있으면 서버 시작 실패) 상수 시간 비교로 확인, 불일치면 `401` 또는 `403`
- 쏠브는 `401` 과 `403` 을 구분하지 않고 같은 인증 실패로 처리한다 (둘 다 재시도 없음)
- 같은 요청이 재시도로 여러 번 와도 데이터가 바뀌면 안 된다 (조회 전용)
- 응답 본문은 1MB(1,048,576바이트) 이하. 쏠브는 1MB 를 넘는 응답을 받지 않는다 (넘으면 그 호출은 실패, 재시도 없음 — 구매내역이면 기존 책장 유지). 구매내역·ⓐ 로그인 모두 해당, 필요한 필드만 담는다
## 선택: 환불 판단용 열람 조회
- 표준 제휴사 서버 → 쏠브: POST {SOLVE_API_BASE_URL}/api/v1/partner-connect/access-status
- Authorization: Bearer {SOLVE_CALLBACK_SECRET} (콜백과 같은 쏠브 발급 키, 없거나 틀리면 항상 401)
- JSON {"platform_type": number, "user_key": string, "items": [{"item_code": string, "purchased_at": "ISO 8601 (선택)"}]}, items는 선택이며 지정하면 1~100개, 빈 배열은 400
- 200 {"linked": boolean, "items": [{"item_code": string, "viewed": boolean, "first_viewed_at": "KST ISO 8601 또는 null"}]}; items 지정 시 요청 순서 유지
- items 생략: 해당 제휴사가 등록한 비어 있지 않은 연동코드를 공백 제거·중복 제거·대소문자 구분 오름차순으로 반환, 전체 기간 최초 열람. 미연동도 같은 코드 목록·전부 미열람. 등록 코드가 없으면 빈 목록
- 회원 전체 조회는 앞 1000개까지, 초과 시에만 truncated: true 추가(그 밖에는 키 생략). 재구매 주문 환불 판단은 상품코드+purchased_at 지정
- 다운로드도 열람에 포함. purchased_at 이상인 접근·다운로드 중 최초 시각. 오프셋 생략은 한국 시간
- 미연동·미등록 코드는 미열람. 오류는 미열람으로 처리하지 않는다. 400(형식·대상), 401(키), 429(분당 600회, Retry-After), 500(조회 오류)
- 환불 직전에 해당 주문의 구매 시각으로 조회한다. 책장 노출은 구매내역 목록으로 결정된다
- 상세: https://developers.solve.im/docs/partner-integration/access-status-api
## 선택: 환불·취소·탈퇴 회수 알림
- 표준 제휴사 서버 → 쏠브: POST {SOLVE_API_BASE_URL}/api/v1/partner-connect/revocations
- 인증: Authorization: Bearer {SOLVE_CALLBACK_SECRET} (콜백·열람 조회와 같은 키), 분당 600회
- 본문: platform_type(정수), user_key(1~255자), items([{item_code}] 1~100개) 또는 all: true 중 정확히 하나, reason("refund"|"cancel"|"withdrawal"), idempotency_key(1~128자, 공백 없는 ASCII, 대소문자 구분)
- 응답 200: {linked, revoked_count, items:[{item_code, revoked}]}. linked false = 연동 없음(오류 아님). 같은 idempotency_key 재호출은 처음 응답 그대로(+ 헤더 Idempotent-Replayed: true), 다시 처리하지 않음
- 409 = 같은 키로 다른 요청. 400(형식·대상), 401(키), 429(Retry-After), 500(같은 키로 재시도)
- 회수 알림을 보내도 그 상품을 구매내역 목록에서 반드시 뺀다 — 남아 있으면 다음 동기화가 다시 지급한다
- 모든 상품 환불·탈퇴로 목록이 비는 회원은 all: true 로 보낸다(빈 목록만으로는 회수하지 않는다)
- 상세: https://developers.solve.im/docs/partner-integration/revocation-api
## 선택: 관리자·마이페이지용 열람 기록 조회
- 표준 제휴사 서버 → 쏠브: POST {SOLVE_API_BASE_URL}/api/v1/partner-connect/access-history (같은 Authorization, 같은 400·401·429·500, 분당 600회)
- JSON {"platform_type": number, "user_key": string, "item_code": "선택", "from": "ISO 8601 이상(선택)", "to": "ISO 8601 미만(선택)", "order": "desc(기본)|asc", "page_size": 1~500(기본 100), "cursor": "앞 응답의 next_cursor(선택)"}
- 200 {"linked": boolean, "records": [{"type": "view|download", "occurred_at": "KST ISO 8601", "item_codes": [string], "book_id": string, "isbn": "string 또는 null", "device": {"type": "mobile|tablet|desktop|unknown", "os": "ios|android|windows|macos|unknown"}}], "next_cursor": "string 또는 null"}
- next_cursor 가 null 이 될 때까지 cursor 만 바꿔 같은 조건으로 이어 받는다. 커서와 order 가 다르면 400, from >= to 도 400
- type 은 모두 열람으로 센다(download 는 기기에 받아 둔 열람). device 는 모든 기록에 있고 모르면·오래된 기록이면 unknown. 미연동은 linked=false·빈 records
- 최근 열람: order desc + page_size 1, 처음 열람: order asc + page_size 1. 진행률은 상품의 책 가운데 기록이 있는 book_id 수로 제휴사가 계산. 마지막 기기: desc 기록 중 device.type 이 unknown 이 아닌 첫 기록
- 개인정보: 회원 마이페이지·고객 응대·환불 판단·관리자 화면에만 쓰고 다른 목적·제3자 제공 금지
- 상세: https://developers.solve.im/docs/partner-integration/access-history-api
## 반드시 지킬 것 (틀리기 쉬움)
- user_key(ⓑ 의 id)는 **절대 바뀌지 않는 내부 회원번호**. 로그인 아이디·이메일·소셜 계정 ID 금지
- 탈퇴 회원의 user_key 를 다른 회원에게 재사용 금지
- item_code 는 상품 단위 코드이며, 쏠브 파트너 어드민에 입력한 "연동코드"와 같아야 한다. 쏠브는 item_code 의 앞뒤 공백을 떼고 비교하고, 그 밖은 대소문자까지 글자 그대로 같아야 한다 (연동코드 앞뒤에 공백을 넣지 않는다)
- 비밀번호·시크릿을 로그에 남기지 않는다
- 예외를 삼키고 200 을 보내지 않는다
## 결정 기본값 (모호하면 이렇게)
- 엔드포인트 경로: POST /solve/login (ⓐ), POST /solve/purchases
- 아이디·비밀번호 불일치 401, 시크릿 불일치 `401` 또는 `403` (기본은 403), 요청 형식 오류 400, 그 외 예외 500
- 에러 응답 본문: {"error": "<snake_case 코드>"}
## 산출물
1. 위 API 구현 코드 (기존 회원·주문 코드를 찾아서 재사용)
2. 테스트: 구매 회원 200, 없는 회원 200+빈 배열, 환불 상품 제외, 틀린 시크릿 `401` 또는 `403`, DB 오류 500
(ⓐ 는 맞는/틀린 비밀번호도)
3. 쏠브가 보낼 요청을 재현하는 curl 명령
4. 쏠브에 전달할 값 목록: 각 URL, 시크릿 헤더 이름, 테스트 계정
5. 구현 뒤 `solve-selfcheck.mjs`(https://developers.solve.im/tools/solve-selfcheck.mjs)로 확인한다 — `--init` 으로 설정 틀을 만들고 값을 채워 실행하며, FAIL 이 0개일 때까지 고친다 (ⓑ 는 `solve-callback-mock.mjs` 로 콜백을 시험)
작업 전에 우리 코드베이스에서 회원·구매 관련 코드를 먼저 찾아보고, 구현 계획을 짧게 보여준 뒤 진행해라.저장소에 규칙으로 넣기
같은 저장소에서 AI 에게 여러 번 일을 시킨다면, 프롬프트를 규칙 파일로 넣어 두면 매번 붙여넣지 않아도 됩니다.
| 도구 | 파일 위치 |
|---|---|
| Claude Code | 저장소 루트 CLAUDE.md 에 추가 |
| Codex, 기타 에이전트 | 저장소 루트 AGENTS.md 에 추가 |
| Cursor | .cursor/rules/solve-integration.mdc |
| GitHub Copilot | .github/copilot-instructions.md |
AI 도구용 문서 경로
| 경로 | 내용 | 쓰는 곳 |
|---|---|---|
/llms.txt | 전체 문서 목차 | AI 에게 "여기서 필요한 문서를 찾아 읽어" |
/llms-full.txt | 전체 문서를 한 파일로 | 한 번에 모든 규약을 넘길 때 |
각 페이지 URL 뒤에 .md | 그 페이지만 마크다운으로 | 특정 페이지만 넘길 때 (예: /docs/partner-integration/purchase-history-api.md) |
각 페이지 제목 아래의 마크다운 복사·AI로 열기 버튼으로도 그 페이지를 바로 넘길 수 있습니다.
AI 가 만든 코드도 셀프 점검을 거쳐 주세요
특히 "예외를 삼키고 200 응답"과 "로그인 아이디를 user_key 로 사용"은 AI 가 자주 만드는 실수입니다. 테스트와 출시의 셀프 점검 도구(solve-selfcheck.mjs)로 확인한 뒤 쏠브에 전달해 주세요.