Recetas de integración

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

Redirigir un código impreso

La razón por la que la mayoría de los equipos recurre a la API. Un código en un empaque, una calcomanía o un cartel sigue funcionando mientras la campaña 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 un registro del CRM

Crea el código con la URL del propio registro, publícalo y lleva la imagen directo a un campo de archivo. El endpoint de imagen devuelve los bytes en línea, así que la mayoría de los CRM los acepta como adjunto sin una carga 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());

Guarda qrId en tu registro. Es la manija de todo lo que sigue: redirección, archivado, analíticas.

Emitir códigos por lotes

Un código por producto, por mesa, por equipo. Envía un CSV, consulta el trabajo y luego relaciona los resultados con tus 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ía 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 tu encabezado Authorization y no pueden usar el endpoint anterior. Pide 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 aplican 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. Pon la url devuelta directo 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 difundió 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íbete a scan.aggregate_ready si te basta un agregado, u obtén tú 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"

Conserva el pagination.nextCursor devuelto y pásalo 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 tu espacio: la respuesta lista allowedDimensions para que sepas qué esperar.

Si el sondeo de verdad no te sirve y necesitas 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 su cuenta.

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

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

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