연동 준비

인증

모든 /v1 API는 업체 서버에서 API 키를 Bearer 토큰으로 보내 인증합니다. 키의 모드(테스트·운영)에 따라 보이는 데이터가 달라집니다.

인증 헤더 #

모든 요청에 아래 헤더를 넣습니다. 요청·응답 본문은 JSON 입니다.

요청 헤더

Authorization: Bearer pl_live_여기에_API_키

서버에서만 호출하세요

API 키는 비밀번호와 같습니다. 브라우저·모바일 앱에서 직접 호출하면 키가 그대로 노출됩니다. 고객 화면은 업체 서버를 거쳐 핀락을 호출하도록 만드세요.

키 확인하기 #

GET /v1/me 인증: API 키

키가 어느 업체의 어떤 모드 키인지 돌려줍니다. 서버를 배포한 뒤 설정이 맞는지 확인하는 용도로 쓰기 좋습니다.

curl -i https://api.pinlock.app/v1/me \
  -H "Authorization: Bearer $PINLOCK_API_KEY"

const res = await fetch("https://api.pinlock.app/v1/me", {
  headers: { Authorization: `Bearer ${process.env.PINLOCK_API_KEY}` }
});
console.log(res.headers.get("x-pinlock-mode")); // "test" 또는 "live"
console.log(res.headers.get("x-request-id"));   // 문의할 때 함께 알려 주세요
console.log((await res.json()).data);

import os, requests

res = requests.get(
    "https://api.pinlock.app/v1/me",
    headers={"Authorization": f"Bearer {os.environ['PINLOCK_API_KEY']}"},
    timeout=10,
)
print(res.headers.get("x-pinlock-mode"), res.headers.get("x-request-id"))
print(res.json()["data"])

응답 200

{
  "success": true,
  "data": {
    "partnerId": "ptn_…",
    "partnerName": "예시상사",
    "mode": "live",
    "serverTime": "2026-09-23T09:00:00.000Z"
  }
}

키 모드 #

pl_test_… 테스트 키: 테스트 양도 코드만 확인·접수합니다. 실재고·실거래에 영향이 없습니다.
pl_live_… 운영 키: 판매자가 넘겨준 실제 양도 코드만 확인·접수합니다.

두 모드의 데이터는 완전히 분리되어 있습니다. 테스트 키로는 실제 양도 코드를, 운영 키로는 테스트 양도 코드를 찾을 수 없습니다(404 NOT_FOUND). 테스트 전용 API(/v1/test/…)를 운영 키로 부르면 403 FORBIDDEN 입니다.

응답 헤더 #

헤더	설명
`x-pinlock-mode`	요청에 쓴 키의 모드. test 또는 live
`X-Request-Id`	요청마다 붙는 고유 ID. 오류를 문의할 때 함께 알려 주면 빠르게 확인할 수 있습니다.

인증 오류 #

401 UNAUTHORIZED: 헤더가 없거나 형식이 틀렸거나, 없는 키·폐기된 키입니다. 키 값과 Bearer 접두어를 확인하세요.
403 FORBIDDEN: 키는 맞지만 업체 이용이 중지된 상태이거나, 그 키 모드로 쓸 수 없는 API 입니다.

{
  "success": false,
  "code": "UNAUTHORIZED",
  "error": "API 키가 없거나 형식이 올바르지 않습니다. 'Authorization: Bearer pl_test_…' 형식으로 보내 주세요."
}

{
  "success": false,
  "code": "UNAUTHORIZED",
  "error": "유효하지 않거나 폐기된 API 키입니다."
}

{
  "success": false,
  "code": "FORBIDDEN",
  "error": "업체 이용이 중지된 상태입니다. 핀락에 문의하세요."
}

호출 빈도

API 키마다 호출 횟수가 제한됩니다. 넘으면 429 LIMIT_EXCEEDED 가 오니 잠시 뒤 다시 시도하세요. 승인 대기 중인 양도의 상태 조회는 10~30초 간격이면 충분합니다(양도 조회).