양도 코드

curl https://api.pinlock.app/v1/transfers/code/PLX-7K2M-Q9TB-4XWN \
  -H "Authorization: Bearer $PINLOCK_API_KEY"

// 판매자가 입력한 코드. 하이픈·대소문자는 핀락이 알아서 맞춥니다
const code = input.transferCode.trim();

const res = await fetch(`https://api.pinlock.app/v1/transfers/code/${encodeURIComponent(code)}`, {
  headers: { Authorization: `Bearer ${process.env.PINLOCK_API_KEY}` }
});
const body = await res.json();
if (!body.success) throw new Error(`${body.code}: ${body.error}`); // 404 NOT_FOUND 면 코드를 다시 확인해 달라고 안내

const transfer = body.data;
if (!transfer.claimable) {
  // 이미 다른 곳에 접수됨, 입금 전, 전달 완료 등 — 매물로 받지 않습니다
  return rejectListing(transfer.status);
}
// 상품·수량·액면가가 판매자가 올리려는 매물과 같은지 확인합니다
assertSameAsListing(transfer.items, transfer.faceTotal);

import os, requests
from urllib.parse import quote

code = form["transfer_code"].strip()  # 하이픈·대소문자는 핀락이 알아서 맞춥니다

res = requests.get(
    f"https://api.pinlock.app/v1/transfers/code/{quote(code)}",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_API_KEY']}"},
    timeout=10,
)
body = res.json()
if not body["success"]:
    raise RuntimeError(f"{body['code']}: {body['error']}")  # 404 NOT_FOUND 면 코드를 다시 확인해 달라고 안내

transfer = body["data"]
if not transfer["claimable"]:
    # 이미 다른 곳에 접수됨, 입금 전, 전달 완료 등 — 매물로 받지 않습니다
    reject_listing(transfer["status"])
# 상품·수량·액면가가 판매자가 올리려는 매물과 같은지 확인합니다
assert_same_as_listing(transfer["items"], transfer["faceTotal"])

curl -X POST https://api.pinlock.app/v1/transfers/claim \
  -H "Authorization: Bearer $PINLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "PLX-7K2M-Q9TB-4XWN", "password": "482913", "externalRef": "listing-58213" }'

const res = await fetch("https://api.pinlock.app/v1/transfers/claim", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PINLOCK_API_KEY}`,
    "Content-Type": "application/json"
  },
  // password: 판매자가 정한 양도 비밀번호(6자리). 저장하지 말고 이 요청에만 씁니다
  body: JSON.stringify({ code, password: sellerPassword, externalRef: listing.id })
});
const body = await res.json();

if (!body.success) {
  // WRONG_PASSWORD(401) · LOCKED(423) · PASSWORD_NOT_SET → 판매자에게 비밀번호를 다시 확인
  // ALREADY_CLAIMED · ALREADY_DELIVERED · PAYMENT_PENDING · UNAVAILABLE → 매물 등록을 막습니다
  return rejectListing(body.code);
}
// 이 transferId 로 이후 링크 생성·조회·해제를 합니다. 코드 원문은 저장하지 않아도 됩니다
await db.saveTransfer(listing.id, body.data.transferId, body.data.claimExpiresAt);

res = requests.post(
    "https://api.pinlock.app/v1/transfers/claim",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_API_KEY']}"},
    # password: 판매자가 정한 양도 비밀번호(6자리). 저장하지 말고 이 요청에만 씁니다
    json={"code": code, "password": seller_password, "externalRef": listing["id"]},
    timeout=10,
)
body = res.json()

if not body["success"]:
    # WRONG_PASSWORD(401) · LOCKED(423) · PASSWORD_NOT_SET → 판매자에게 비밀번호를 다시 확인
    # ALREADY_CLAIMED · ALREADY_DELIVERED · PAYMENT_PENDING · UNAVAILABLE → 매물 등록을 막습니다
    reject_listing(body["code"])
else:
    # 이 transferId 로 이후 링크 생성·조회·해제를 합니다. 코드 원문은 저장하지 않아도 됩니다
    db.save_transfer(listing["id"], body["data"]["transferId"], body["data"]["claimExpiresAt"])

curl https://api.pinlock.app/v1/transfers/trf_여기에_ID \
  -H "Authorization: Bearer $PINLOCK_API_KEY"

// 링크를 만든 거래만 30~60초마다 확인합니다
for (const deal of await db.findDealsWaitingForDelivery()) {
  const res = await fetch(`https://api.pinlock.app/v1/transfers/${deal.transferId}`, {
    headers: { Authorization: `Bearer ${process.env.PINLOCK_API_KEY}` }
  });
  const body = await res.json();

  if (res.status === 404) {
    // 선점이 풀림(7일 자동 해제 또는 해제) — 거래를 멈추고 판매자·구매자에게 알립니다
    await db.markDealReleased(deal.id);
    continue;
  }
  if (!body.success) continue; // 일시 오류는 다음 주기에

  const transfer = body.data;
  if (transfer.status === "delivered") {
    await db.markDelivered(deal.id, transfer.deliveredAt);
    await settleToSeller(deal); // 구매자가 PIN을 확인했으니 판매자에게 정산
  } else if (transfer.share && ["expired", "locked"].includes(transfer.share.status)) {
    await askBuyerToRequestNewLink(deal); // 새 링크를 만들어 다시 보여 줍니다
  }
}

