API Mosaqo pour les développeurs

Une API REST sur le même espace de travail que celui de l’application. Tout ce qui suit fonctionne avec une seule clé d’API et n’importe quel client HTTP.

Ce que vous pouvez faire

Créer des QR codes à partir de vos propres enregistrements — un par un, ou dix mille depuis un CSV.
Changer la destination d’un code déjà imprimé, en un appel, sans rien réimprimer.
Télécharger la carte finale en PNG, SVG ou PDF et la joindre à une fiche CRM.
Lire les scans et les statistiques agrégées, filtrés par les règles de confidentialité de votre espace.
Recevoir des webhooks signés quand un code est créé, publié, modifié ou archivé.

Démarrage rapide

Créez une clé dans Bulk & API au sein de votre espace, cochez les scopes qr:write et qr:read, puis copiez le secret — il n’est affiché qu’une fois.

Vérifiez la clé et découvrez quel espace elle ouvre :

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

Créez un QR code dynamique :

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

Publiez-le — c’est ce qui active la redirection — puis récupérez l’image prête à imprimer :

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

Des mois plus tard, quand la campagne change, redirigez le même code imprimé sans le réimprimer :

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

Authentification

Envoyez votre secret de l’une ou l’autre façon. Les deux restent valables pendant toute la v1.

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

Une clé appartient à un seul espace de travail : les chemins n’ont donc pas besoin d’identifiant d’espace, /v1/public-api/qr suffit. L’ancienne forme /v1/public-api/workspaces/{workspaceId}/qr fonctionne toujours.

Scope	Autorise
`qr:read`	Lister et lire les QR codes, les dossiers et les modèles
`qr:write`	Créer, modifier, rediriger, publier, archiver et supprimer
`exports:read`	Télécharger les cartes rendues
`analytics:read`	Statistiques agrégées et scans individuels
`bulk:write`	Créer et lire des tâches en lot
`webhooks:write`	Gérer les abonnements aux webhooks

Une clé peut être révoquée, dotée d’une date d’expiration et restreinte à une liste d’IP autorisées. Si c’est cette liste qui rejette la clé, nous le disons explicitement plutôt que de la faire passer pour invalide.

Pagination

Les listes utilisent une pagination par clé. Renvoyez pagination.nextCursor tel quel : aucune ligne ne se répète ni ne disparaît parce qu’un élément a été modifié en cours de synchronisation — ce qui compte pour une synchro nocturne.

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

Pour interroger les changements au lieu de tout parcourir, ajoutez updatedSince=2026-08-05T00:00:00Z.

Erreurs

Chaque échec porte un code stable sur lequel brancher votre logique, un message lisible et un requestId à citer au support.

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

Statut	Codes	Que faire
401	`invalid_api_key`	La clé est absente, révoquée ou expirée. Demandez à l’utilisateur de se reconnecter.
403	`insufficient_scope`, `ip_not_allowed`, `workspace_mismatch`, `quota_exceeded`	La clé est valide mais n’a pas ce droit. Se reconnecter n’y changera rien.
404	`not_found`	Aucun enregistrement de ce type dans cet espace.
409	`idempotency_conflict`, `idempotency_in_progress`	Clé réutilisée avec des données différentes, ou première tentative encore en cours.
422	`validation_failed`, `invalid_cursor`, `approval_required`, `contrast_check_failed`	Corrigez l’entrée. Ne réessayez jamais à l’identique.
429	`rate_limited`	Attendez le nombre de secondes indiqué par `Retry-After`.

Limites de débit

Chaque réponse indique votre budget courant, pas seulement celles qui sont refusées :

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

Cette limite est un garde-fou anti-abus, pas une offre : elle n’implique ni quota, ni facturation, ni montée en gamme.

Idempotence

Idempotency-Key est facultatif. Envoyez-en une — n’importe quelle chaîne unique — et réessayer la requête identique dans les 24 heures rejoue la réponse initiale au lieu d’agir deux fois. La même clé avec des données différentes renvoie 409. Sans clé, la requête s’exécute simplement, sans protection contre le rejeu.

Ensuite

Webhooks — le catalogue d’événements et la vérification d’une livraison.
Recettes — Make, Zapier, n8n et les schémas CRM.
Référence de l’API — chaque endpoint, avec une console en direct.