개념 배경
PG·솔루션 선택과 계약 판단은 블로그에서 다뤄요. 이 페이지는 기술 마이그레이션 순서 한정.
- PG 선정, 무엇을 보고 결정하나요?
- PG 계약, 뭘 확인하고 사인해야 하나요?
- 결제 연동키·SDK 공통 준비는 결제 SDK 시작하기 를 봐요.
기존 다른 솔루션의 구독 계약, 고객, 상품 정보를 부트페이로 한 번에 옮겨오는 API예요. CSV 파일을 통해 데이터를 일괄 등록하며, 다음 구독회차부터 자동으로 관리돼요.
API 엔드포인트
POST
https://api.bootapi.com/v1/migrationsBasic Auth마이그레이션 시 고객, 상품, 구독 정보가 자동으로 생성돼요. 미리 등록할 필요가 없어요.
CSV 파일 준비
CSV 파일에 마이그레이션할 데이터를 작성해요.
CSV 필수 컬럼
| 컬럼명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| order_number | String | Y | 주문번호 (기존 시스템의 주문 식별자) |
| group | String | Y | "개인" 또는 "그룹" |
| username | String | Y | 고객 이름 |
| phone | String | Y | 휴대폰 번호 (01012345678 형식) |
| 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"bashconst { BootpayCommerce } = require('@bootpay/backend-js');
const fs = require('fs');
const commerce = new BootpayCommerce({
client_key: '{client_key}',
secret_key: '{secret_key}'
});
const response = await commerce.migration.upload({
file: fs.createReadStream('migration_data.csv'),
type: 'subscription'
});
console.log(response);javascriptfrom bootpay_backend.commerce import BootpayCommerce
commerce = BootpayCommerce('{client_key}', '{secret_key}')
with open('migration_data.csv', 'rb') as f:
response = commerce.migration_upload({
'file': f,
'type': 'subscription'
})
print(response)pythonuse Bootpay\ServerPhp\BootpayCommerceApi;
$commerce = new BootpayCommerceApi("{client_key}", "{secret_key}");
$response = $commerce->migration->upload([
'file' => new CURLFile('migration_data.csv'),
'type' => 'subscription'
]);
print_r($response);phpimport kr.co.bootpay.store.BootpayStore;
import kr.co.bootpay.store.model.request.TokenPayload;
import java.io.File;
TokenPayload tokenPayload = new TokenPayload("{client_key}", "{secret_key}");
BootpayStore bootpay = new BootpayStore(tokenPayload);
File file = new File("migration_data.csv");
var response = bootpay.migration.upload(file, "subscription");
System.out.println(response.getData());javacommerce = BootpayStore::Api.new('{client_key}', '{secret_key}')
response = commerce.migration_upload({
file: File.open('migration_data.csv'),
type: 'subscription'
})
puts responserubycommerce := bootpay.NewCommerceApi("{client_key}", "{secret_key}")
file, _ := os.Open("migration_data.csv")
response, err := commerce.Migration.Upload(map[string]interface{}{
"file": file,
"type": "subscription",
})
fmt.Println(response)gousing Bootpay.Commerce;
var commerce = new BootpayCommerceApi("{client_key}", "{secret_key}");
using var fileStream = File.OpenRead("migration_data.csv");
var response = await commerce.Migration.Upload(new {
file = fileStream,
type = "subscription"
});
Console.WriteLine(response);csharp응답
성공 응답
{
"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가 중복됐어요. |
