API da Mosaqo para desenvolvedores

Uma API REST sobre o mesmo espaço de trabalho que você usa no aplicativo. Tudo abaixo funciona com uma única chave de API e qualquer cliente HTTP.

O que dá para fazer

• Criar QR codes a partir dos seus registros — um a um ou dez mil de um CSV.
• Mudar para onde aponta um código já impresso, em uma chamada e sem reimprimir nada.
• Baixar o cartão final em PNG, SVG ou PDF e anexá-lo a um registro do CRM.
• Ler escaneamentos e análises agregadas, filtrados pelas regras de privacidade do seu espaço.
• Receber webhooks assinados quando um código é criado, publicado, alterado ou arquivado.

Início rápido

Crie uma chave em Bulk & API dentro do seu espaço, marque os escopos qr:write e qr:read e copie o segredo — ele é exibido uma única vez.

Verifique a chave e descubra qual espaço ela abre:

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

Crie um QR code dinâmico:

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

Publique-o — é isso que faz o redirecionamento funcionar — e então pegue a imagem pronta para impressão:

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

Meses depois, quando a campanha mudar, redirecione o mesmo código impresso sem reimprimi-lo:

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

Autenticação

Envie seu segredo de qualquer uma das duas formas. Ambas valem por toda a v1.

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

Uma chave pertence a exatamente um espaço de trabalho, então os caminhos não precisam do identificador do espaço: /v1/public-api/qr basta. A forma antiga /v1/public-api/workspaces/{workspaceId}/qr continua funcionando.

As chaves podem ser revogadas, receber data de expiração e ficar restritas a uma lista de IPs permitidos. Se for essa lista que rejeitou a chave, dizemos isso explicitamente em vez de fazê-la parecer inválida.

Paginação

As listas usam paginação por chave. Devolva pagination.nextCursor sem alterações: linhas nunca se repetem nem somem porque algo foi editado no meio da sincronização, o que importa numa sincronização noturna.

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

Para consultar mudanças em vez de percorrer tudo, acrescente updatedSince=2026-08-05T00:00:00Z.

Erros

Toda falha traz um code estável para ramificar, uma message legível e um requestId que vale citar ao suporte.

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

Limites de requisição

Toda resposta traz o seu orçamento atual, não apenas as que são recusadas:

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

O limite é uma proteção contra abuso, não um plano: não implica cota, cobrança nem upgrade.

Idempotência

Idempotency-Key é opcional. Envie uma — qualquer string única — e repetir a mesma requisição em até 24 horas reproduz a resposta original em vez de agir duas vezes. A mesma chave com dados diferentes retorna 409. Sem chave, a requisição simplesmente roda, sem proteção contra repetição.

A seguir

• Webhooks — o catálogo de eventos e como verificar uma entrega.
• Receitas — padrões para Make, Zapier, n8n e CRMs.
• Referência da API — cada endpoint, com console ao vivo.