개발자를 위한 Mosaqo API
앱에서 쓰는 것과 동일한 워크스페이스를 다루는 REST API입니다. 아래 내용은 모두 API 키 하나와 아무 HTTP 클라이언트만 있으면 동작합니다.
할 수 있는 일
- 자체 레코드에서 QR 코드를 생성합니다 — 하나씩, 또는 CSV로 1만 개를 한 번에.
- 인쇄된 코드가 가리키는 곳을 바꿉니다. 호출 한 번이면 되고, 다시 인쇄할 필요가 없습니다.
- 완성된 카드를 PNG, SVG, PDF로 내려받아 CRM 레코드에 첨부합니다.
- 워크스페이스의 개인정보 규칙에 따라 필터링된 스캔과 집계 분석을 읽습니다.
- 코드가 생성, 게시, 변경, 보관될 때 서명된 웹훅을 받습니다.
퀵스타트
워크스페이스의 Bulk & API에서 키를 만들고, qr:write와 qr:read 스코프를 선택한 뒤 시크릿을 복사하세요 — 한 번만 표시됩니다.
키를 확인하고 어떤 워크스페이스를 여는 키인지 알아봅니다.
curl https://api.mosaqo.app/v1/public-api/me \
-H "Authorization: Bearer $MOSAQO_KEY"동적 QR 코드를 생성합니다.
curl -X POST https://api.mosaqo.app/v1/public-api/qr \
-H "Authorization: Bearer $MOSAQO_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Autumn campaign",
"mode": "dynamic",
"contentType": "url",
"content": { "targetUrl": "https://example.com/autumn" }
}'게시하면 리다이렉트가 동작하기 시작합니다. 이어서 인쇄용 이미지를 가져옵니다.
curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/publish \
-H "Authorization: Bearer $MOSAQO_KEY"
curl https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image?format=png&size=2048 \
-H "Authorization: Bearer $MOSAQO_KEY" -o campaign.png몇 달 뒤 캠페인이 바뀌면, 이미 인쇄된 그 코드를 다시 인쇄하지 않고 연결 대상만 바꿉니다.
curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/destination \
-H "Authorization: Bearer $MOSAQO_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/winter" }'인증
시크릿은 둘 중 어느 방식으로 보내도 됩니다. v1 전체 기간 동안 둘 다 지원합니다.
Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx키는 정확히 하나의 워크스페이스에 속하므로 경로에 워크스페이스 ID가 필요 없습니다. /v1/public-api/qr 만으로 충분합니다. 이전 형식인 /v1/public-api/workspaces/{workspaceId}/qr 도 계속 동작합니다.
| 스코프 | 허용되는 작업 |
|---|---|
qr:read | QR 코드, 폴더, 템플릿 목록 조회 및 읽기 |
qr:write | 생성, 수정, 연결 대상 변경, 게시, 보관, 삭제 |
exports:read | 렌더링된 카드 다운로드 |
analytics:read | 집계 분석과 개별 스캔 |
bulk:write | 일괄 작업 생성 및 조회 |
webhooks:write | 웹훅 구독 관리 |
키는 폐기하거나, 만료일을 지정하거나, IP 허용 목록으로 제한할 수 있습니다. 허용 목록에서 거부된 키는 유효하지 않은 것처럼 보이게 하지 않고, 그 사실을 명시적으로 알려 줍니다.
페이지네이션
목록은 키셋 페이지네이션을 사용합니다. pagination.nextCursor 를 그대로 되돌려 보내세요. 동기화 도중 무언가 수정되더라도 행이 중복되거나 사라지지 않으며, 이는 야간 동기화에서 특히 중요합니다.
curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
-H "Authorization: Bearer $MOSAQO_KEY"전체를 훑는 대신 변경분만 폴링하려면 updatedSince=2026-08-05T00:00:00Z 를 추가하세요.
오류
모든 실패 응답에는 분기 처리에 쓸 수 있는 안정적인 code, 사람이 읽을 수 있는 message, 그리고 지원팀에 알려 줄 만한 requestId 가 담깁니다.
{
"error": "This API key does not have the qr:write scope.",
"message": "This API key does not have the qr:write scope.",
"code": "insufficient_scope",
"details": { "required": "qr:write", "granted": ["qr:read"] },
"requestId": "req-42"
}| 상태 | 코드 | 대응 방법 |
|---|---|---|
| 401 | invalid_api_key | 키가 없거나, 폐기되었거나, 만료되었습니다. 사용자에게 다시 연결하도록 안내하세요. |
| 403 | insufficient_scope, ip_not_allowed, workspace_mismatch, quota_exceeded | 키는 유효하지만 이 작업은 허용되지 않습니다. 다시 연결해도 해결되지 않습니다. |
| 404 | not_found | 이 워크스페이스에 해당 레코드가 없습니다. |
| 409 | idempotency_conflict, idempotency_in_progress | 같은 키를 다른 입력으로 재사용했거나, 첫 시도가 아직 실행 중입니다. |
| 422 | validation_failed, invalid_cursor, approval_required, contrast_check_failed | 입력을 고치세요. 그대로 재시도해서는 안 됩니다. |
| 429 | rate_limited | Retry-After 에 적힌 초만큼 기다리세요. |
사용량 제한
거부된 응답뿐 아니라 모든 응답에 현재 남은 한도가 담깁니다.
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718이 제한은 남용 방지 장치이지 요금제가 아닙니다. 할당량, 과금, 업그레이드와는 무관합니다.
멱등성
Idempotency-Key 는 선택 사항입니다. 고유한 문자열이면 무엇이든 하나 보내면, 24시간 안에 동일한 요청을 재시도할 때 두 번 실행되는 대신 원래 응답이 그대로 반환됩니다. 같은 키를 다른 입력으로 재사용하면 409 가 반환됩니다. 키가 없으면 요청은 그냥 실행되며, 재시도 보호는 적용되지 않습니다.