인증서 검증

POST /certificates/verify

인증서의 진위 여부를 검증합니다. 이미지 업로드 또는 txHash / itemId 중 하나를 사용합니다.

요청 형식: multipart/form-data

필드	타입	설명
`image`	file	검증할 인증서 이미지 (image 또는 q 중 하나 필수)
`q`	string (query)	트랜잭션 해시 (`0x...`) 또는 발급 이력 ID (UUID)

이미지와 q가 동시에 전달되면 이미지가 우선 적용됩니다.

HMAC 서명

multipart 요청 시 BODY_HASH = SHA256("") (빈 문자열 해시)를 사용합니다.
쿼리스트링(?q=...)은 서명 경로에서 제외합니다. PATH = /certificates/verify

TypeScript (이미지)
TypeScript (txHash)
Python (이미지)
Python (txHash)

const timestamp = String(Date.now());
const bodyHash = crypto.createHash('sha256').update('').digest('hex');
const stringToSign = `POST\n/certificates/verify\n${timestamp}\n${bodyHash}`;
const signature = crypto.createHmac('sha256', apiSecret).update(stringToSign).digest('hex');

const formData = new FormData();
formData.append('image', imageFile);

const res = await fetch('https://api.koreabaas.co.kr/certificates/verify', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body: formData,
});

const timestamp = String(Date.now());
const bodyHash = crypto.createHash('sha256').update('').digest('hex');
const stringToSign = `POST\n/certificates/verify\n${timestamp}\n${bodyHash}`;
const signature = crypto.createHmac('sha256', apiSecret).update(stringToSign).digest('hex');

const res = await fetch('https://api.koreabaas.co.kr/certificates/verify?q=0xabc123...', {
  method: 'POST',
  headers: {
    'X-API-Key': apiKey,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
});

timestamp, sig = sign('POST', '/certificates/verify', body=None)

with open('certificate.png', 'rb') as f:
    result = requests.post(
        'https://api.koreabaas.co.kr/certificates/verify',
        headers={'X-API-Key': API_KEY, 'X-Timestamp': timestamp, 'X-Signature': sig},
        files={'image': f},
    ).json()

tx_hash = '0xd97fc363...'
timestamp, sig = sign('POST', '/certificates/verify', body=None)

result = requests.post(
    f'https://api.koreabaas.co.kr/certificates/verify?q={tx_hash}',
    headers={'X-API-Key': API_KEY, 'X-Timestamp': timestamp, 'X-Signature': sig},
).json()

응답

검증 성공 (verified: true)

{
  "success": true,
  "data": {
    "verified": true,
    "documentHash": "6b7fa434f92a8b80aab02d9bf1a12e49ffcae424e4013a1c4f68b67e3d2bbcd0",
    "issuedAt": "2024-01-01T09:00:00.000Z",
    "issuer": "블록오디세이",
    "status": "valid",
    "contractName": "졸업 증명서",
    "contractType": "sbt",
    "to": "0x1111111111111111111111111111111111111111",
    "tokenId": "42",
    "transactionHash": "0xd97fc363...",
    "verifiedAt": "2024-06-01T00:00:00.000Z"
  }
}

검증 실패 (verified: false)

{
  "success": true,
  "data": {
    "verified": false,
    "verifiedAt": "2024-06-01T00:00:00.000Z"
  }
}

응답 필드

필드	설명
`verified`	검증 성공 여부
`documentHash`	인증서 이미지 SHA-256 해시 (이미지 발급 건만)
`issuedAt`	발급 일시
`issuer`	발급 기관명
`status`	`valid` (유효) / `revoked` (폐기됨)
`contractName`	인증서 컨트랙트 이름
`contractType`	컨트랙트 타입 (`erc721`, `sbt` 등)
`to`	수신자 지갑 주소
`tokenId`	토큰 ID
`transactionHash`	발급 트랜잭션 해시
`verifiedAt`	검증 수행 일시

응답​

응답