CreateQR 개발자 매뉴얼

번거로운 과정 없이 QR 생성을 자동화하세요

세 가지 엔드포인트로 QR 코드를 생성, 조회, 삭제하고 스타일도 자유롭게 제어하세요. 당일 연동, 깔끔한 JSON, 그리고 생성한 QR은 대시보드에 그대로 유지됩니다.

API 키 받기 요금제 보기

기본 경로: /api/v1 인증: Authorization: Bearer <key> (권장)

API로 생성한 QR 코드 예시

같은 엔드포인트로도 다양한 스타일을 만들 수 있습니다. 심플하게 유지하거나, 브랜드를 살리거나, 오프라인 캠페인용으로 프레임을 추가해 보세요.

기본형

군더더기 없이 빠른 스캔

고대비

먼 거리에서도 잘 보이도록 설계

브랜드 컬러

테마에 맞춘 캠페인

중앙 로고

기본 워터마크 아이콘

프레임 라벨

포스터용 "SCAN ME"

그라데이션 무드

소셜용 스타일 강화

QR 코드 생성

정적 또는 동적 QR 코드를 생성하고 계정에 저장합니다.

POST https://createqr.app/api/v1/create

JSON만 전송하세요. 키 인증의 경우 헤더 사용이 권장됩니다. 본문의 키 필드는 기존 통합과의 호환성을 위해 제공됩니다.

빠른 시작(cURL)

가장 빠르게 Hello World를 시작하는 방법입니다.

curl -sS -X POST 'https://createqr.app/api/v1/create' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ck_live_XXXXXXXXXXXXXXXXXXXXXXXX' \
  -d '{"data":"https://createqr.app","qrtype":"static"}'

인증 및 호환성

권장: Authorization: Bearer <key>
다음도 허용됨: X-API-Key
JSON 대체 필드: apikey 또는 api_key
Content-Type은 application/json이어야 합니다
POST가 아닌 메서드는 405 method_not_allowed를 반환합니다

기본 매개변수

매개변수	유형	기본값	설명
`apikey`	문자열	`필수`	비밀 API 키입니다. Authorization 헤더(Bearer) 사용을 권장합니다. JSON 본문의 apikey/api_key도 허용됩니다.
`data`	문자열	`필수`	인코딩할 콘텐츠입니다. 동적 QR의 경우 유효한 URL이어야 합니다.
`qrtype`	문자열	`static`	QR 모드: static 또는 dynamic.
`title`	문자열	`선택 사항`	대시보드에 표시되는 QR 제목입니다(120자까지 잘림).
`folderid`	숫자	`선택 사항`	계정에 속한 양의 정수 폴더 ID입니다.

색상 및 모양 매개변수

