Receitas de integração

Quatro padrões cobrem quase toda integração que vemos. Cada um são poucas chamadas, e eles se combinam.

Redirecionar um código impresso

A razão pela qual a maioria dos times recorre à API. Um código numa embalagem, num adesivo ou num cartaz continua funcionando enquanto a campanha por trás dele muda.

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

Em um código publicado o efeito é imediato — não há etapa de republicação — e a resposta diz se o código está live ou ainda é rascunho.

Anexar um QR a um registro do CRM

Crie o código com a URL do próprio registro, publique-o e puxe a imagem direto para um campo de arquivo. O endpoint de imagem devolve os bytes inline, então a maioria dos CRMs aceita como anexo sem upload intermediário.

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 no seu registro. É a alça de tudo depois — redirecionar, arquivar, análises.

Emitir códigos em lote

Um código por produto, por mesa, por equipamento. Envie um CSV, consulte a tarefa e depois relacione os resultados às suas linhas — cada linha traz o qrId que produziu.

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"

Envie primeiro "dryRun": true para validar cada linha sem gravar nada.

Incorporar a imagem por URL

Airtable, Notion e Sheets exibem uma imagem a partir de um link que eles mesmos buscam, portanto nunca enviam seu cabeçalho Authorization e não conseguem usar o endpoint acima. Peça um link assinado no lugar:

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

Só valem códigos publicados — um código publicado já está impresso e no mundo, enquanto um rascunho pode ser uma campanha não anunciada. Coloque a url devolvida direto em um campo de anexo ou imagem. Arquivar ou excluir o código corta o link na hora: é assim que se revoga um que se espalhou mais do que você pretendia.

Reagir a escaneamentos

Escaneamentos nunca são enviados: não há webhook por escaneamento e não mandamos análises no nível do escaneamento para endpoints de terceiros. Assine scan.aggregate_ready se um agregado bastar, ou busque você mesmo os escaneamentos individuais em uma rotina:

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

Guarde o pagination.nextCursor devolvido e passe-o na próxima vez. A ordem é estável, então um coletor nunca relê nem pula um escaneamento. Quais campos aparecem depende das configurações de privacidade analítica do seu espaço — a resposta lista allowedDimensions para você saber o que esperar.

Se a consulta periódica realmente não servir e você precisar dos escaneamentos no momento em que acontecem, isso está disponível mediante solicitação, não por padrão.

Plataformas no-code

Make, Zapier, n8n e Pipedream já conseguem falar com a Mosaqo por um módulo HTTP genérico, e as peças de que precisam estão prontas: GET /me como teste de conexão, paginação por cursor para iteradores e assinaturas de webhook que um gatilho cria e remove sozinho.

O mesmo documento OpenAPI importa no Postman e no Insomnia e gera um cliente tipado com openapi-typescript ou qualquer gerador OpenAPI.

Duas regras que valem a pena seguir

• Guarde `qrId`, não a URL pública. A URL é estável, mas o identificador é o que toda chamada seguinte precisa.
• Arquive em vez de excluir. Excluir é permanente e inutiliza cada cópia impressa; arquivar tira um código do ar e pode ser desfeito.

Todos os detalhes dos endpoints estão na referência da API.