Рецепты интеграции

Четыре подхода покрывают почти каждую интеграцию, которую мы видим. Каждый — это несколько вызовов, и они сочетаются между собой.

Перенацелить напечатанный код

Причина, по которой большинство команд вообще берётся за 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 или ещё черновик.

Вложить QR в запись CRM

Создайте код с адресом самой записи, опубликуйте его, а затем положите изображение прямо в файловое поле. Эндпоинт изображения отдаёт байты инлайн, поэтому большинство 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, чтобы проверить каждую строку, ничего не записывая.

Вставить изображение по ссылке

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 кладите прямо в поле вложения или изображения. Архивация или удаление кода мгновенно прекращает работу ссылки — именно так отзывают то, что разошлось дальше, чем вы планировали.

Реагировать на сканирования

Сканирования никогда не выталкиваются: вебхука на отдельное сканирование нет, и аналитику уровня сканирований мы на сторонние endpoint-ы не отправляем. Подпишитесь на 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, чтобы вы знали, чего ждать.

Если опрос вам действительно не подходит и нужны сканирования в момент, когда они происходят, — это доступно по отдельному запросу, а не по умолчанию.

No-code платформы

Make, Zapier, n8n и Pipedream уже сегодня могут разговаривать с Mosaqo через обычный HTTP-модуль, и всё нужное для этого есть: GET /me как проверка соединения, курсорная пагинация для итераторов и подписки на webhooks, которые триггер создаёт и снимает сам.

Тот же документ OpenAPI импортируется в Postman и Insomnia и даёт типизированный клиент через openapi-typescript или любой генератор OpenAPI.

Два правила, которых стоит держаться

• Сохраняйте `qrId`, а не публичный адрес. Адрес стабилен, но именно id нужен каждому следующему вызову.
• Архивируйте, а не удаляйте. Удаление необратимо и ломает каждую напечатанную копию; архивация снимает код с эфира, и её можно отменить.

Все подробности об эндпоинтах — в справочнике API.