Crie QR Codes com a API, o MCP e automações

Ao final deste guia você cria QR Codes a partir do seu próprio sistema — um por pedido, mesa, produto ou linha de planilha —, troca para onde apontam, lista e exclui, e é avisado de cada leitura, usando a API REST, o servidor MCP ou o Make.

Disponibilidade

Plano: a API está em todos os planos; a franquia mensal de QR Codes é a mesma do app (Free 5, Starter 150, Pro 1.000 dinâmicos + estáticos ilimitados, Business 5.000). Requisições por minuto: Free 60, Starter 100, Pro 500, Business 1.000. Webhooks de leitura por código precisam de Business.
Onde: https://api.codeqr.io/qrcodes com uma chave de Configurações → Chaves de API; o servidor MCP em https://mcp.codeqr.io/mcp; o app da CodeQR no Make. Referência completa dos campos: docs.codeqr.io.

Antes de começar

Crie uma chave em Configurações → Chaves de API → Criar, dê um nome, escolha as permissões e copie o valor uma única vez. Envie como Authorization: Bearer codeqr_….
type é o único campo obrigatório. static tem padrão false (dinâmico). domain e key são opcionais; sem eles a CodeQR usa o domínio do workspace e uma chave aleatória terminada em -qr. Uma key não pode se repetir dentro do workspace.
Padrões de design pela API: size 1024, level M, preto sobre branco, showLogo true (logo do workspace). Envie "level": "H" quando o código levar logo — o editor faz isso por você, a API não.

Endpoints

POST /qrcodes — O que faz: Cria um código
POST /qrcodes/bulk — O que faz: Cria de 1 a 100 códigos numa chamada (corpo em array)
GET /qrcodes — O que faz: Lista e filtra (type, format=static · dynamic, search, tagIds, folderId, sort=createdAt · scans · lastClicked, page, pageSize até 100, entre outros)
GET /qrcodes/count — O que faz: Conta com os mesmos filtros, groupBy opcional
GET /qrcodes/info?domain=…&key=… — O que faz: Busca um código por domínio e chave (não existe GET /qrcodes/{id})
PUT /qrcodes/{qrcodeId} — O que faz: Atualiza qualquer campo, inclusive url, design, expiresAt, password, archived e static: false para converter
DELETE /qrcodes/{qrcodeId} — O que faz: Exclui um código
DELETE /qrcodes/bulk?qrcodeIds=id1,id2 — O que faz: Exclui vários (ids separados por vírgula num único parâmetro)
GET https://api.codeqr.io/qr?url=<shortLink> — O que faz: PNG de um código existente (sem chave)

Passos: crie códigos a partir dos seus dados

Crie um código para conferir os campos de que precisa:

curl -X POST https://api.codeqr.io/qrcodes \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "type": "url", "url": "https://example.com/menu", "title": "Cafe menu", "static": false }'

Resposta (200 OK, resumida): "id": "cmsx875y30001je433cy0ltlh", "key": "iVx0OCFyDn79-qr", "shortLink": "https://qrup.link/iVx0OCFyDn79-qr", "image": "https://res.cloudinary.com/dhnaggn4g/image/upload/v1786970667/qrup.link/iVx0OCFyDn79-qr.png", "scans": 0.

Crie vários de uma vez — um objeto por linha, até 100 por chamada. Inclua externalId com o id do seu registro para achar o código depois:

curl -X POST https://api.codeqr.io/qrcodes/bulk \
  -H "Authorization: Bearer codeqr_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '[
    { "type": "url", "url": "https://example.com/table/1", "title": "Table 1", "static": false },
    { "type": "url", "url": "https://example.com/table/2", "title": "Table 2", "static": false }
  ]'

Resposta (200 OK, resumida): um array na mesma ordem — "key": "XD2lytoBgPOe-qr" e "key": "IS87MRzr7Gos-qr", cada um com seu shortLink. Códigos criados em massa voltam com "image": null; renderize-os com https://api.codeqr.io/qr?url=<shortLink> ou abra-os no app.

