테스트 모드

테스트 모드란 #

pl_test_ 로 시작하는 테스트 키로 호출하면 모든 요청이 테스트 모드로 처리됩니다. API 주소와 요청·응답 형식은 운영과 같으므로, 키만 바꾸면 같은 코드로 운영에 연결할 수 있습니다. 응답 헤더 x-pinlock-mode: test 나 GET /v1/me 의 mode 로도 확인할 수 있습니다.

운영과 다른 점 #

상품 ID 고르기 #

테스트 양도 코드를 만들려면 어떤 상품권을 넘겨받은 상황인지 정해야 합니다. 상품 목록에서 id 를 골라 아래 발급 요청의 items[].productId 에 넣으세요. 상품 하나는 GET /v1/products/{productId} 로 조회합니다. 필드는 상품 객체를 보세요.

curl https://api.pinlock.app/v1/products \
  -H "Authorization: Bearer $PINLOCK_TEST_API_KEY"

const res = await fetch("https://api.pinlock.app/v1/products", {
  headers: { Authorization: `Bearer ${process.env.PINLOCK_TEST_API_KEY}` }
});
const { data } = await res.json();
const product = data.find((item) => item.inStock);
console.log(product.id, product.name, product.faceValue); // 테스트 양도 코드 발급에 쓸 상품 ID

테스트 양도 코드 발급 #

판매자가 코드와 양도 비밀번호를 넘겨준 상황을 만듭니다. 입금이 끝난 테스트 주문과 그 양도 코드를 한 번에 만들어 transferCode 와 transferPassword 로 돌려주므로, 바로 코드 확인·접수부터 시험할 수 있습니다. 응답은 201 입니다.

• 본문은 { "items": [{ "productId": "…", "quantity": 1 }] } 형식입니다. 상품은 1~10종, 수량은 상품별 1 이상 maxQuantity 이하입니다.
• 같은 상품을 두 줄로 보내거나 판매 중이 아닌 상품이면 422 VALIDATION_ERROR, 최대 수량을 넘으면 422 LIMIT_EXCEEDED 입니다.
• 운영 키로 호출하면 403 FORBIDDEN 입니다.

curl -X POST https://api.pinlock.app/v1/test/transfers \
  -H "Authorization: Bearer $PINLOCK_TEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "items": [{ "productId": "prd_여기에_상품_ID", "quantity": 1 }] }'

const res = await fetch("https://api.pinlock.app/v1/test/transfers", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PINLOCK_TEST_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ items: [{ productId: "prd_여기에_상품_ID", quantity: 1 }] })
});
const { data } = await res.json();
console.log(data.transferCode, data.transferPassword); // "PLX-…" "246813"

res = requests.post(
    "https://api.pinlock.app/v1/test/transfers",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_TEST_API_KEY']}"},
    json={"items": [{"productId": "prd_여기에_상품_ID", "quantity": 1}]},
    timeout=10,
)
data = res.json()["data"]
print(data["transferCode"], data["transferPassword"])  # "PLX-…" "246813"

{
  "success": true,
  "data": { "transferCode": "PLX-3HRT-8QZC-M2VK", "transferPassword": "246813" }
}

테스트 양도 비밀번호 #

테스트 코드의 양도 비밀번호는 항상 246813 입니다. 접수(POST /v1/transfers/claim)의 password 에 이 값을 넣으세요. 다른 값을 넣으면 운영과 똑같이 401 WRONG_PASSWORD 가 오고, 5번 틀리면 그 코드는 60분 동안 423 LOCKED 입니다. 잠금을 기다리기 싫다면 새 테스트 코드를 발급하세요.

판매자 승인 시뮬레이션 #

테스트 코드에는 승인해 줄 판매자가 없으므로, 접수(pending_approval) 뒤 이 API로 판매자가 승인한 것처럼 처리합니다. 요청 본문은 없고, 응답은 status: "claimed_by_you", approval.status: "approved" 인 양도 객체입니다. claimExpiresAt 은 승인 시각 + 7일로 다시 정해집니다.

