파일 - GetQR Docs

GetQR API는 베타 버전이며 일부 워크스페이스에서만 사용할 수 있습니다. 정식 출시 전에 세부 사항이 변경될 수 있습니다.

PDF, Image, Video QR 코드는 파일을 가리키며, 직접 만든 로고도 파일입니다. 업로드는 두 단계로 진행됩니다. 파일을 등록하여 URL을 받은 다음, 그 URL로 파일 바이트를 보냅니다.

메서드	경로	설명
`POST`	`/api/v1/files`	파일 업로드 등록

파일 업로드

파일 등록

파일의 target, contentType, size를 담아 파일 업로드 등록을 호출합니다. target에 따라 허용되는 콘텐츠 타입과 크기 제한이 정해집니다. fileId와 uploadUrl을 받습니다.

파일 보내기

uploadUrl로 PUT 요청을 보내 파일을 전송합니다. Content-Type과 Content-Length는 등록한 contentType, size와 정확히 일치해야 하며, 그렇지 않으면 거부됩니다. URL은 사전 서명되어 있으므로 API 키를 추가하지 마세요. URL은 10분 후에 만료됩니다.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @menu.pdf

파일 ID 사용

QR 코드를 생성할 때 fileId를 전달합니다.

pdf, image, video QR 코드의 fileId로 사용합니다. 일치하는 용도로 업로드하세요.
vcard, social, multilink, event QR 코드 프로필 이미지의 fileId로 사용합니다. logo 용도로 업로드하세요.
직접 만든 로고에는 logoOptions.type을 uploaded로 설정하고 logoOptions.fileId로 사용합니다. logo 용도로 업로드하세요. 맞춤 설정을 참조하세요.

제한

`target`	허용되는 콘텐츠 타입	최대 크기
`pdf`	`application/pdf`	20 MB(20,971,520바이트)
`image`	`image/*`	5 MB(5,242,880바이트)
`video`	`video/*`	50 MB(52,428,800바이트)
`logo`	`image/*`	5 MB(5,242,880바이트)

매개변수 없는 MIME 타입. image/png처럼 소문자 타입과 하위 타입 하나만 보내세요. ;charset= 같은 매개변수나 목록은 거부됩니다.
SVG 불가. image/svg+xml 같은 XML 기반 타입은 허용되지 않습니다. image/png나 image/jpeg 같은 래스터 이미지를 업로드하세요.

헤더

string

필수

Bearer 뒤에 API 키를 붙입니다. 인증을 참조하세요.

string

필수

application/json.

파일 업로드 등록

POST /api/v1/files 파일을 등록하고 업로드할 사전 서명된 URL을 반환합니다. 이 호출 자체는 파일을 업로드하지 않습니다.

string

필수

파일의 용도: pdf, image, video, logo. 허용되는 콘텐츠 타입과 크기 제한이 정해집니다. 제한을 참조하세요.

string

필수

매개변수 없는 파일의 MIME 타입입니다. 예: application/pdf. 업로드 요청은 정확히 이 Content-Type을 보내야 합니다.

integer

필수

바이트 단위의 정확한 파일 크기로, 양의 정수입니다. 용도별 제한과 대조됩니다. 업로드 요청은 정확히 이 Content-Length를 보내야 합니다.

string

원본 파일 이름으로, 최대 255자입니다. 대시보드 표시용으로 보관됩니다. / 또는 \가 포함된 경로는 거부됩니다.

string

fileId 또는 logoOptions.fileId로 전달할 ID입니다.

string

파일을 PUT할 사전 서명된 URL입니다.

integer

uploadUrl이 만료될 때까지 남은 초: 600.

string

업로드에 사용할 HTTP 메서드: PUT.

curl -X POST "https://getqr.com/api/v1/files" \
  -H "Authorization: Bearer $GETQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "pdf",
    "contentType": "application/pdf",
    "size": 248000,
    "name": "menu.pdf"
  }'

{
  "fileId": "file_7bQ2xR9mKp",
  "uploadUrl": "https://storage.getqr.com/qrs-content/pdf/file_7bQ2xR9mKp?X-Amz-...",
  "expiresIn": 600,
  "method": "PUT"
}

자주 발생하는 문제

422 "Content type … is not allowed for target"

콘텐츠 타입이 용도와 맞지 않습니다. 예를 들어 pdf는 application/pdf만 받습니다. 제한을 참조하세요.

422 "must be a single lowercase type/subtype"

콘텐츠 타입은 소문자로, 매개변수 없이 보내세요. Image/PNG나 image/png; charset=utf-8이 아니라 image/png입니다.

422 "File is too large for target"

선언한 size가 용도별 제한을 초과합니다. 등록하기 전에 파일을 압축하세요.

uploadUrl로의 업로드가 실패합니다

URL은 파일을 등록하고 10분 후에 만료되며, 요청은 등록한 Content-Type과 Content-Length를 정확히 보내야 합니다. 새 URL을 받으려면 파일을 다시 등록하세요.

QR 코드 생성 시 422 "is registered but its content was never uploaded"

파일을 등록했지만 uploadUrl로의 PUT이 완료되지 않았습니다. 파일을 업로드한 다음 QR 코드를 만드세요.

QR 코드 생성 시 422 "was uploaded to …"

파일이 다른 용도로 등록되었습니다. 예를 들어 pdf QR 코드에 image 파일을 사용한 경우입니다. 일치하는 용도로 새 업로드를 등록하세요.

QR 코드 생성 시 404 "File … was not found"

해당 fileId가 존재하지 않습니다. 파일 업로드 등록의 응답에서 가져오세요.

API

파일

파일 업로드

제한

헤더

파일 업로드 등록

자주 발생하는 문제

다음 단계

QR 코드

QR 코드 유형

맞춤 설정

오류

​파일 업로드

​제한

​헤더

​파일 업로드 등록

​자주 발생하는 문제

​다음 단계

QR 코드

QR 코드 유형

맞춤 설정

오류

파일 업로드

제한

헤더

파일 업로드 등록

자주 발생하는 문제

다음 단계