API 소개

​

할 수 있는 작업

​

가이드

​

기본 URL

https://getqr.com/api/v1

​

버전 관리

• 호환성이 깨지는 변경은 /api/v2/ 같은 새 버전 접두사로 제공되며, /api/v1/은 계속 작동합니다.
• 새로운 선택 필드나 새 엔드포인트 같은 추가 변경은 v1 안에서 이루어질 수 있습니다. 코드가 인식하지 못하는 응답 필드는 무시하세요.

​

빠른 시작

curl https://getqr.com/api/v1/health

curl -X POST "https://getqr.com/api/v1/qrs" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: first-qr-0001" \
  -d '{
    "qrType": "website",
    "data": "https://example.com",
    "title": "Landing page"
  }'

curl "https://getqr.com/api/v1/qrs/{qrId}/download?format=png&resolution=1024" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  --output qr-code.png

​

요청과 응답

• 형식. 요청 본문은 Content-Type: application/json과 함께 JSON으로 보내세요. 예외는 대량 생성의 CSV 업로드로, multipart/form-data를 사용합니다.
• 응답. 응답은 JSON입니다. QR 이미지나 대량 생성 ZIP 아카이브 같은 다운로드는 파일 자체를 반환합니다.
• 날짜. 날짜는 UTC 기준 ISO 8601 문자열입니다. 예: 2026-08-01T10:00:00.000Z.
• 쿼리 매개변수. 불리언 매개변수에는 문자열 true 또는 false를 사용합니다.
• 부분 업데이트. PATCH 엔드포인트는 보낸 필드만 변경합니다.
• 민감한 정보. 응답에는 비밀번호나 내부 식별자가 포함되지 않습니다. 비밀번호로 보호된 QR 코드는 passwordProtected: true만 반환합니다.
• 워크스페이스. 모든 요청은 API 키가 속한 워크스페이스에서 실행됩니다. 워크스페이스 ID를 전달할 필요가 없습니다. 접근 권한 및 역할을 참조하세요.
• 오류. 실패한 요청은 고정된 code가 담긴 error 객체를 반환합니다. 오류를 참조하세요.

​

페이지네이션

{
  "data": [ … ],
  "pagination": { "page": 1, "pageSize": 50, "total": 128, "hasMore": true }
}

​

멱등성

-H "Idempotency-Key: order-4821-qr"

• 24시간 안에 같은 키로 요청을 반복하면 두 번째 QR 코드를 만들지 않고 원래 응답을 반환합니다.
• 응답 헤더 x-idempotent-replay는 재생된 응답에서는 true, 새 응답에서는 false입니다.
• 해당 키의 첫 번째 요청이 아직 처리 중이면 API는 409 conflict를 반환합니다. 처리가 끝난 뒤 다시 시도하세요.
• 같은 키를 다른 요청 본문과 함께 다시 사용하면 422 unprocessable_entity를 반환합니다.
• 헤더가 없으면 30초 안에 보낸 동일한 요청 본문은 중복으로 처리됩니다.

​

요청 한도

​

추후 제공 예정

​

다음 단계