Mosaqo API для розробників

REST API над тим самим простором, який ви бачите в застосунку. Усе нижче працює з одним API-ключем і будь-яким HTTP-клієнтом.

Що можна зробити

• Створювати QR-коди зі своїх записів — по одному або десять тисяч із CSV.
• Змінювати, куди веде надрукований код, одним викликом і без передруку.
• Завантажувати готову картку в PNG, SVG чи PDF і вкладати її в запис CRM.
• Читати сканування й зведену аналітику з урахуванням правил приватності вашого простору.
• Отримувати підписані webhooks, коли коди створюються, публікуються, змінюються чи архівуються.

Швидкий старт

Створіть ключ у розділі Пакетна робота та 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

Ключ належить рівно одному простору, тому ідентифікатор простору в шляху не потрібен: достатньо /v1/public-api/qr. Стара форма /v1/public-api/workspaces/{workspaceId}/qr теж працює.

Ключ можна відкликати, обмежити строком дії або IP allow-list. Якщо ключ відхилено саме через allow-list, вам про це скажуть прямо, а не видадуть його за недійсний.

Пагінація

Списки використовують keyset-пагінацію. Передавайте 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"
}

Ліміти запитів

Кожна відповідь несе ваш поточний залишок, а не лише ті, які відхилено:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 574
X-RateLimit-Reset: 1785942718

Ліміт — це захист від зловживань, а не тариф: він не означає ні квоти, ні оплати, ні переходу на вищий план.

Ідемпотентність

Idempotency-Key необов’язковий. Передайте його — будь-який унікальний рядок, — і повтор того самого запиту протягом 24 годин відтворить початкову відповідь замість того, щоб виконати дію двічі. Той самий ключ з іншими даними поверне 409. Без ключа запит просто виконається, без захисту від повтору.

Далі

• Webhooks — каталог подій і як перевірити доставку.
• Рецепти — Make, Zapier, n8n та підходи для CRM.
• Довідник API — усі ендпоінти з живою консоллю.