Mosaqo API pro vývojáře

REST API nad stejným pracovním prostorem, jaký používáte v aplikaci. Vše níže funguje s jediným API klíčem a libovolným HTTP klientem.

Co můžete dělat

Vytvářet QR kódy z vlastních záznamů — po jednom, nebo deset tisíc z CSV.
Změnit, kam vede vytištěný kód, jedním voláním a bez opětovného tisku.
Stáhnout hotovou kartu v PNG, SVG nebo PDF a připojit ji k záznamu v CRM.
Číst skenování a agregovanou analytiku, filtrované pravidly soukromí vašeho prostoru.
Dostávat podepsané webhooky, když se kódy vytvoří, publikují, změní nebo archivují.

Rychlý start

Vytvořte klíč v sekci Bulk & API svého prostoru, zaškrtněte rozsahy qr:write a qr:read a zkopírujte tajemství — zobrazí se jen jednou.

Ověřte klíč a zjistěte, který prostor otevírá:

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

Vytvořte dynamický QR kód:

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

Publikujte ho — právě to zprovozní přesměrování — a pak si vyzvedněte obrázek k tisku:

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

O měsíce později, když se kampaň přesune, přesměrujte tentýž vytištěný kód bez opětovného tisku:

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

Autentizace

Tajemství pošlete jedním ze dvou způsobů. Oba platí po celou dobu v1.

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

Klíč patří přesně jednomu pracovnímu prostoru, takže cesty jeho identifikátor nepotřebují: stačí /v1/public-api/qr. Starší tvar /v1/public-api/workspaces/{workspaceId}/qr stále funguje.

Rozsah	Opravňuje k
`qr:read`	Výpisu a čtení QR kódů, složek a šablon
`qr:write`	Vytváření, úpravám, přesměrování, publikaci, archivaci a mazání
`exports:read`	Stahování vykreslených karet
`analytics:read`	Agregované analytice a jednotlivým skenováním
`bulk:write`	Zakládání a čtení hromadných úloh
`webhooks:write`	Správě odběrů webhooků

Klíče lze odvolat, opatřit datem vypršení a omezit na seznam povolených IP. Pokud klíč odmítne právě tento seznam, řekneme to výslovně, místo aby vypadal jako neplatný.

Stránkování

Seznamy používají stránkování podle klíče. Vracejte pagination.nextCursor beze změny: řádky se nikdy neopakují ani nemizí kvůli tomu, že se něco upravilo uprostřed synchronizace — což je u noční synchronizace podstatné.

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

Chcete-li se ptát jen na změny místo procházení všeho, přidejte updatedSince=2026-08-05T00:00:00Z.

Chyby

Každá chyba nese stabilní code, podle kterého se dá větvit, čitelnou message a requestId, který stojí za to uvést podpoře.

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

Stav	Kódy	Co udělat
401	`invalid_api_key`	Klíč chybí, byl odvolán nebo vypršel. Požádejte uživatele, ať se připojí znovu.
403	`insufficient_scope`, `ip_not_allowed`, `workspace_mismatch`, `quota_exceeded`	Klíč je platný, ale na tohle nemá právo. Opětovné připojení nepomůže.
404	`not_found`	Takový záznam v tomto prostoru není.
409	`idempotency_conflict`, `idempotency_in_progress`	Klíč byl použit znovu s jinými daty, nebo první pokus stále běží.
422	`validation_failed`, `invalid_cursor`, `approval_required`, `contrast_check_failed`	Opravte vstup. Nikdy neopakujte beze změny.
429	`rate_limited`	Počkejte počet sekund z hlavičky `Retry-After`.

Limity požadavků

Každá odpověď nese váš aktuální zůstatek, nejen ty odmítnuté:

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

Limit je ochrana proti zneužití, ne tarif: neznamená kvótu, fakturaci ani přechod na vyšší plán.

Idempotence

Idempotency-Key je volitelný. Pošlete ho — libovolný jedinečný řetězec — a zopakování stejného požadavku do 24 hodin přehraje původní odpověď místo druhého provedení. Tentýž klíč s jinými daty vrátí 409. Bez klíče se požadavek prostě provede, bez ochrany proti opakování.

Dál

Webhooky — katalog událostí a jak ověřit doručení.
Recepty — vzory pro Make, Zapier, n8n a CRM.
Reference API — každý endpoint, s živou konzolí.