매개변수	유형	기본값	설명
`transparent`	문자열/불리언	`off`	on/off, true/false, 1/0, yes/no를 허용합니다.
`backcolor`	문자열	`#FFFFFF`	#RRGGBB 형식의 배경 16진수 색상입니다.
`frontcolor`	문자열	`#000000`	#RRGGBB 형식의 기본 점 16진수 색상입니다.
`gradient`	문자열/불리언	`off`	두 가지 색상의 점 그라데이션을 활성화합니다.
`radial`	문자열/불리언	`off`	방사형 그라데이션을 활성화합니다(gradient가 켜져 있을 때 작동).
`gradient_color`	문자열	`#15A97C`	#RRGGBB 형식의 두 번째 그라데이션 색상입니다.
`marker_out_color`	문자열	`#000000`	외부 파인더 마커 색상입니다.
`marker_in_color`	문자열	`#000000`	내부 파인더 마커 색상입니다.
`pattern`	문자열	`default`	본문 점 스타일 프리셋입니다. default circle star diamond sparkle danger cross plus x heart shake blob special-circle-orizz special-circle-vert special-circle special-diamond ribbon oriental ellipse
`marker`	문자열	`default`	외부 마커 스타일 프리셋입니다. default flurry sdoz drop_in drop dropeye dropeyeleft dropeyeleaf dropeyeright squarecircle circle rounded flower flower_in leaf
`marker_in`	문자열	`default`	내부 마커 스타일 프리셋입니다. default flurry sdoz drop_in drop dropeye circle rounded sun star diamond danger cross plus x heart
`optionlogo`	문자열	`none`	none, 권장되는 로컬 SVG 워터마크 경로, 레거시 로컬 PNG 경로 또는 base64 이미지 데이터입니다. none data:image/*;base64,... /images/watermarks/v2/01-link.svg /images/watermarks/v2/02-location.svg /images/watermarks/v2/03-email.svg /images/watermarks/v2/04-whatsapp.svg /images/watermarks/v2/05-wifi.svg /images/watermarks/v2/06-vcard.svg /images/watermarks/v2/07-menu.svg /images/watermarks/v2/08-app.svg /images/watermarks/v2/09-video.svg /images/watermarks/v2/10-feedback.svg /images/watermarks/v2/11-event.svg /images/watermarks/v2/12-coupon.svg /images/watermarks/v2/13-music.svg /images/watermarks/v2/14-social.svg /images/watermarks/v2/15-paypal.svg /images/watermarks/v2/16-bitcoin.svg /images/watermarks/v2/17-scan.svg
`no_logo_bg`	문자열/불리언	`off`	로고 배경판을 비활성화합니다.

프레임 매개변수

매개변수	유형	기본값	설명
`outer_frame`	문자열	`none`	프레임 스타일 프리셋입니다. none bottom top balloon-bottom balloon-top ribbon-bottom ribbon-top phone cine
`framelabel`	문자열	`스캔하세요`	프레임 텍스트 라벨입니다(80자까지 잘림).
`label_font`	문자열	`Arial, Helvetica, sans-serif`	프레임 라벨용 글꼴 스택입니다.
`custom_frame_color`	문자열/불리언	`off`	사용자 지정 프레임 색상을 활성화합니다.
`framecolor`	문자열	`#000000`	#RRGGBB 형식의 프레임 16진수 색상입니다.

생성 요청 예시

예시: 기본 QR

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app",
    "qrtype": "static",
    "title": "Launch Landing QR",
    "transparent": "off",
    "backcolor": "#FFFFFF",
    "frontcolor": "#000000",
    "marker_out_color": "#000000",
    "marker_in_color": "#000000",
    "pattern": "default",
    "marker": "default",
    "marker_in": "default",
    "optionlogo": "none"
}

예시: 컬러 + 로고

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/features",
    "qrtype": "static",
    "title": "Feature Tour QR",
    "transparent": "off",
    "backcolor": "#033895",
    "frontcolor": "#FFFFFF",
    "marker_out_color": "#669DF4",
    "marker_in_color": "#669DF4",
    "pattern": "oriental",
    "marker": "flower",
    "marker_in": "circle",
    "optionlogo": "/images/watermarks/v2/01-link.svg"
}

예시: 프레임 캠페인 QR

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "data": "https://createqr.app/pricing",
    "qrtype": "static",
    "title": "Pricing Poster QR",
    "transparent": "off",
    "frontcolor": "#2B0011",
    "marker_out_color": "#3B0001",
    "marker_in_color": "#3B0001",
    "pattern": "ellipse",
    "marker": "sdoz",
    "marker_in": "sdoz",
    "optionlogo": "none",
    "outer_frame": "balloon-top",
    "framelabel": "SCAN ME",
    "label_font": "Arial, Helvetica, sans-serif",
    "custom_frame_color": "on",
    "framecolor": "#3B0001"
}

성공 응답 엔벌로프

{
    "success": true,
    "data": {
        "qrid": "1284",
        "svg": "<svg ...>...</svg>",
        "type": "static",
        "title": "Pricing Poster QR",
        "dashboard_url": "https://createqr.app/app/qrs/1284",
        "download_url": "https://createqr.app/app/qrs/1284/download/svg"
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

QR 코드 삭제

ID로 QR 코드를 삭제합니다(소유자만 가능).

POST https://createqr.app/api/v1/delete

요청 본문

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "qrid": "1284"
}

응답

{
    "success": true,
    "data": {
        "deleted": true,
        "qrid": "1284"
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

QR 코드 목록

QR 코드를 최신순으로 페이지당 100개씩 조회합니다.

POST https://createqr.app/api/v1/list

페이지네이션은 1부터 시작하세요. 결과는 페이지당 최대 100개 항목을 반환합니다.

요청 본문

{
    "apikey": "ck_live_XXXXXXXXXXXXXXXXXXXXXXXX",
    "pagination": "1"
}

응답

{
    "success": true,
    "data": {
        "pagination": "1",
        "page_size": 100,
        "total": 2,
        "items": [
            {
                "qrid": "1284",
                "title": "Campaign QR",
                "type": "dynamic",
                "created_at": "2026-02-17 09:12:30",
                "short_url": "https://createqr.app/r/a1b2c3",
                "dashboard_url": "https://createqr.app/app/qrs/1284"
            },
            {
                "qrid": "1269",
                "title": "Storefront QR",
                "type": "static",
                "created_at": "2026-02-17 08:02:08",
                "dashboard_url": "https://createqr.app/app/qrs/1269"
            }
        ]
    },
    "request_id": "0f8fad5b-d9cb-469f-a165-70867728950e"
}

오류 응답, 제한 및 재시도

모든 응답에는 request_id가 포함됩니다. 빠르게 디버깅할 수 있도록 지원팀에 문의할 때 이를 함께 전달해 주세요.

일반적인 오류 응답 형식

{
    "success": false,
    "error": {
        "code": "validation_error",
        "message": "Dynamic QR requires a valid URL in data."
    },
    "request_id": "5f5fbd38-f82f-49ad-bf11-f7f04ca9747a"
}

재시도 전략

429 rate_limited: 지터를 포함한 지수 백오프로 재시도하세요.
Retry-After가 있으면 이를 준수하세요.
429 monthly_quota_exceeded: 할당량이 재설정될 때까지 기다리거나 남은 할당량이 있는 키를 사용하세요.
5xx: 시도 횟수 상한을 두고 재시도한 후, 팀에 알리세요.

오류 코드	HTTP	발생 시점	대응 방법
`invalid_api_key`	401	API 키가 없거나 유효하지 않음	Bearer, X-API-Key 또는 JSON 본문 필드를 통해 유효한 키를 제공하세요.
`invalid_content_type`	415	본문이 application/json이 아님	Content-Type: application/json을 전송하세요.
`request_too_large`	413	페이로드가 설정된 제한을 초과함	본문 크기를 줄이세요. 특히 base64 로고를 확인하세요.
`plan_upgrade_required`	403	현재 요금제에서는 API를 사용할 수 없음	결제 페이지에서 Business로 업그레이드하세요.
`validation_error`	422	URL, color 또는 folderid 등의 필드가 유효하지 않음	페이로드 형식을 수정한 후 다시 제출하세요.
`rate_limited`	429	분당 제한에 도달함	지수 백오프로 재시도하고 Retry-After를 준수하세요.
`monthly_quota_exceeded`	429	월간 할당량을 모두 소진함	재설정을 기다리거나 할당량 및 키 설정을 조정하세요.
`qr_not_found`	404	삭제 대상이 없거나 본인 소유가 아님	qrid 소유권을 확인한 후 다시 시도하세요.
`internal_error`	500	예기치 않은 서버 측 문제	백오프로 재시도하고 지원팀 문의를 위해 request_id를 보관하세요.

자주 묻는 질문

통합에서 가장 자주 받는 질문에 대한 짧은 답변입니다.

API 요청은 몇 번까지 실행할 수 있나요?

API는 Business 전용입니다. 월간 할당량은 활성 플랜과 키별 재정의 설정에 따라 결정됩니다. 기본 Business 제공량은 넉넉하며, 관리자는 키별로 세부 조정할 수 있습니다.

JSON 본문에 API 키를 보낼 수 있나요?

예. 헤더 기반 인증을 권장하지만, 호환성을 위해 본문 필드 apikey 또는 api_key도 허용됩니다.

API로 생성한 QR도 대시보드에 표시되나요?

예. 생성에 성공한 모든 QR은 계정에 저장되며 다른 QR과 동일하게 관리할 수 있습니다.

한도에 도달하면 어떻게 되나요?

JSON 오류를 받게 됩니다. 429 응답의 경우 Retry-After를 준수하고 지터를 포함한 지수 백오프를 사용하세요.

다른 계정의 QR을 삭제할 수 있나요?

아니요. 삭제와 목록 조회는 인증된 API 키 소유자 범위로 제한됩니다.

보안 모범 사례

브라우저 JavaScript, 모바일 번들 또는 공개 저장소에 원시 API 키를 절대 노출하지 마세요.
API 키 IP 허용 목록을 사용해 신뢰할 수 있는 서버로만 사용을 제한하세요.
더 빠른 사고 분류를 위해 request_id를 자체 추적 ID와 함께 기록하세요.
정기적으로 키를 교체하고 자격 증명 유출 직후에는 즉시 교체하세요.

API 키 관리자 열기