레퍼런스
API 레퍼런스
양도 코드 연동 API의 모든 엔드포인트와 양도·상품·키 정보 객체의 필드를 한 페이지에 정리했습니다.
공통 규칙 #
| 기본 주소 | https://api.pinlock.app |
| 인증 | Authorization: Bearer <API 키> |
| 형식 | JSON (Content-Type: application/json) |
| 응답 헤더 | x-pinlock-mode: test | live, X-Request-Id |
| 시각 | ISO 8601, UTC (예: 2026-09-23T09:00:00.000Z) |
| 금액 | 원 단위 정수 |
응답 형식
// 성공
{ "success": true, "data": { … }, "meta": { … } }
// 실패
{ "success": false, "code": "ALREADY_CLAIMED", "error": "한국어 메시지", "meta": { … } }오류는 code 로 구분하세요. 전체 목록은 오류 코드에 있습니다.
엔드포인트 #
| 요청 |
|---|
GET / 키 확인 — 업체·모드·서버 시각 |
GET / 양도 코드 확인 (선점하지 않음, claimable 로 중복 등록 방지) |
POST / 양도 코드 접수(선점) 요청 — 코드 + 양도 비밀번호. 성공하면 판매자 승인 대기(pending_approval) |
GET / 양도 조회 (접수한 업체만) — 승인·전달 완료 확인 |
POST / 구매자용 PIN 전달 링크 생성 (판매자 승인 뒤, 이전 링크 즉시 폐기) |
POST / 선점 해제 (링크 폐기, 판매자가 코드를 다시 쓸 수 있음) |
POST / 테스트 양도 코드 발급 (테스트 키 전용) |
POST / 판매자 승인 시뮬레이션 (테스트 키 전용) |
GET / 상품 목록 — 테스트 양도 코드를 만들 때 쓸 상품 ID 조회 |
GET / 상품 하나 조회 |
핀락이 업체 서버로 보내는 요청은 없습니다
판매자 승인과 PIN 전달 완료는 양도 조회 API로 확인합니다. PIN은 구매자가 PIN 전달 링크를 열어 직접 확인하고, 업체
서버로는 전달되지 않습니다.
양도 객체 #
양도 코드 확인·접수·조회·링크 생성 응답의 data 가 이 형식입니다. 해제 응답은 { transferId, status: "released" } 입니다. 다른 업체가
접수했거나(claimed_by_other) 이미 전달이 끝난 코드를 확인하면 transferId·mode·status·claimable 만
옵니다. 자세한 내용은 양도 코드와 양도 코드 상태를 보세요.
Transfer
| 필드 | 설명 |
|---|---|
transferId string | 양도 건 ID(trf_…) |
mode "live" | "test" | 실주문 코드인지 테스트 코드인지. 키 모드와 항상 같습니다. |
status string | waiting_payment · available · pending_approval · claimed_by_you · claimed_by_other · delivered · unavailable (양도 코드 상태 문서 참고) |
claimable boolean | 지금 접수할 수 있는지. status 가 available 일 때만 true — false 면 접수하지 마세요. |
passwordSet boolean | 판매자가 양도 비밀번호를 정했는지. false 면 접수가 PASSWORD_NOT_SET 으로 거절됩니다. |
items[] { productName, faceValue, quantity }[] | 판매자 주문의 상품·액면가·수량 |
faceTotal number | 액면가 합계(원) |
paidAt string | null | 판매자의 핀락 입금 확인 시각 |
codeLast4 string | 코드 끝 4자리 |
externalRef string | null | 접수 때 보낸 업체 매물·거래 번호 (접수한 곳에만) |
claimedAt string | 접수 시각 (접수한 곳에만) |
approval. "pending" | "approved" | 판매자 승인 상태 (접수한 곳에만) |
approval. string | null | 접수(승인 요청) 시각 |
approval. string | null | 승인 기한. 이때까지 승인되지 않으면 접수가 자동 취소됩니다. |
approval. string | null | 판매자가 승인한 시각 |
claimExpiresAt string | 선점 만료 시각. 승인되면 승인 시각 + 7일로 다시 정해집니다. 지나면 자동 해제 (접수한 곳에만) |
deliveredAt string | null | 구매자가 PIN을 확인한 시각 (접수한 곳에만) |
share object | null | 구매자용 PIN 전달 링크. 링크를 만들기 전에는 null (접수한 곳에만) |
share. string | ready · opened · expired · locked · revoked · unavailable (양도 코드 상태 문서 참고) |
share. string | PIN 전달 링크. 링크 생성 응답에만 있고 조회 응답에는 없습니다. |
share. string | 링크 만료 시각 = 링크를 만든 시각 + 24시간 |
share. string | null | 구매자가 링크를 열어 PIN을 확인한 시각 |
share. number | 비밀번호를 틀린 횟수. 5회면 locked |
share. string | 현재 링크를 만든 시각(새로 만들면 바뀜) |
상품 객체 #
GET /v1/products·GET /v1/products/{productId} 응답의 data 입니다(목록은 배열). 양도 연동에서는 테스트 양도 코드를 만들 때 상품 ID를 고르는 데만 씁니다. 판매 중이 아닌 상품 ID로 조회하면 404 입니다.
아래는 양도 연동에 필요한 필드만 정리했습니다.
Product
| 필드 | 설명 |
|---|---|
id string | 상품 ID. POST /v1/test/transfers 의 items[].productId 에 넣습니다. |
name string | 상품 이름 |
brand { slug, name } | 브랜드 |
faceValue number | 액면가(원) |
validityMonths number | 유효기간(개월) |
maxQuantity number | 상품별 한 번에 담을 수 있는 최대 수량. 넘으면 422 LIMIT_EXCEEDED |
orderableQuantity number | 지금 담을 수 있는 수량. 테스트 키로 조회하면 항상 maxQuantity 입니다. |
inStock boolean | 지금 담을 수 있는지 |
키 정보 (GET /v1/me) #
Me
| 필드 | 설명 |
|---|---|
partnerId string | 업체 ID |
partnerName string | 업체 이름 |
mode "test" | "live" | 키 모드 |
serverTime string | 핀락 서버 시각(ISO 8601, UTC). 서버 시계 점검에 쓸 수 있습니다. |