# 링크를 만든 거래만 30~60초마다 확인합니다
for deal in db.find_deals_waiting_for_delivery():
    res = requests.get(
        f"https://api.pinlock.app/v1/transfers/{deal['transfer_id']}",
        headers={"Authorization": f"Bearer {os.environ['PINLOCK_API_KEY']}"},
        timeout=10,
    )
    if res.status_code == 404:
        # 선점이 풀림(7일 자동 해제 또는 해제) — 거래를 멈추고 판매자·구매자에게 알립니다
        db.mark_deal_released(deal["id"])
        continue
    body = res.json()
    if not body["success"]:
        continue  # 일시 오류는 다음 주기에

    transfer = body["data"]
    if transfer["status"] == "delivered":
        db.mark_delivered(deal["id"], transfer["deliveredAt"])
        settle_to_seller(deal)  # 구매자가 PIN을 확인했으니 판매자에게 정산
    elif transfer["share"] and transfer["share"]["status"] in ("expired", "locked"):
        ask_buyer_to_request_new_link(deal)  # 새 링크를 만들어 다시 보여 줍니다

curl -X POST https://api.pinlock.app/v1/transfers/trf_여기에_ID/share-link \
  -H "Authorization: Bearer $PINLOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sharePassword": "7K2m9Q" }'

import { randomInt } from "node:crypto";

// 구매자 결제가 확인된 뒤에만 호출합니다
const ALPHABET = "ABCDEFGHJKMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789";
const sharePassword = Array.from({ length: 8 }, () => ALPHABET[randomInt(ALPHABET.length)]).join("");

const res = await fetch(`https://api.pinlock.app/v1/transfers/${deal.transferId}/share-link`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PINLOCK_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ sharePassword })
});
const body = await res.json();
if (!body.success) throw new Error(`${body.code}: ${body.error}`);

// share.url 은 이 응답에서만 받을 수 있습니다. 암호화해 저장하고 구매자 화면에만 보여 줍니다
await db.saveBuyerLink(deal.id, encrypt(body.data.share.url), encrypt(sharePassword), body.data.share.expiresAt);

import secrets, string

# 구매자 결제가 확인된 뒤에만 호출합니다
alphabet = string.ascii_letters + string.digits
share_password = "".join(secrets.choice(alphabet) for _ in range(8))

res = requests.post(
    f"https://api.pinlock.app/v1/transfers/{deal['transfer_id']}/share-link",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_API_KEY']}"},
    json={"sharePassword": share_password},
    timeout=10,
)
body = res.json()
if not body["success"]:
    raise RuntimeError(f"{body['code']}: {body['error']}")

# share.url 은 이 응답에서만 받을 수 있습니다. 암호화해 저장하고 구매자 화면에만 보여 줍니다
db.save_buyer_link(deal["id"], encrypt(body["data"]["share"]["url"]), encrypt(share_password), body["data"]["share"]["expiresAt"])

curl -X POST https://api.pinlock.app/v1/transfers/trf_여기에_ID/release \
  -H "Authorization: Bearer $PINLOCK_API_KEY"

const res = await fetch(`https://api.pinlock.app/v1/transfers/${deal.transferId}/release`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.PINLOCK_API_KEY}` }
});
const body = await res.json();
if (!body.success) {
  // 409 CONFLICT — 그 사이 구매자가 PIN을 열었을 수 있습니다. 조회해서 delivered 인지 확인합니다
  throw new Error(`${body.code}: ${body.error}`);
}
await db.markDealReleased(deal.id); // body.data.status === "released"

res = requests.post(
    f"https://api.pinlock.app/v1/transfers/{deal['transfer_id']}/release",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_API_KEY']}"},
    timeout=10,
)
body = res.json()
if not body["success"]:
    # 409 CONFLICT — 그 사이 구매자가 PIN을 열었을 수 있습니다. 조회해서 delivered 인지 확인합니다
    raise RuntimeError(f"{body['code']}: {body['error']}")
db.mark_deal_released(deal["id"])  # body["data"]["status"] == "released"

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); // "PLX-…" — 판매자가 넘겨준 코드처럼 쓰면 됩니다

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"])  # 판매자가 넘겨준 코드·비밀번호처럼 쓰면 됩니다 (테스트 비밀번호는 항상 246813)