Recetas de integración

Cuatro patrones cubren casi todas las integraciones que vemos. Cada uno son unas pocas llamadas, y se combinan entre sí.

Redirigir un código impreso

La razón por la que la mayoría de los equipos recurren a la API. Un código en un envase, una pegatina o un cartel sigue funcionando mientras la campaña que hay detrás cambia.

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

Sobre un código publicado surte efecto de inmediato —no hay paso de republicación— y la respuesta indica si el código está live o sigue en borrador.

Adjuntar un QR a una ficha del CRM

Cree el código con la URL de la propia ficha, publíquelo y lleve la imagen directamente a un campo de archivo. El endpoint de imagen devuelve los bytes en línea, así que la mayoría de los CRM los aceptan como adjunto sin una subida intermedia.

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

Guarde qrId en su ficha. Es el asa de todo lo que venga después: redirección, archivado, analíticas.

Emitir códigos por lotes

Un código por producto, por mesa, por equipo. Envíe un CSV, consulte el trabajo y luego relacione los resultados con sus propias filas: cada fila lleva el qrId que produjo.

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"

Envíe primero "dryRun": true para validar cada fila sin escribir nada.

Incrustar la imagen por URL

Airtable, Notion y Sheets muestran una imagen a partir de un enlace que obtienen ellos mismos, así que nunca envían su cabecera Authorization y no pueden usar el endpoint anterior. Pida en su lugar un enlace firmado:

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

Solo valen los códigos publicados: un código publicado ya está impreso y en el mundo, mientras que un borrador puede ser una campaña sin anunciar. Ponga la url devuelta directamente en un campo de adjunto o de imagen. Archivar o eliminar el código corta el enlace al instante: así se revoca uno que se ha difundido más de lo previsto.

Reaccionar a los escaneos

Los escaneos nunca se envían: no hay webhook por escaneo y no mandamos analíticas a nivel de escaneo a endpoints de terceros. Suscríbase a scan.aggregate_ready si le basta un agregado, u obtenga usted mismo los escaneos individuales de forma programada:

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

Conserve el pagination.nextCursor devuelto y páselo la próxima vez. El orden es estable, así que un proceso de sondeo nunca relee ni se salta un escaneo. Qué campos aparecen depende de los ajustes de privacidad analítica de su espacio: la respuesta lista allowedDimensions para que sepa qué esperar.

Si el sondeo periódico realmente no le sirve y necesita los escaneos en el momento en que ocurren, eso está disponible bajo petición, no por defecto.

Plataformas no-code

Make, Zapier, n8n y Pipedream ya pueden hablar con Mosaqo mediante un módulo HTTP genérico, y las piezas que necesitan están listas: GET /me como prueba de conexión, paginación por cursor para los iteradores y suscripciones de webhook que un disparador crea y elimina por sí mismo.

El mismo documento OpenAPI se importa en Postman e Insomnia, y genera un cliente tipado con openapi-typescript o cualquier generador de OpenAPI.

Dos reglas que conviene seguir

• Guarde `qrId`, no la URL pública. La URL es estable, pero el identificador es lo que necesita cada llamada posterior.
• Archive en lugar de eliminar. Eliminar es permanente y estropea cada copia impresa; archivar retira un código de circulación y se puede deshacer.

Todos los detalles de los endpoints están en la referencia de la API.