HonestQR API v1

QR코드 생성과 스캔 통계 조회를 프로그래밍 방식으로 할 수 있습니다. 먼저 대시보드(API 키 섹션)에서 API 키를 발급받아 Bearer 토큰으로 전달하세요.

기본 URL: https://qr.zalize.com

인증: Authorization: Bearer hqr_…

요청 제한: API 키당 분당 60회 요청(초과 시 HTTP 429).

정적 QR코드 렌더링

GET /api/v1/static — 이미지를 바로 반환합니다. 아무것도 저장되지 않으며 정적 코드는 만료되지 않습니다. 쿼리 파라미터: data(필수, 최대 2048자), format(기본 png 또는 svg), size(px, 128–4096, 기본 1024).

curl -H "Authorization: Bearer $HONESTQR_KEY" \
  "https://qr.zalize.com/api/v1/static?data=https%3A%2F%2Fexample.com&format=png&size=1024" \
  -o qr.png

curl -H "Authorization: Bearer $HONESTQR_KEY" \
  "https://qr.zalize.com/api/v1/static?data=https%3A%2F%2Fexample.com&format=svg" \
  -o qr.svg

동적 QR코드 생성

POST /api/v1/qrcodes — 편집 가능한 단축 링크(https://qr.zalize.com/r/<slug>)를 만들고 이미지 URL을 반환합니다. 바디 필드: target_url(필수), name, folder. 무료 플랜에는 동적 코드 3개가 포함됩니다.

curl -X POST https://qr.zalize.com/api/v1/qrcodes \
  -H "Authorization: Bearer $HONESTQR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_url": "https://example.com/menu", "name": "Menu"}'

{
  "qrcode": { "id": "…", "slug": "abc1234", "short_url": "https://qr.zalize.com/r/abc1234", … },
  "image_png": "https://qr.zalize.com/api/v1/qrcodes/<id>/image?format=png",
  "image_svg": "https://qr.zalize.com/api/v1/qrcodes/<id>/image?format=svg"
}

JavaScript 예시

Node.js 18+ 및 fetch를 지원하는 모든 런타임(Workers, Deno, Bun)에서 동작합니다. 브라우저에서는 백엔드 프록시를 통해서만 — 키를 클라이언트에 노출하지 마세요.

const BASE = 'https://qr.zalize.com';
const headers = {
  Authorization: `Bearer ${process.env.HONESTQR_KEY}`,
  'Content-Type': 'application/json',
};

// Create a dynamic code
const res = await fetch(`${BASE}/api/v1/qrcodes`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ target_url: 'https://example.com/menu', name: 'Menu' }),
});
if (!res.ok) throw new Error(`HonestQR ${res.status}: ${(await res.json()).error}`);
const { qrcode } = await res.json();

// Fetch its stats later
const stats = await (await fetch(`${BASE}/api/v1/qrcodes/${qrcode.id}/stats`, { headers })).json();
console.log(qrcode.short_url, stats.total);

Python 예시

import os, requests

BASE = "https://qr.zalize.com"
HEADERS = {"Authorization": f"Bearer {os.environ['HONESTQR_KEY']}"}

# Render a static QR code (never stored, never expires)
png = requests.get(
    f"{BASE}/api/v1/static",
    params={"data": "https://example.com", "format": "png", "size": 1024},
    headers=HEADERS,
)
png.raise_for_status()
open("qr.png", "wb").write(png.content)

# Create a dynamic code
r = requests.post(
    f"{BASE}/api/v1/qrcodes",
    json={"target_url": "https://example.com/menu", "name": "Menu"},
    headers=HEADERS,
)
r.raise_for_status()
print(r.json()["qrcode"]["short_url"])

동적 코드 이미지 다운로드

GET /api/v1/qrcodes/:id/image — 쿼리 파라미터 format(png/svg)과 size.

curl -H "Authorization: Bearer $HONESTQR_KEY" \
  "https://qr.zalize.com/api/v1/qrcodes/<id>/image?format=svg" -o menu.svg

내 QR코드 목록

GET /api/v1/qrcodes

curl -H "Authorization: Bearer $HONESTQR_KEY" https://qr.zalize.com/api/v1/qrcodes

스캔 통계

GET /api/v1/qrcodes/:id/stats — 총계와 함께 일별(최근 30일)·국가별·기기별 분포.

curl -H "Authorization: Bearer $HONESTQR_KEY" https://qr.zalize.com/api/v1/qrcodes/<id>/stats

오류

모든 오류는 JSON입니다: {"error": "…"}.

상태	의미	대처 방법
`400`	잘못된 요청(파라미터 누락/오류)	`error` 메시지를 확인하고 파라미터를 수정하세요.
`401`	API 키 누락 또는 무효	`Authorization: Bearer hqr_…`를 전달하세요. 취소된 키는 대시보드에서 재발급.
`402`	플랜 한도 도달(무료 플랜: 동적 코드 3개)	사용하지 않는 코드를 삭제하거나 Pro로 업그레이드하세요.
`404`	QR코드 없음(또는 다른 계정 소유)	`GET /api/v1/qrcodes`로 `id`를 확인하세요.
`429`	요청 제한(키당 분당 60회)	1분 후 재시도하고 가능하면 조회를 묶어서 처리하세요.

코드 없이 삽입하고 싶다면

전체 생성기를 무료 임베드 위젯으로 내 사이트에 넣을 수도 있습니다 — 스니펫 하나, API 키 불필요.

AI 에이전트를 사용 중인가요?

HonestQR는 무료 MCP 서버도 제공하여 Claude, Cursor 등 MCP 클라이언트가 직접 QR코드를 생성·디코딩할 수 있습니다 — API 키 불필요.