Como Criar QR Codes via API da CodeQR: Guia Completo

O que é a API da CodeQR?

A API da CodeQR é uma interface RESTful que permite criar, gerenciar e rastrear QR codes programaticamente. Com ela, você pode:

• Criar QR codes de diferentes tipos (URL, texto, WiFi, email, etc.)
• Personalizar aparência com cores, tamanhos e logos
• Configurar comportamentos como expiração, senha e redirecionamento
• Rastrear analytics e escaneamentos em tempo real
• Integrar webhooks para eventos automáticos

Por que usar a API da CodeQR?

Vantagens da integração via API

• Automação completa: Crie QR codes sem intervenção manual
• Escalabilidade: Gere milhares de QR codes rapidamente
• Personalização avançada: Controle total sobre aparência e comportamento
• Integração simples: Funciona com qualquer linguagem de programação
• Analytics detalhados: Rastreie performance e engajamento

Casos de uso comuns

• E-commerce: QR codes para produtos e campanhas
• Eventos: Check-in e informações para participantes
• Marketing: Campanhas promocionais e tracking
• WiFi: Compartilhamento de credenciais de rede
• Contatos: vCards para networking profissional

Configuração Inicial

1. Obter sua chave de API

Para começar, você precisa de uma chave de API válida:

1. Acesse Settings > API Keys no seu dashboard da CodeQR

1. Clique em "Create" para gerar uma nova chave
2. Selecione as permissões necessárias
3. Copie e armazene a chave de forma segura

Saiba mais sobre como obter sua chave de API.

2. Configurar autenticação

Todas as requisições devem incluir sua chave de API no header de autorização:

Authorization: Bearer codeqr_xxxxxxxx

3. Obter o Project Slug

Além da chave de API, você precisa do project slug do seu projeto. Este parâmetro é obrigatório em todas as requisições:

Como encontrar o project slug:

1. Acesse seu projeto no dashboard da CodeQR
2. O slug aparece na URL: app.codeqr.io/[acme]
3. Exemplo: se a URL é app.codeqr.io/acme, o slug é marketing
4. Ou vá em Settings > Project para ver o slug configurado

4. Base URL da API

Todas as requisições devem ser feitas para:

https://api.codeqr.io

Importante: Todas as requisições devem incluir o parâmetro projectSlug na query string.

Criando seu Primeiro QR Code

QR Code básico de URL

O parâmetro mínimo necessário é a url de destino:

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "url",
    "url": "https://codeqr.io/blog",
}'

Escaneie para acessar

Resposta da API:

 {
	"id": "cmf6yawg30001pqrwjhd1bdxe",
	"domain": "expol.ink",
	"key": "iympEuajxgeP-qr",
	"archived": false,
	"expiresAt": null,
	"expiredUrl": null,
	"password": null,
	"externalId": null,
	"trackConversion": false,
	"proxy": false,
	"title": null,
	"description": null,
	"image": "https://res.cloudinary.com/dhnaggn4g/image/upload/v1757085378/expol.ink/iympEuajxgeP-qr.png",
	"utm_source": null,
	"utm_medium": null,
	"utm_campaign": null,
	"utm_term": null,
	"utm_content": null,
	"rewrite": false,
	"doIndex": false,
	"flexible": false,
	"filled": true,
	"ios": null,
	"android": null,
	"geo": null,
	"static": false,
	"type": "url",
	"contentStatic": null,
	"text": null,
	"email": null,
	"wifi": null,
	"url": "https://codeqr.io/blog",
	"phone": null,
	"vcard": null,
	"crypto": null,
	"sms": null,
	"facetime": null,
	"latlog": null,
	"pix": null,
	"logo": null,
	"bgColor": "#FFFFFF",
	"fgColor": "#000000",
	"size": 1024,
	"level": "H",
	"showLogo": true,
	"src": "https://res.cloudinary.com/dhnaggn4g/image/upload/v1741477675/logos/clwazhjsm00002nx4heuc6vge.png",
	"height": 153,
	"width": 153,
	"excavate": true,
	"pattern": "default",
	"shape": "none",
	"frame": "none",
	"frameColor": "#000000",
	"frameText": null,
	"userId": "cmbsr6sky0000ljvvbzz5qjkj",
	"projectId": "clwazhjsm00002nx4heuc6vge",
	"preRedirection": false,
	"pageId": null,
	"pageUrl": null,
	"isFormMandatory": false,
	"publicStats": false,
	"scans": 0,
	"lastClicked": null,
	"leads": 0,
	"sales": 0,
	"saleAmount": 0,
	"createdAt": "2025-09-05T14:49:17.761Z",
	"updatedAt": "2025-09-05T15:16:21.270Z",
	"tagId": null,
	"comments": "",
	"notificationToken": null,
	"tags": [],
	"shortLink": "https://expol.ink/iympEuajxgeP-qr",
	"webhookIds": []
}