• 호출하지 않으면 운영처럼 approval.expiresAt 이 지나 접수가 취소되는 흐름을 시험할 수 있습니다.
• 승인 대기가 아닌 건(이미 승인됨·전달 완료 등)은 409 CONFLICT, 이 업체가 접수하지 않았거나 선점이 풀린 건은 404, 운영 키는 403 FORBIDDEN 입니다.

curl -X POST https://api.pinlock.app/v1/test/transfers/trf_…/approve \
  -H "Authorization: Bearer $PINLOCK_TEST_API_KEY"

const res = await fetch(`https://api.pinlock.app/v1/test/transfers/${transferId}/approve`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PINLOCK_TEST_API_KEY}` }
});
const { data } = await res.json();
console.log(data.status, data.approval.status); // "claimed_by_you" "approved" → 이제 링크를 만들 수 있음

res = requests.post(
    f"https://api.pinlock.app/v1/test/transfers/{transfer_id}/approve",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_TEST_API_KEY']}"},
    timeout=10,
)
data = res.json()["data"]
print(data["status"], data["approval"]["status"])  # claimed_by_you approved

테스트 링크 열기 · 테스트 PIN #

승인 뒤 PIN 전달 링크를 만들고, 응답의 share.url 을 브라우저에서 열어 sharePassword 로 넣은 비밀번호를 입력하면 무작위 테스트 PIN(TEST-xxxx-xxxx-xxxx)이 한 번 표시되고 양도가 delivered 가 됩니다. 테스트 PIN은 실제 상품권으로 쓸 수 없습니다.

• 열람 규칙(만든 시각부터 24시간, 1회 열람, 5회 틀리면 locked)은 운영과 같습니다.
• 테스트 링크가 실제 구매자에게 전달되지 않도록 양도 객체의 mode 나 응답 헤더 x-pinlock-mode 를 확인하세요.

확인해 볼 시나리오 #

1. 상품 조회 → 테스트 코드 발급 → 코드 확인(claimable: true, passwordSet: true) → 접수(password: 246813, 201 pending_approval) → 승인 시뮬레이션 → 조회로 claimed_by_you 확인 → 링크 생성 → 링크 열기 → 조회로 delivered 확인
2. 승인 시뮬레이션 전에 링크를 만들면 409 APPROVAL_PENDING 이고 meta.approvalExpiresAt 이 오는지 확인
3. 승인 시뮬레이션을 하지 않고 approval.expiresAt 을 넘기면 transferId 조회가 404 이고, 코드 확인 결과가 다시 available 인지 확인
4. 틀린 양도 비밀번호로 접수해 401 WRONG_PASSWORD 와 meta.attemptsLeft 가 오는지, 5번 틀리면 423 LOCKED 인지 확인
5. 같은 코드로 접수를 동시에 두 번 보내 한쪽만 201 이고 다른 쪽은 409 ALREADY_CLAIMED 인지, 그 뒤 코드 확인 결과가 pending_approval 인지 확인
6. 접수 응답을 받지 못한 상황을 가정해 같은 코드로 다시 접수하면 같은 transferId 가 오는지 확인
7. 하이픈 없이·소문자로 코드를 보내도 같은 양도 건으로 확인되는지, 형식이 틀리면 422, 없는 코드면 404 인지 확인
8. 링크를 두 번 만들어 이전 링크가 열리지 않는지 확인
9. 해제(release) 후 링크가 열리지 않고, 코드 확인 결과가 다시 available 이며, transferId 조회는 404 인지 확인
10. 전달 완료(delivered) 뒤 접수·링크 생성은 409 ALREADY_DELIVERED, 해제는 409 CONFLICT 인지 확인
11. 로그·오류 추적 도구에 양도 코드, 양도 비밀번호, sharePassword, share.url 이 남지 않는지 확인

모두 확인했다면 운영 전환 체크리스트로 넘어가세요.