Guarde id, key e shortLink junto do seu registro. Imprima a imagem de image ou do endpoint /qr, ou exporte o SVG pelo app.
Para mudar para onde um código vai, envie PUT /qrcodes/{id} com { "url": "https://example.com/menu-v2" } — veja Altere o link de um QR Code já impresso. Para converter um registro estático, envie { "static": false }.
Para achar um código a partir do link curto impresso, chame GET /qrcodes/info?domain=qrup.link&key=iVx0OCFyDn79-qr. Para listar, GET /qrcodes?type=wifi&pageSize=2 devolve os dois códigos de Wi-Fi mais recentes; GET /qrcodes/count devolve o total (100 no workspace de teste).
Para excluir, DELETE /qrcodes/{id} devolve { "id": "…" }; uma leitura desse código passa a responder 302 https://codeqr.io/not-found. DELETE /qrcodes/bulk?qrcodeIds=id1,id2 devolve { "deletedCount": 2 } — passe os ids separados por vírgula num único parâmetro, não repetido.

Outros campos que você pode enviar: expiresAt + expiredUrl, password, folderId, tagIds, comments, trackConversion (Pro), rules (Regras inteligentes, Business, só dinâmicos), preRedirection + pageId (Business) e os campos de design (fgColor, bgColor, size, pattern, shape, frame, frameText, frameTextStyles, showLogo). Tipos além de url recebem o próprio objeto: wifi, whatsapp, vcard, email, phone, text, pix (só estático) — exemplos em Crie QR Codes de WhatsApp, Wi-Fi e cartão de visita.

Erros que você vai encontrar

422 — Mensagem (literal): invalid_type: type: Required · Correção: Envie type
422 — Mensagem (literal): custom: url: Invalid URL · Correção: URL absoluta com https://
400 — Mensagem (literal): Missing Wi-Fi SSID. / Missing PIX data. / Missing WhatsApp number. · Correção: Preencha o objeto do tipo
400 — Mensagem (literal): Invalid size. · Correção: size entre 128 e 5000
422 — Mensagem (literal): invalid_string: whatsapp.number: Invalid WhatsApp number (use E.164 digits, e.g. 5511999999999) · Correção: Só dígitos, com código do país
422 — Mensagem (literal): too_big: frameText: Frame text must be at most 200 characters · Correção: Encurte frameText
403 — Mensagem (literal): Smart rules can only be used on dynamic QR codes. · Correção: Remova rules ou envie static: false
403 — Mensagem (literal): You have reached the monthly limit of {N} qrcodes on the {Plan} plan. Please upgrade to add more QR Codes. · Correção: Espere o próximo ciclo, exclua códigos ou faça upgrade
409 — Mensagem (literal): Duplicate key: this qr code already exists. · Correção: Use outra key ou omita

Todo corpo de erro tem error.code, error.message e error.doc_url.

O mesmo pelo servidor MCP

Conecte seu cliente de IA a https://mcp.codeqr.io/mcp (OAuth 2.0). Peça, por exemplo:

Create a QR code for https://example.com/menu titled "Cafe menu".

O cliente chama create_qrcode com { "url": "https://example.com/menu", "title": "Cafe menu" } e recebe o objeto criado com key e shortLink. Tools disponíveis: create_qrcode (tipos url, text, email, phone, sms, wifi, vcard, crypto, whatsapp; mais domain, key, size, level, fgColor, bgColor), update_qrcode (qrcodeId + os mesmos campos, archived), list_qrcodes (page), delete_qrcode. As tools do MCP criam só códigos dinâmicos e não aceitam static, padrões de design, molduras, rules, tags, pastas, expiresAt nem password — use a API para isso.

Automações

