feat(performance): 토스쇼핑 매출 수집 — OAuth 토큰·주문 내역 조회(31일·커서)·원본 데이터 확인

- 인증: Access Key·Secret Key → POST oauth2.cert.toss.im/token(client_credentials, scope toss-shopping-fep:write),
  토큰(약 1년) 암호화 저장·재사용, 401 이면 한 번 새로 발급. 키 발급 때 등록한 IP 에서만 호출됨
- 입력칸 라벨을 Access Key / Secret Key 로(키 이름 api_key·api_secret 그대로 — 저장값 유지), 판매자 ID 칸 제거
- 수집: GET /api/v3/shopping-fep/orders/v2 31일 구간 + nextCursor, HTTP 200 + resultType FAIL 도 오류 처리
- 잠정 매출 규칙: 주문 단위(toss:{orderId}), 주문일(한국 날짜), price 합(할인 전·배송비 제외), 결제 전만 제외
- 설정 화면 "쇼핑몰 원본 데이터 확인"에 토스쇼핑 — 상태별 항목 합계·날짜별 현재 규칙 매출(개인정보 숨김)
- 테스트 3개 추가(토큰·연결·오류, 수집 규칙·구간·커서, 원본 확인 개인정보), 문서 갱신

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 09:36:42 +09:00
parent d3761183c3
commit a45f78217c
6 changed files with 566 additions and 15 deletions
+24 -1
View File
@@ -29,7 +29,7 @@
오류 클래스 = 연결 상태: `NotConfigured`(인증정보 미설정) · `AuthFailed`(인증 실패) · `TokenExpired` · `ApiError` · `NotImplementedYet`(연동 준비 중).
**연동 현황**: 카페24·11번가·네이버 스마트스토어·GS샵 = **구현됨**, 나머지 7개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 현황**: 카페24·11번가·네이버 스마트스토어·GS샵·토스쇼핑 = **구현됨**(토스쇼핑은 매출 규칙 잠정), 나머지 5개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 단계에서 공식 API 문서로 확정**한다.
### 카페24 (`adapters/cafe24.py`, 구현됨)
@@ -147,6 +147,29 @@
**GS샵 수수료율은 0%**. 배송비 제외, `ordType` 이 SALE 이 아니면 RETURN 음수. `replace_range`.
원본 데이터 확인에 날짜별 현재 규칙 매출·취소/반품·배송비(참고).
### 토스쇼핑 (`adapters/toss.py`, 구현됨 — 매출 규칙 잠정)
- 문서: `https://shopping-docs.toss.im/dev` (공개, 전체 목록 `llms.txt`, 쪽 주소 뒤 `.md` = 원문). 문의는 문서의 디스코드.
- 인증: 토스쇼핑 파트너스 → 상점 이름 > 가맹점·계정 관리 > **자체 개발** → [키 발급](**호출 IP 입력 — 운영 서버 외부 IP**, 등록된
IP 만 호출 가능) → Access Key·Secret Key. `POST https://oauth2.cert.toss.im/token`(form: `grant_type=client_credentials`·
`client_id`=Access Key·`client_secret`=Secret Key·`scope=toss-shopping-fep:write`). 토큰 `expires_in` 약 1년 — 문서가 매번 발급하면
이용이 제한될 수 있다고 해서 `access_token`·`access_token_expires_at`(internal, 암호화)으로 저장해 재사용, 만료 1시간 전·401 이면 새로.
[연결 테스트]는 입력값으로 시험하므로 항상 새 토큰. 입력칸 키는 처음 만든 `api_key`(Access Key)·`api_secret`(Secret Key) 그대로
(라벨만 변경 — 예전 "판매자 ID" 칸은 없앰).
- API: `https://shopping-fep.toss.im`, `Authorization: Bearer {token}`. 오류가 **HTTP 200 + `resultType: "FAIL"`**(`error.errorCode`·
`reason`)로도 온다. 읽기 초당 50회(넘으면 `TOO_MANY_REQUEST`) → 호출 간격 0.1초, 제한이면 1·2·4초 쉬고 다시.
- 수집: 주문 내역 조회 `GET /api/v3/shopping-fep/orders/v2?startDate&endDate&limit=50&nextCursor` — 한 번에 **31일**, 상태 생략 =
전체, 커서(`nextCursor` null = 끝). 줄 = 주문상품(`orderProductId`), 주문 = `orderId`. 금액 항목: `price`(판매가 × 수량)·
`originPrice`(정상가 × 수량)·`totalDiscountPrice`(= `tossShoppingDiscount` + `tossPayDiscount`)·`tossPayPoint`·`deliveryFee`
(묶음 `deliveryFeeGroupId` 마다). 결제일 필드는 따로 없고 `orderedAt`(주문 = 결제) · `canceledAt` · `confirmedAt`.
- **매출 규칙(잠정, 파트너스 화면과 대조 전)**: SALE = 주문 하나(`toss:{orderId}`), 날짜 = `orderedAt` 의 한국 날짜, 금액 =
`price` 합(할인 전, 배송비 제외), 할인은 `discount_amount` 로만. 결제 전(`BEFORE_PAYMENT`)만 빼고 결제 뒤 취소·반품도 주문일 매출에
둔다(네이버와 같은 방식 → 지난 날짜 매출이 나중에 줄지 않음). `replace_range`. 개인정보(주문자·수령인·주소·요청사항·송장)는 저장 안 함.
- 정산 API `GET /settlement-steps`(`dateCondition` PAYOUT_DATE·PAYOUT_BASE_DATE·TRANSACTION_DATE…, 31일, `stepType` PAY|REFUND,
셀러 부담 쿠폰 `shoppingDiscountMerchant`, 정산 지급액 `settlementAmount`)은 구매확정·취소된 건만 나온다 — 규칙 확정 때 필요하면 쓴다.
- 확정 방법: 설정 화면 "쇼핑몰 원본 데이터 확인" → 토스쇼핑, 매출이 있던 기간 → 날짜별 현재 규칙 매출·상태별 항목 합계를 토스쇼핑
파트너스 매출 화면과 비교해 맞는 항목(`price` / `price − totalDiscountPrice` / 취소 제외 여부)으로 규칙을 고친다.
### 연동 단계 체크리스트(쇼핑몰마다)
- 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 API·날짜 필드 확인