연동 레시피

네 가지 패턴이면 저희가 보는 거의 모든 연동을 다룰 수 있습니다. 각각은 호출 몇 번이면 되고, 서로 조합할 수 있습니다.

인쇄된 코드의 연결 대상 바꾸기

대부분의 팀이 애초에 API를 찾는 이유입니다. 포장재, 스티커, 포스터에 붙은 코드는 그 뒤의 캠페인이 바뀌어도 계속 동작합니다.

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" }'

게시된 코드에는 즉시 반영되며 다시 게시하는 단계는 없습니다. 응답을 보면 코드가 live 인지 아직 초안인지 알 수 있습니다.

CRM 레코드에 QR 첨부하기

레코드 자체의 URL로 코드를 만들고, 게시한 뒤, 이미지를 곧바로 파일 필드로 가져오세요. 이미지 엔드포인트는 바이트를 인라인으로 반환하므로 대부분의 CRM은 중간 업로드 없이 첨부로 받아들입니다.

const headers = { Authorization: `Bearer ${process.env.MOSAQO_KEY}` };

const created = await fetch('https://api.mosaqo.app/v1/public-api/qr', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: `Deal ${deal.id}`,
    mode: 'dynamic',
    contentType: 'url',
    content: { targetUrl: `https://crm.example.com/deals/${deal.id}` },
  }),
}).then((r) => r.json());

const qrId = created.data.id;
await fetch(`https://api.mosaqo.app/v1/public-api/qr/${qrId}/publish`, { method: 'POST', headers });

const png = await fetch(
  `https://api.mosaqo.app/v1/public-api/qr/${qrId}/image?format=png&size=1024`,
  { headers },
).then((r) => r.arrayBuffer());

레코드에 qrId 를 저장하세요. 이후의 모든 작업 — 연결 대상 변경, 보관, 분석 — 의 손잡이가 됩니다.

코드 일괄 발급하기

제품마다, 테이블마다, 자산마다 코드 하나씩. CSV를 보내고, 작업을 폴링한 다음, 결과를 자신의 행에 다시 매핑하세요. 각 행에는 그 행이 만들어 낸 qrId 가 담겨 있습니다.

curl -X POST https://api.mosaqo.app/v1/public-api/bulk \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "url",
    "mode": "dynamic",
    "csv": "name,destination\nTable 1,https://example.com/menu?t=1\nTable 2,https://example.com/menu?t=2"
  }'

curl "https://api.mosaqo.app/v1/public-api/bulk/$JOB_ID?limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

먼저 "dryRun": true 를 보내면 아무것도 기록하지 않고 모든 행을 검증할 수 있습니다.

URL로 이미지 삽입하기

Airtable, Notion, Sheets는 자신이 직접 가져온 링크로 이미지를 표시합니다. 그래서 여러분의 Authorization 헤더를 보내지 않으며 위 엔드포인트를 사용할 수 없습니다. 대신 서명된 링크를 요청하세요.

curl -X POST https://api.mosaqo.app/v1/public-api/qr/$QR_ID/image-url \
  -H "Authorization: Bearer $MOSAQO_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "format": "png", "size": 1024 }'

게시된 코드만 해당됩니다 — 게시된 코드는 이미 인쇄되어 세상에 나가 있지만, 초안은 아직 공개하지 않은 캠페인일 수 있습니다. 반환된 url 을 첨부 필드나 이미지 필드에 그대로 넣으세요. 코드를 보관하거나 삭제하면 링크는 즉시 동작을 멈추며, 의도보다 널리 퍼진 링크는 이렇게 회수합니다.

스캔에 반응하기

스캔은 절대 푸시되지 않습니다. 스캔 단위 웹훅은 없고, 스캔 수준의 분석 데이터를 외부 엔드포인트로 보내지도 않습니다. 집계로 충분하다면 scan.aggregate_ready 를 구독하고, 그렇지 않다면 개별 스캔을 주기적으로 직접 가져오세요.

curl "https://api.mosaqo.app/v1/public-api/scans?since=$LAST_SEEN&limit=500" \
  -H "Authorization: Bearer $MOSAQO_KEY"

반환된 pagination.nextCursor 를 보관했다가 다음번에 그대로 넘기세요. 정렬이 안정적이므로 폴러가 스캔을 다시 읽거나 건너뛰는 일이 없습니다. 어떤 필드가 나타나는지는 워크스페이스의 분석 개인정보 설정에 달려 있습니다. 응답에는 allowedDimensions 가 포함되어 무엇을 기대할 수 있는지 알 수 있습니다.

폴링이 정말로 현실적이지 않고 스캔을 발생하는 즉시 받아야 한다면, 기본 제공은 아니지만 요청 시 지원이 가능합니다.

노코드 플랫폼

Make, Zapier, n8n, Pipedream은 모두 범용 HTTP 모듈로 지금 바로 Mosaqo와 통신할 수 있으며, 필요한 조각도 모두 갖춰져 있습니다. 연결 테스트용 GET /me, 이터레이터용 커서 페이지네이션, 그리고 트리거가 스스로 만들고 지울 수 있는 웹훅 구독입니다.

같은 OpenAPI 문서를 Postman과 Insomnia로 가져올 수 있고, openapi-typescript 나 임의의 OpenAPI 생성기로 타입이 있는 클라이언트를 만들 수 있습니다.

지킬 만한 두 가지 규칙

• 공개 URL이 아니라 `qrId` 를 저장하세요. URL은 변하지 않지만, 이후의 모든 호출이 필요로 하는 것은 ID입니다.
• 삭제하지 말고 보관하세요. 삭제는 되돌릴 수 없고 인쇄된 모든 사본을 못 쓰게 만듭니다. 보관은 코드를 오프라인으로 내릴 뿐이며 되돌릴 수 있습니다.

엔드포인트의 전체 상세는 API 레퍼런스에 있습니다.