레퍼런스

양도 코드 상태

양도 객체의 status 값과 상태가 바뀌는 흐름, 판매자 승인(approval) 상태, 구매자용 PIN 전달 링크(share) 상태를 정리했습니다.

양도 상태 (status) #

양도 코드 API가 돌려주는 상태로, 호출한 업체 입장에서 계산됩니다. 같은 코드라도 접수한 업체에는 pending_approval·claimed_by_you, 다른 업체에는 claimed_by_other 로 보입니다. claimable 은 available 일 때만 true 입니다.

상태	의미 · 업체 대응
`waiting_payment` 판매자 입금 대기 대기	판매자가 핀락에 아직 입금하지 않았습니다. 접수할 수 없습니다(PAYMENT_PENDING). 판매자 입금이 확인된 뒤 코드를 다시 확인합니다.
`available` 접수 가능 진행	판매자 입금이 확인되었고 아무 곳에도 접수되지 않았습니다. claimable 이 true 인 유일한 상태입니다. 매물 등록 시점에 코드와 양도 비밀번호로 접수합니다. passwordSet 이 false 면 판매자에게 비밀번호를 먼저 정해 달라고 안내합니다.
`pending_approval` 판매자 승인 대기 대기	이 업체가 접수했고 판매자의 승인을 기다립니다. 다른 곳은 이 코드를 접수할 수 없습니다. 판매자에게 핀락에서 승인해 달라고 안내하고 조회로 기다립니다. 링크는 아직 만들 수 없고(APPROVAL_PENDING), 해제는 할 수 있습니다. approval.expiresAt 까지 승인되지 않거나 판매자가 거절하면 접수가 취소됩니다.
`claimed_by_you` 내가 접수함 진행	판매자가 승인해 이 업체 앞으로 확정되었습니다. claimExpiresAt(승인 + 7일)까지 유효합니다. 매물을 공개하고, 구매자 결제 뒤 링크를 만듭니다. 거래가 깨지면 해제합니다.
`claimed_by_other` 다른 곳에 접수됨 종료	다른 업체가 이미 접수했습니다(승인 대기 포함). 상태 외의 정보는 나오지 않습니다. 매물로 받지 않습니다(ALREADY_CLAIMED).
`delivered` 전달 완료 완료	구매자가 링크를 열어 PIN을 확인했습니다. 끝난 상태입니다. 판매자에게 정산합니다. 링크 생성·해제를 더 할 수 없습니다(ALREADY_DELIVERED · CONFLICT).
`unavailable` 사용 불가 종료	판매자 주문이 취소·환불·환불 심사·실패 등이라 양도할 수 없습니다. 접수하지 않습니다(UNAVAILABLE).

상태 전이 #

양도 상태 흐름

waiting_payment ──판매자 입금 확인──▶ available
available ──────접수(claim)──────▶ pending_approval
pending_approval ──판매자 승인──▶ claimed_by_you
claimed_by_you ──구매자가 링크 열람──▶ delivered

available 로 돌아가는 경우 (이 업체의 transferId 는 404, 열리지 않은 링크는 폐기)
  pending_approval ── 승인 기한 만료 · 판매자 거절 · 해제(release)
  claimed_by_you   ── 해제(release) · 7일 자동 해제

접수 전 판매자 주문 취소·환불 ──▶ unavailable
다른 업체가 먼저 접수 ──▶ (내가 보면) claimed_by_other

판매자는 양도 코드를 바꾸거나 다시 만들 수 없습니다. 접수 중(pending_approval·claimed_by_you)에는 판매자가 주문을 취소·환불할 수도 없습니다.
선점이 풀리면(해제·승인 기한 만료·판매자 거절·7일 자동 해제) 그 업체는 transferId 로 더 이상 조회할 수 없습니다(404). 같은 코드로 다시 거래하려면 판매자에게 코드를 다시 받아 확인부터 시작합니다.
해제 응답은 양도 객체가 아니라 { transferId, status: "released" } 입니다. released 는 이 응답에서만 쓰입니다.
핀락은 상태 변경을 업체 서버로 먼저 알려 주지 않습니다. 승인·전달 완료는 양도 조회로 확인하세요.

방어적으로 처리하세요

예상하지 못한 상태 값을 받아도 오류로 멈추지 말고 "처리 중"으로 보여 주는 등 안전하게 처리하도록 만들어 두세요.

판매자 승인 상태 (approval.status) #

접수한 곳에만 나오는 값입니다. 승인을 기다리는 시간은 핀락 운영 설정을 따르며(기본 30분), 응답의 approval.expiresAt 으로 알 수 있습니다.

`pending`	판매자 승인 대기. 양도 status 는 pending_approval 입니다. approval.expiresAt 까지 승인되지 않으면 접수가 취소됩니다.
`approved`	판매자가 승인함. 양도 status 는 claimed_by_you 이고, claimExpiresAt 이 승인 시각 + 7일로 다시 정해집니다.

양도 객체의 share 는 접수한 업체가 만든 구매자용 PIN 전달 링크의 정보이고, 링크를 만들기 전에는 null 입니다. 판매자의 입금이 이미 확인된 코드만 접수할 수 있으므로 링크는 만든 즉시 ready 입니다. 자세한 사용법은 PIN 전달 링크 만들기를 보세요.

share.status	의미
`ready`	링크를 만든 직후. share.expiresAt(만든 시각 + 24시간)까지 한 번 열 수 있습니다.
`opened`	구매자가 비밀번호를 입력해 PIN을 확인함. 양도는 delivered
`expired`	24시간 안에 열지 않아 만료됨. 새 링크를 만들면 다시 열 수 있습니다.
`locked`	비밀번호를 5번 틀려 잠김. 새 링크를 만들어야 합니다.
`unavailable`	판매자 주문이 환불 심사·실패 등이라 지금은 열 수 없음
`revoked`	폐기된 링크. 판매자 주문이 취소·환불된 경우 등입니다.

링크를 다시 만들면 이전 링크는 바로 폐기되고, 양도 객체에는 새 링크의 정보만 나옵니다.
선점이 풀리면 열리지 않은 링크는 만료 시각이 남아 있어도 폐기됩니다.

양도 상태 (status) #

상태 전이 #

판매자 승인 상태 (approval.status) #

PIN 전달 링크 상태 (share.status) #