Рецепти інтеграції

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

Перецілити надрукований код

Причина, з якої більшість команд узагалі беруться за 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.