API Mosaqo dla programistów

API REST na tej samej przestrzeni roboczej, której używasz w aplikacji. Wszystko poniżej działa z jednym kluczem API i dowolnym klientem HTTP.

Co możesz zrobić

• Tworzyć kody QR z własnych rekordów — pojedynczo albo dziesięć tysięcy z pliku CSV.
• Zmienić, dokąd prowadzi wydrukowany kod, jednym wywołaniem i bez ponownego druku.
• Pobrać gotową kartę w PNG, SVG lub PDF i dołączyć ją do rekordu w CRM.
• Czytać skanowania i zagregowaną analitykę, filtrowane przez reguły prywatności Twojej przestrzeni.
• Otrzymywać podpisane webhooki, gdy kody są tworzone, publikowane, zmieniane lub archiwizowane.

Szybki start

Utwórz klucz w sekcji Bulk & API swojej przestrzeni, zaznacz zakresy qr:write i qr:read i skopiuj sekret — pokazujemy go tylko raz.

Sprawdź klucz i dowiedz się, którą przestrzeń otwiera:

curl https://api.mosaqo.app/v1/public-api/me \
  -H "Authorization: Bearer $MOSAQO_KEY"

Utwórz dynamiczny kod 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" }
  }'

Opublikuj go — to właśnie uruchamia przekierowanie — a potem pobierz obraz gotowy do druku:

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

Miesiące później, gdy kampania się zmieni, przekieruj ten sam wydrukowany kod bez ponownego druku:

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

Uwierzytelnianie

Wyślij sekret w dowolny z dwóch sposobów. Oba obowiązują przez całe v1.

Authorization: Bearer mosaqo_xxx
X-Mosaqo-API-Key: mosaqo_xxx

Klucz należy do dokładnie jednej przestrzeni roboczej, więc ścieżki nie potrzebują jej identyfikatora: wystarczy /v1/public-api/qr. Starsza forma /v1/public-api/workspaces/{workspaceId}/qr nadal działa.

Klucze można unieważnić, nadać im datę wygaśnięcia i ograniczyć do listy dozwolonych adresów IP. Jeśli to ta lista odrzuciła klucz, mówimy o tym wprost, zamiast pozwolić mu wyglądać na nieważny.

Paginacja

Listy używają paginacji kluczowej. Odsyłaj pagination.nextCursor bez zmian: wiersze nigdy się nie powtórzą ani nie znikną dlatego, że coś zmieniono w trakcie synchronizacji — co ma znaczenie przy nocnym przebiegu.

curl "https://api.mosaqo.app/v1/public-api/qr?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $MOSAQO_KEY"

Aby odpytywać o zmiany zamiast przechodzić wszystko, dodaj updatedSince=2026-08-05T00:00:00Z.

Błędy

Każdy błąd niesie stabilny code, na którym można się rozgałęzić, czytelny message oraz requestId, który warto podać wsparciu.

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

Limity zapytań

Każda odpowiedź niesie Twój bieżący budżet, nie tylko te odrzucone:

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

Limit to zabezpieczenie przed nadużyciami, a nie plan taryfowy: nie oznacza ani kwoty, ani rozliczeń, ani przejścia wyżej.

Idempotentność

Idempotency-Key jest opcjonalny. Wyślij go — dowolny unikalny ciąg — a ponowienie identycznego żądania w ciągu 24 godzin odtworzy pierwotną odpowiedź zamiast działać dwa razy. Ten sam klucz z innymi danymi zwróci 409. Bez klucza żądanie po prostu się wykona, bez ochrony przed powtórzeniem.

Dalej

• Webhooki — katalog zdarzeń i jak zweryfikować dostarczenie.
• Przepisy — wzorce dla Make, Zapier, n8n i systemów CRM.
• Dokumentacja API — każdy endpoint, z konsolą na żywo.