Campos importantes da resposta

A resposta da API contém vários campos úteis que você pode usar em sua aplicação:

image - URL da imagem do QR code

• Use este campo para exibir o QR code
• Exemplo: https://res.cloudinary.com/.../qr.png

shortLink - Link encurtado

• Redireciona para a URL original
• Exemplo: https://expol.ink/zfNIPj8Mv24Q-qr

id - Identificador único

• Use para futuras operações (atualizar, deletar)
• Exemplo: cm9zsbu1f00019imtllva1p35

key - Slug personalizado

• Nome personalizado (se fornecido)
• Exemplo: zfNIPj8Mv24Q-qr

scans - Contador de escaneamentos

• Atualizado em tempo real
• Exemplo: 500

createdAt - Data de criação

• Timestamp ISO 8601
• Exemplo: 2025-04-27T15:09:08.689Z

💡 Dica: O campo image é especialmente importante - ele contém a URL direta para a imagem do QR code que você pode usar em sua aplicação, site ou impressões.

Exemplo em JavaScript

const response = await fetch("https://api.codeqr.io/qrcodes?projectSlug=acme", {
  method: "POST",
  headers: {
    Authorization: "Bearer codeqr_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "url",
    url: "https://codeqr.io/blog",
  }),
});

const qrCode = await response.json();
console.log("QR Code criado:", qrCode.shortLink);
console.log("Imagem do QR Code:", qrCode.image);

Personalizando QR Codes

Aparência visual

Você pode personalizar completamente a aparência do seu QR code:

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
	"type": "url",
	"url": "https://codeqr.io/blog",
	"static": false,
	"bgColor": "#fff5b1",
	"fgColor": "#0017e5",
	"showLogo": true,
	"pattern": "diamond",
	"shape": "square",
	"frame": "none"
}'

Resultado

Parâmetros de personalização

bgColor (string) - A cor de fundo do QR code

• Exemplo: #fff5b1

fgColor (string) - A cor de primeiro plano do QR code

• Exemplo: #0017e5

size (number) - O tamanho do QR code

• Exemplo: 1024

level (string) - O nível de correção de erro do QR code

• Exemplo: M

showLogo (boolean) - Se o logo deve ser exibido no QR code

• Exemplo: true

src (string | null) - A URL da imagem do QR code

• Exemplo: enter src

height (number) - A altura do QR code

• Exemplo: 256

width (number) - A largura do QR code

• Exemplo: 256

excavate (boolean) - Se o QR code deve ter áreas escavadas

• Exemplo: true

pattern (string) - O padrão de forma dos módulos do QR code

• Valores aceitos: default, circles, diamond, triangles, squares, circles, stars, hearts
• Exemplo: diamond

shape (string) - A forma do design ao redor do QR code

• Valores aceitos: none, square, circle
• Exemplo: circle

Organização e identificação

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://codeqr.io/blog",
    "key": "meu-qr-personalizado",
    "title": "QR Code do Produto",
    "description": "QR code para página do produto",
    "externalId": "PROD-001",
    "tagIds": ["tag1", "tag2"]
  }'

Tipos de QR Code Disponíveis

1. QR Code de Texto

curl --request POST \
  --url https://api.codeqr.io/qrcodes \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "url",
    "url": "https://codeqr.io/blog",
}'

2. QR Code de Texto

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "text",
    "text": "Olá! Este é um QR code de texto."
  }'

3. QR Code de Email

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "email",
    "email": {
      "to": "contact@codeqr.io",
      "subject": "Assunto do email",
      "body": "Corpo do email"
    }
  }'

4. QR Code de WiFi

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "wifi",
    "wifi": {
      "ssid": "NomeDaRede",
      "password": "senha123",
      "security": "WPA"
    }
  }'

5. QR Code de Telefone

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "phone",
    "phone": "+5511999999999"
  }'

6. QR Code de Localização

curl --request POST \
  --url https://api.codeqr.io/qrcodes \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "latlog",
    "latlog": {
      "latitude": -23.5505,
      "longitude": -46.6333
    }
  }'

