Przepisy integracyjne

Cztery wzorce pokrywają niemal każdą integrację, jaką widujemy. Każdy to garść wywołań, i dają się łączyć.

Przekierować wydrukowany kod

Powód, dla którego większość zespołów w ogóle sięga po API. Kod na opakowaniu, naklejce czy plakacie działa dalej, podczas gdy kampania za nim się zmienia.

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

Na opublikowanym kodzie działa natychmiast — nie ma kroku ponownej publikacji — a odpowiedź mówi, czy kod jest live, czy wciąż roboczy.

Dołączyć QR do rekordu w CRM

Utwórz kod z adresem samego rekordu, opublikuj go, a potem wciągnij obraz prosto do pola plikowego. Endpoint obrazu zwraca bajty inline, więc większość CRM-ów przyjmuje je jako załącznik bez pośredniego wysyłania.

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());

Zapisz qrId przy swoim rekordzie. To uchwyt do wszystkiego później — przekierowania, archiwizacji, analityki.

Wydać kody zbiorczo

Jeden kod na produkt, na stolik, na urządzenie. Wyślij CSV, odpytuj zadanie, a potem przypisz wyniki do własnych wierszy — każdy wiersz niesie qrId, który wytworzył.

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"

Najpierw wyślij "dryRun": true, żeby sprawdzić każdy wiersz, nic nie zapisując.

Osadzić obraz przez URL

Airtable, Notion i Sheets pokazują obraz z linku, po który idą same, więc nigdy nie wysyłają Twojego nagłówka Authorization i nie mogą użyć powyższego endpointu. Poproś zamiast tego o podpisany link:

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

Kwalifikują się tylko kody opublikowane — opublikowany kod jest już wydrukowany i w świecie, a wersja robocza może być niezapowiedzianą kampanią. Zwrócony url wstaw prosto w pole załącznika lub obrazu. Archiwizacja albo usunięcie kodu natychmiast unieruchamia link — tak właśnie odwołuje się ten, który rozszedł się dalej, niż zamierzałeś.

Reagować na skanowania

Skanowań nigdy nie wypychamy: nie ma webhooka na pojedyncze skanowanie i nie wysyłamy analityki na poziomie skanowania do endpointów osób trzecich. Zasubskrybuj scan.aggregate_ready, jeśli wystarczy agregat, albo sam pobieraj pojedyncze skanowania według harmonogramu:

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

Zachowaj zwrócony pagination.nextCursor i podaj go następnym razem. Kolejność jest stabilna, więc odpytywacz nigdy nie czyta dwa razy ani nie pomija skanowania. To, które pola się pojawią, zależy od ustawień prywatności analityki Twojej przestrzeni — odpowiedź wypisuje allowedDimensions, żebyś wiedział, czego się spodziewać.

Jeśli odpytywanie naprawdę Ci nie pasuje i potrzebujesz skanowań w chwili, gdy się dzieją, jest to dostępne na życzenie, a nie domyślnie.

Platformy no-code

Make, Zapier, n8n i Pipedream już dziś potrafią rozmawiać z Mosaqo przez ogólny moduł HTTP, a potrzebne im elementy są na miejscu: GET /me jako test połączenia, paginacja kursorowa dla iteratorów i subskrypcje webhooków, które wyzwalacz zakłada i usuwa sam.

Ten sam dokument OpenAPI importuje się do Postmana i Insomnii oraz generuje typowanego klienta przez openapi-typescript lub dowolny generator OpenAPI.

Dwie zasady warte trzymania się

• Zapisuj `qrId`, a nie publiczny adres. Adres jest stabilny, ale to identyfikatora potrzebuje każde kolejne wywołanie.
• Archiwizuj zamiast usuwać. Usunięcie jest nieodwracalne i psuje każdą wydrukowaną kopię; archiwizacja zdejmuje kod z obiegu i da się cofnąć.

Wszystkie szczegóły endpointów znajdziesz w dokumentacji API.