참고

구독 마이그레이션

기존 구독 고객과 계약을 다음 회차 기준으로 안전하게 옮겨요.

개념 배경

PG·솔루션 선택과 계약 판단은 블로그에서 다뤄요. 이 페이지는 기술 마이그레이션 순서 한정​.

기존 다른 솔루션의 구독 계약, 고객, 상품 정보를 부트페이로 한 번에 옮겨오는 API예요. CSV 파일을 통해 데이터를 일괄 등록하며, 다음 구독회차부터 자동으로 관리돼요.

API 엔드포인트

POSThttps://api.bootapi.com/v1/migrationsBasic Auth

마이그레이션 시 고객, 상품, 구독 정보가 자동으로 생성돼요. 미리 등록할 필요가 없어요.

CSV 파일 준비

CSV 파일에 마이그레이션할 데이터를 작성해요.

CSV 필수 컬럼

컬럼명 타입 필수 설명
order_number String Y 주문번호 (기존 시스템의 주문 식별자)
group String Y "개인" 또는 "그룹"
username String Y 고객 이름
phone String Y 휴대폰 번호 (01012345678 형식)
email String Y 고객 이메일 주소
external_user_id String Y 기존 시스템의 고객 고유 식별자
subscription_payment_date Integer Y 구독 결제일 (1~21 권장)
external_product_id String Y 기존 상품 고유 식별자
product_name String Y 상품명
product_price Integer Y 상품 기본 가격
external_order_subscription_id String Y 기존 구독 주문 고유 식별자
order_name String Y 주문명
price Integer Y 최종 결제 금액
total_duration Integer Y 전체 구독 기간 (개월)
duration Integer Y 현재 회차
quantity Integer Y 구독 수량
service_start_at String Y 서비스 시작일 (YYYY-MM-DD)

요청 파라미터

파라미터 타입 필수 설명
file File 필수 마이그레이션할 데이터가 포함된 CSV 파일
type String 필수 마이그레이션 타입 (subscription: 구독 데이터)

코드 예제

curl -X POST "https://api.bootapi.com/v1/migrations" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@migration_data.csv" \
  -F "type=subscription"bash

응답

성공 응답

{
  "migration_id": "mig_abc123def456",
  "total_records": 150,
  "processed_records": 148,
  "failed_records": 2,
  "created": {
    "users": 50,
    "products": 10,
    "subscriptions": 148
  }
}json

응답 파라미터

파라미터 타입 설명
migration_id String 마이그레이션 작업 고유 ID
total_records Integer CSV 파일의 전체 레코드 수
processed_records Integer 성공적으로 처리된 레코드 수
failed_records Integer 처리 실패한 레코드 수
created Object 생성된 엔티티 수 (users, products, subscriptions)

에러 코드

공통 에러

인증·권한 관련 에러는 커머스 오류코드를 참고해요.

코드 메시지 대처 방법
PG_SYMBOL_EXIST 중복되는 PG Symbol이 있어요. 다른 Symbol을 사용해요. CSV 파일만 업로드 가능해요.
PG_ALIAS_EXIST 사용중인 PG Alias가 있어요. CSV 파일에 필수 컬럼이 포함되어야 해요.
PG_RESOURCE_INVALID 등록된 결제수단의 리소스 정보가 결제 가능한 상태가 아니에요. PG로 부터 받은 결제 정보를 다시한번 확인해요. 각 컬럼의 데이터 형식을 확인해요.
PG_RESOURCE_NOT_FOUND 등록하려는 결제수단의 PG Symbol이 없어요. 다시 확인해요 [ 요청된 symbol - ] 동일한 external_user_id 또는 external_product_id가 중복됐어요.