Configurações Avançadas

Controle de acesso

Proteja seus QR codes com senha e data de expiração:

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "url",
    "url": "https://codeqr.io/blog",
    "password": "password123",
    "expiresAt": "2025-12-05T17:10:00.000Z",
  }'

Redirecionamento por dispositivo

Direcione usuários para diferentes URLs baseado no dispositivo:

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://codeqr.io/blog",
    "ios": "https://apps.apple.com/us/app/qr-code-generator-and-reader/id1623860555",
    "android": "https://play.google.com/store/apps/details?id=com.losenvo.codeqrlink"
  }'

Redirecionamento por localização

Personalize a experiência baseada na localização do usuário:

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "url",
    "url": "https://codeqr.io/blog",
    "geo": {
      "BR": "https://exemplo.com/brasil",
      "US": "https://exemplo.com/usa",
      "GB": "https://exemplo.com/uk"
    }
  }'

Parâmetros UTM para analytics

Rastreie a performance dos seus QR codes:

curl --request POST \
  --url https://api.codeqr.io/qrcodes?projectSlug=acme \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "url",
    "url": "https://exemplo.com",
    "utm_source": "marketing",
    "utm_medium": "qr_code",
    "utm_campaign": "promocao_2025",
    "utm_term": "produto",
    "utm_content": "banner"
  }'

Tratamento de Erros

Códigos de erro comuns

bad_request (400) - Requisição malformada

• Solução: Verificar formato dos dados

unauthorized (401) - Chave de API inválida

• Solução: Verificar chave de API

forbidden (403) - Sem permissão

• Solução: Verificar permissões da chave

not_found (404) - Recurso não encontrado

• Solução: Verificar ID/URL do QR code

conflict (409) - Conflito (ex: key duplicada)

• Solução: Usar key única

rate_limit_exceeded (429) - Rate limit excedido

• Solução: Aguardar e tentar novamente

internal_server_error (500) - Erro interno do servidor

• Solução: Tentar novamente mais tarde
  

Melhores Práticas

1. Segurança

• Nunca exponha chaves de API no frontend
• Use variáveis de ambiente para armazenar credenciais
• Implemente rotação regular de chaves
• Use chaves com permissões mínimas necessárias

2. Performance

• Implemente cache para QR codes frequentemente acessados
• Use paginação para listas grandes
• Monitore rate limits e implemente retry logic
• Considere webhooks para atualizações em tempo real

3. Monitoramento

• Implemente logging para todas as operações
• Use UTM parameters para rastreamento
• Configure alertas para erros críticos
• Monitore uso anômalo de API

4. Validação

• Valide todas as URLs antes de criar QR codes
• Verifique formatos de dados obrigatórios
• Teste em diferentes dispositivos e navegadores
• Implemente validação de entrada robusta

Próximos Passos

Agora que você sabe como criar QR codes via API, explore estas funcionalidades avançadas:

1. Gerenciamento de QR Codes

• Como atualizar QR codes existentes
• Como listar e buscar QR codes
• Como deletar QR codes

2. Operações em Lote

• Criação em massa de QR codes
• Atualização em lote
• Exclusão em lote

3. Recursos Avançados

• Configuração de webhooks
• Analytics e rastreamento
• Rate limits e otimização

4. Integração com SDKs

• SDKs disponíveis
• SDK TypeScript
• SDK Python

Recursos Adicionais

Documentação Oficial

• Documentação completa da API
• Endpoint de criação de QR codes
• Guia de autenticação

Artigos Relacionados

• Como usar link cloaking na CodeQR
• Como criar links protegidos por senha
• Como usar tags na CodeQR
• Integração com ActiveCampaign

Suporte

• Central de Ajuda
• Contato por Email

Conclusão

A API da CodeQR oferece uma solução completa e flexível para criar QR codes programaticamente. Com este guia, você aprendeu:

• ✅ Como configurar autenticação e fazer sua primeira requisição
• ✅ Como personalizar aparência e comportamento dos QR codes
• ✅ Diferentes tipos de QR codes disponíveis
• ✅ Configurações avançadas para casos específicos
• ✅ Exemplos práticos em JavaScript, Python e PHP
• ✅ Tratamento de erros e melhores práticas

Agora você está pronto para integrar a criação de QR codes em suas aplicações e aproveitar todo o potencial da plataforma CodeQR!

Este artigo foi útil? Compartilhe com sua equipe e explore outros recursos da documentação da CodeQR.