Make: use o app da CodeQR; o módulo Make an API Call envia qualquer das requisições acima (método POST, URL /qrcodes, corpo como mostrado), que é como você cria um código por linha de planilha. O Make também recebe os eventos de QR Code abaixo.
Webhooks: em Configurações → Webhooks, assine qrcode.created, qrcode.updated, qrcode.deleted (nível do workspace) e, no Business, qrcode.scanned (escolhido por código, com país, cidade, dispositivo, navegador e sistema da leitura). Payloads: docs.codeqr.io.
Zapier: hoje não há gatilhos nem ações de QR Code (só eventos de link e lead); use um passo de webhook ou de requisição HTTP com as chamadas de API acima.

Como verificar

curl -sI -A "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X)" \
  https://qrup.link/XD2lytoBgPOe-qr | grep -iE "^HTTP|^location"
# HTTP/2 302
# location: https://example.com/table/1

Depois, GET /qrcodes/info?domain=qrup.link&key=XD2lytoBgPOe-qr mostra "scans": 1, e GET https://api.codeqr.io/analytics?event=clicks&groupBy=count&interval=24h&qrcodeId=cmsx899e5000hje43xlr42g24 devolve {"clicks":0,"scans":1,"views":0,"leads":0,"sales":0,"saleAmount":0}. groupBy=top_qrcodes lista os seus códigos com as leituras.

Solução de problemas

O código que criei pela API é estático

static tem padrão false, então os códigos são dinâmicos a menos que você envie "static": true. Confira o campo static na resposta.

`GET /qrcodes/{id}` devolve 404

Essa rota não existe. Use GET /qrcodes/info?domain=…&key=… ou GET /qrcodes?search=….

`DELETE /qrcodes/bulk` excluiu só um código

Parâmetros qrcodeIds= repetidos guardam só um valor. Envie-os separados por vírgula num único qrcodeIds.

A API criou um Pix dinâmico que abre a página inicial do domínio

Pix precisa ser estático: envie "static": true com type: "pix".

`DELETE /qrcodes/{id}` devolveu 500

Confira se o código ainda existe com GET /qrcodes/info?domain=…&key=… antes de repetir: nos nossos testes o código já tinha sido excluído mesmo com a resposta 500, e a repetição respondeu 404 "qrCode not found.".

`GET https://api.codeqr.io/qr?url=…` devolve 500

A url precisa ser um link curto da CodeQR de um código existente (https://<domínio>/<chave>-qr); outras URLs não são renderizadas.

Crie QR Codes com a API, o MCP e automações

Disponibilidade

Antes de começar

Endpoints

Passos: crie códigos a partir dos seus dados

Erros que você vai encontrar

O mesmo pelo servidor MCP

Automações

Como verificar

Solução de problemas

O código que criei pela API é estático

`GET /qrcodes/{id}` devolve 404

`DELETE /qrcodes/bulk` excluiu só um código

A API criou um Pix dinâmico que abre a página inicial do domínio

`DELETE /qrcodes/{id}` devolveu 500

`GET https://api.codeqr.io/qr?url=…` devolve 500

Artigos relacionados

Produto

Soluções

Recursos

Empresa

Legal

Crie QR Codes com a API, o MCP e automações

Disponibilidade

Antes de começar

Endpoints

Passos: crie códigos a partir dos seus dados

Erros que você vai encontrar

O mesmo pelo servidor MCP

Automações

Como verificar

Solução de problemas

O código que criei pela API é estático

GET /qrcodes/{id} devolve 404

DELETE /qrcodes/bulk excluiu só um código

A API criou um Pix dinâmico que abre a página inicial do domínio

DELETE /qrcodes/{id} devolveu 500

GET https://api.codeqr.io/qr?url=… devolve 500

Artigos relacionados

`GET /qrcodes/{id}` devolve 404

`DELETE /qrcodes/bulk` excluiu só um código

`DELETE /qrcodes/{id}` devolveu 500

`GET https://api.codeqr.io/qr?url=…` devolve 500