Recettes d’intégration

Quatre schémas couvrent presque toutes les intégrations que nous voyons. Chacun tient en quelques appels, et ils se combinent.

Rediriger un code imprimé

La raison pour laquelle la plupart des équipes se tournent vers l’API. Un code sur un emballage, un autocollant ou une affiche continue de fonctionner pendant que la campagne derrière lui change.

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

L’effet est immédiat sur un code publié — aucune étape de republication — et la réponse indique si le code est live ou encore un brouillon.

Joindre un QR à une fiche CRM

Créez le code avec l’URL de la fiche elle-même, publiez-le, puis tirez l’image directement dans un champ fichier. L’endpoint d’image renvoie les octets en ligne, si bien que la plupart des CRM les acceptent en pièce jointe sans téléversement intermédiaire.

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

Stockez qrId sur votre fiche. C’est la poignée de tout le reste — redirection, archivage, statistiques.

Émettre des codes en masse

Un code par produit, par table, par équipement. Envoyez un CSV, interrogez la tâche, puis rapprochez les résultats de vos propres lignes — chaque ligne porte le qrId qu’elle a produit.

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"

Envoyez d’abord "dryRun": true pour valider chaque ligne sans rien écrire.

Intégrer l’image par URL

Airtable, Notion et Sheets affichent une image à partir d’un lien qu’ils récupèrent eux-mêmes : ils n’envoient donc jamais votre en-tête Authorization et ne peuvent pas utiliser l’endpoint ci-dessus. Demandez plutôt un lien signé :

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

Seuls les codes publiés y ont droit — un code publié est déjà imprimé et dans le monde, alors qu’un brouillon peut être une campagne non annoncée. Placez l’url renvoyée directement dans un champ pièce jointe ou image. Archiver ou supprimer le code coupe le lien immédiatement : c’est ainsi que l’on révoque celui qui a circulé plus loin que prévu.

Réagir aux scans

Les scans ne sont jamais poussés : il n’y a pas de webhook par scan, et nous n’envoyons pas de statistiques au niveau du scan vers des endpoints tiers. Abonnez-vous à scan.aggregate_ready si une agrégation suffit, ou récupérez vous-même les scans individuels selon un calendrier :

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

Conservez le pagination.nextCursor renvoyé et redonnez-le la fois suivante. L’ordre est stable : un collecteur ne relit jamais un scan et n’en saute jamais. Les champs présents dépendent des réglages de confidentialité analytique de votre espace — la réponse liste allowedDimensions pour que vous sachiez à quoi vous attendre.

Si l’interrogation périodique ne convient vraiment pas et qu’il vous faut les scans au moment où ils surviennent, c’est possible sur demande, pas par défaut.

Plateformes no-code

Make, Zapier, n8n et Pipedream savent déjà parler à Mosaqo avec un module HTTP générique, et les pièces dont ils ont besoin sont en place : GET /me comme test de connexion, une pagination par curseur pour les itérateurs, et des abonnements webhook qu’un déclencheur crée et supprime lui-même.

Le même document OpenAPI s’importe dans Postman et Insomnia, et génère un client typé avec openapi-typescript ou n’importe quel générateur OpenAPI.

Deux règles à suivre

• Stockez `qrId`, pas l’URL publique. L’URL est stable, mais c’est l’identifiant dont chaque appel ultérieur a besoin.
• Archivez plutôt que supprimer. La suppression est définitive et casse chaque exemplaire imprimé ; l’archivage retire un code de la circulation et se défait.

Tous les détails des endpoints se trouvent dans la référence de l’API.