Como Criar Links Curtos 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 links curtos programaticamente. Com ela, você pode:

• Criar links curtos com URLs personalizadas e domínios customizados
• Personalizar aparência com custom preview para redes sociais
• Mascarar URLs com link cloaking para URLs complexas
• Rastrear conversões com conversion tracking avançado
• Otimizar SEO com links indexáveis pelos buscadores
• Configurar comportamentos como expiração, senha e redirecionamento
• Rastrear analytics e cliques 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 links curtos sem intervenção manual
• Escalabilidade: Gere milhares de links 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

• Marketing: Campanhas promocionais com conversion tracking
• E-commerce: Links para produtos com custom preview
• Redes sociais: Compartilhamento otimizado com preview personalizado
• Email marketing: Links rastreáveis em campanhas
• Afiliados: Links de referência e comissões
• SEO: Links indexáveis para melhor posicionamento
• URLs complexas: Cloaking para mascarar URLs longas
• Analytics: Rastreamento detalhado de conversões

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
2. Clique em "Create" para gerar uma nova chave
3. Selecione as permissões necessárias
4. Copie e armazene a chave de forma segura

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 Link Curto

Link básico

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

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

Resposta da API:

{
	"id": "clwc7hxcd0001ab6tqskb0h7v",
	"domain": "codeqr.link",
	"key": "site",
	"url": "https://codeqr.io",
	"archived": false,
	"expiresAt": null,
	"expiredUrl": null,
	"password": null,
	"externalId": null,
	"trackConversion": true,
	"proxy": true,
	"title": "CodeQR - Smart QR Codes, Short Links & Custom Pages",
	"description": "Create, manage, and track intelligent QR Codes, dynamic short links, and personalized landing pages. Boost engagement and gain valuable insights for your business.",
	"image": "https://res.cloudinary.com/dhnaggn4g/image/upload/c_thumb,w_200,g_face/v1750078911/static/codeqr_thumbnail_abgafw.png",
	"video": null,
	"utm_source": null,
	"utm_medium": null,
	"utm_campaign": null,
	"utm_term": null,
	"utm_content": null,
	"rewrite": false,
	"doIndex": false,
	"flexible": false,
	"filled": false,
	"ios": null,
	"android": null,
	"geo": null,
	"userId": "cloukebiw0000ig8g2q4w6vbp",
	"projectId": "clwazhjsm00002nx4heuc6vge",
	"preRedirection": false,
	"pageId": null,
	"pageUrl": null,
	"isFormMandatory": false,
	"publicStats": false,
	"clicks": 21,
	"lastClicked": "2025-08-30T12:16:06.000Z",
	"leads": 0,
	"sales": 0,
	"saleAmount": 0,
	"createdAt": "2024-05-18T14:31:08.557Z",
	"updatedAt": "2025-09-06T12:21:07.873Z",
	"tagId": null,
	"comments": "Link para landing page ",
	"notificationToken": null,
	"tags": [],
	"shortLink": "https://codeqr.link/site",
	"webhookIds": [],
	"qrCode": "https://api.codeqr.io/qr?url=https://codeqr.link/site?qr=1"
}

Campos importantes da resposta

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

shortLink - URL do link curto

• Use este campo para compartilhar o link
• Exemplo: https://codeqr.link/claim

id - Identificador único

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

key - Slug do link

• Nome personalizado (se fornecido)
• Exemplo: claim

url - URL de destino

• URL original para onde o link redireciona
• Exemplo: https://codeqr.io

domain - Domínio do link curto

• Domínio usado para o link curto
• Exemplo: codeqr.link

qrCode - URL da imagem do QR code

• QR code gerado automaticamente
• Exemplo: https://api.codeqr.io/qr?url=https://codeqr.link/site?qr=1

title - Título do link

• Título personalizado (se fornecido)
• Exemplo: "CodeQR - Smart QR Codes, Short Links & Custom Pages"

description - Descrição do link

• Descrição personalizada (se fornecida)
• Exemplo: "Create, manage, and track intelligent QR Codes"

image - Imagem do link

• URL da imagem personalizada (se fornecida)
• Exemplo: https://res.cloudinary.com/.../codeqr_thumbnail.png

clicks - Contador de cliques

• Atualizado em tempo real
• Exemplo: 21

leads - Contador de leads

• Número de leads gerados
• Exemplo: 0

sales - Contador de vendas

• Número de vendas realizadas
• Exemplo: 0

saleAmount - Valor total das vendas

• Soma dos valores das vendas
• Exemplo: 0

lastClicked - Último clique

• Timestamp do último clique registrado
• Exemplo: 2025-08-30T12:16:06.000Z

createdAt - Data de criação

• Timestamp ISO 8601
• Exemplo: 2024-05-18T14:31:08.557Z

updatedAt - Data da última atualização

• Timestamp da última modificação
• Exemplo: 2025-09-06T12:21:07.873Z

externalId - ID externo

• Identificador do seu sistema (se fornecido)
• Exemplo: PROD-001

userId - ID do usuário

• Identificador do usuário que criou o link
• Exemplo: cloukebiw0000ig8g2q4w6vbp

projectId - ID do projeto

• Identificador do projeto (se aplicável)
• Exemplo: clwazhjsm00002nx4heuc6vge

trackConversion - Rastreamento de conversão

• Se o link está configurado para rastrear conversões
• Exemplo: true

proxy - Custom preview

• Se o link usa preview personalizado
• Exemplo: true

rewrite - Link cloaking

• Se o link usa camuflagem de URL
• Exemplo: false

doIndex - Indexação SEO

• Se o link pode ser indexado pelos buscadores
• Exemplo: false

archived - Link arquivado

• Se o link está arquivado
• Exemplo: false

expiresAt - Data de expiração

• Timestamp de quando o link expira (se configurado)
• Exemplo: null

password - Senha de proteção

• Se o link está protegido por senha
• Exemplo: null

comments - Comentários

• Comentários internos sobre o link
• Exemplo: "Link para landing page"

tags - Tags associadas

• Array de tags do link
• Exemplo: []

💡 Dica: Os campos shortLink, clicks, leads, sales e lastClicked são especialmente úteis para monitorar a performance dos seus links em tempo real.

Exemplo em JavaScript

const response = await fetch("https://api.codeqr.io/links", {
  method: "POST",
  headers: {
    Authorization: "Bearer sua_chave_api",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://codeqr.io",
  }),
});

const link = await response.json();
console.log("Link criado:", link.shortLink);
console.log("QR Code:", link.qrCode);

Usando o Link Curto

Agora que você criou o link curto, você pode usá-lo em qualquer lugar:

Visite nosso site

Exemplo prático:

Campanha de Marketing

Acesse nossa promoção especial: https://codeqr.link/site

Clique no link para acesso rápido!

💡 Dica: Use o campo shortLink da resposta da API para compartilhar o link em campanhas, redes sociais, emails ou qualquer plataforma.

Personalizando Links Curtos

Aparência e identificação

Você pode personalizar completamente seu link curto:

Custom Link Preview

Personalize a aparência dos seus links quando compartilhados em redes sociais:

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "proxy": true,
    "title": "Promoção Especial - 50% OFF",
    "description": "Aproveite nossa promoção especial com 50% de desconto em todos os produtos. Oferta válida por tempo limitado!",
    "image": "https://exemplo.com/promo-banner.jpg"
  }'

Parâmetros de Custom Link Preview:

proxy (boolean) - Se o link curto usa o recurso de Visualização de link personalizado

• Padrão: false
• Obrigatório: Sim
• Exemplo: true

title (string | null) - O título do link curto

• Obrigatório: Sim
• Exemplo: "Promoção Especial - 50% OFF"

description (string | null) - A descrição do link curto

• Obrigatório: Sim
• Exemplo: "Aproveite nossa promoção especial com 50% de desconto"

image (string | null) - A imagem do link curto

• Obrigatório: Sim
• Exemplo: "https://exemplo.com/promo-banner.jpg"

💡 Dica: Quando proxy é true, o link curto mostrará uma página de preview personalizada antes de redirecionar para a URL final, permitindo controle total sobre como o link aparece em redes sociais.

Organização com tags

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://codeqr.io",
    "tagIds": ["tag1", "tag2"],
    "tagNames": "campanha-marketing"
  }'

Configurações Avançadas

Controle de acesso

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

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://codeqr.io/",
    "password": "123456",
    "expiresAt": "2026-12-31T23:59:59Z",
    "expiredUrl": "https://exemplo.com/expirado"
  }'

Clique no linnk apaixo e use a senha 123456 para acessar:

Link protegido

Redirecionamento por dispositivo

Direcione usuários para diferentes URLs baseado no dispositivo:

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "ios": "https://apps.apple.com/app/exemplo",
    "android": "https://play.google.com/store/apps/details?id=com.exemplo"
  }'

Redirecionamento por localização

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

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "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 links:

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

Monitoramento de Conversão

Monitore conversões para medir a eficácia das suas campanhas de marketing:

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "trackConversion": true,
    "utm_source": "facebook",
    "utm_medium": "social",
    "utm_campaign": "black_friday"
  }'

Parâmetros de Conversion Tracking:

trackConversion (boolean) - Se deve rastrear conversões para o link curto

• Padrão: false
• Exemplo: true

💡 Dica: Com conversion tracking ativado, você pode monitorar leads, vendas e valores de conversão diretamente no dashboard da CodeQR.

Camuflagem de Links

Mascare sua URL de destino para que os usuários vejam apenas o link curto na barra de endereços:

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com/pagina-muito-longa-e-complexa",
    "rewrite": true,
    "key": "link-limpo"
  }'

Parâmetros de Link Cloaking:

rewrite (boolean) - Se o link curto usa camuflagem de link

• Padrão: false
• Obrigatório: Sim
• Exemplo: true

💡 Dica: Com rewrite: true, a URL de destino fica completamente oculta. Os usuários sempre verão apenas o link curto na barra de endereços, mesmo após o redirecionamento.

Search Engine Indexing

Permita que mecanismos de busca indexem seu link curto:

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "doIndex": true,
    "title": "Página Importante",
    "description": "Conteúdo que deve ser indexado pelos buscadores"
  }'

Parâmetros de Search Engine Indexing:

doIndex (boolean) - Permitir que os mecanismos de busca indexem seu link curto

• Padrão: false
• Exemplo: true

💡 Dica: Por padrão, os links curtos não são indexados pelos buscadores. Use doIndex: true apenas quando quiser que o link curto apareça nos resultados de busca. Saiba mais: https://codeqr.link/noindex

Operações em Lote

Criando múltiplos links

Crie até 100 links de uma vez:

curl --request POST \
  --url https://api.codeqr.io/links/bulk \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "url": "https://produto1.com",
      "key": "produto-1"
    },
    {
      "url": "https://produto2.com",
      "key": "produto-2"
    },
    {
      "url": "https://produto3.com",
      "key": "produto-3"
    }
  ]'

⚠️ Limitações das operações em lote:

• Não suporta previews customizados
• Não dispara eventos de webhook
• Máximo de 100 links por requisição

Atualizando múltiplos links

Atualize até 100 links com os mesmos dados:

curl --request PATCH \
  --url https://api.codeqr.io/links/bulk \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "link_ids": ["link1", "link2", "link3"],
    "data": {
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "tagIds": ["campanha-2025"]
    }
  }'

Deletando múltiplos links

curl --request DELETE \
  --url https://api.codeqr.io/links/bulk?linkIds=link1,link2,link3 \
  --header 'Authorization: Bearer codeqr_your_api_key'

Organização de Links

External ID

Use externalId para associar links com seu sistema:

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "externalId": "12345"
  }'

Recuperar link por externalId:

curl --request GET \
  --url "https://api.codeqr.io/links/info?external_id=12345" \
  --header 'Authorization: Bearer codeqr_your_api_key'

Tenant ID

Agrupe links por tenant (usuário/equipe):

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "tenantId": "usuario123"
  }'

Recuperar links por tenantId:

curl --request GET \
  --url "https://api.codeqr.io/links?tenantId=usuario123" \
  --header 'Authorization: Bearer codeqr_your_api_key'

Tags

Organize links com tags:

curl --request POST \
  --url https://api.codeqr.io/links \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "tagIds": ["clux0rgak00011..."]
  }'

Recuperar links por tags:

curl --request GET \
  --url "https://api.codeqr.io/links?tagNames=marketing" \
  --header 'Authorization: Bearer codeqr_your_api_key'

Exemplos Práticos

1. Link para E-commerce

async function criarLinkProduto(produto) {
  const response = await fetch("https://api.codeqr.io/links", {
    method: "POST",
    headers: {
      Authorization: "Bearer codeqr_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: `https://loja.com/produto/${produto.id}`,
      key: `produto-${produto.id}`,
      title: produto.nome,
      description: `Link para ${produto.nome}`,
      externalId: produto.sku,
      utm_source: "ecommerce",
      utm_medium: "link_curto",
      utm_campaign: "produto",
      tagIds: ["produtos", "ecommerce"],
    }),
  });

  return await response.json();
}

// Uso
const produto = {
  id: 123,
  nome: "Smartphone XYZ",
  sku: "SP-123",
};

const link = await criarLinkProduto(produto);
console.log("Link criado:", link.shortLink);

2. Link para Campanha de Marketing

import requests
import json

def criar_link_campanha(url_destino, nome_campanha, canal):
    data = {
        "url": url_destino,
        "key": f"campanha-{nome_campanha.lower().replace(' ', '-')}",
        "title": f"Campanha - {nome_campanha}",
        "description": f"Link para campanha {nome_campanha} via {canal}",
        "utm_source": canal,
        "utm_medium": "link_curto",
        "utm_campaign": nome_campanha.lower().replace(' ', '-'),
        "tagNames": [nome_campanha, canal]
    }

    response = requests.post(
        'https://api.codeqr.io/links',
        headers={
            'Authorization': 'Bearer codeqr_your_api_key',
            'Content-Type': 'application/json'
        },
        data=json.dumps(data)
    )

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Erro: {response.status_code} - {response.text}")

# Uso
link_campanha = criar_link_campanha(
    "https://promocao.com/desconto-50",
    "Black Friday 2025",
    "email"
)
print(f"Link da campanha criado: {link_campanha['shortLink']}")

3. Link para Afiliados

<?php
function criarLinkAfiliado($url_destino, $afiliado_id, $produto_id) {
    $data = [
        'url' => $url_destino,
        'key' => "afiliado-{$afiliado_id}-{$produto_id}",
        'title' => "Link de Afiliado - Produto {$produto_id}",
        'description' => "Link de afiliado para produto {$produto_id}",
        'externalId' => "afiliado_{$afiliado_id}_{$produto_id}",
        'utm_source' => 'afiliado',
        'utm_medium' => 'link_curto',
        'utm_campaign' => "produto_{$produto_id}",
        'utm_content' => "afiliado_{$afiliado_id}",
        'tagIds' => ['afiliados', "produto-{$produto_id}"]
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://api.codeqr.io/links');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer codeqr_your_api_key',
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Erro ao criar link: $httpCode");
    }
}

// Uso
$link_afiliado = criarLinkAfiliado(
    "https://loja.com/produto/123",
    "AF001",
    "123"
);
echo "Link de afiliado criado: " . $link_afiliado['shortLink'];
?>

4. Link com Custom Preview para Redes Sociais

async function criarLinkComPreview(url, titulo, descricao, imagem) {
  const response = await fetch("https://api.codeqr.io/links", {
    method: "POST",
    headers: {
      Authorization: "Bearer codeqr_your_api_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      url: url,
      proxy: true,
      title: titulo,
      description: descricao,
      image: imagem,
      trackConversion: true,
      utm_source: "social_media",
      utm_medium: "custom_preview",
      utm_campaign: "viral_campaign",
    }),
  });

  return await response.json();
}

// Uso
const linkPreview = await criarLinkComPreview(
  "https://exemplo.com/promocao",
  "🔥 Promoção Relâmpago - 70% OFF!",
  "Últimas 24h! Aproveite nossa maior promoção do ano com 70% de desconto em todos os produtos. Frete grátis!",
  "https://exemplo.com/banner-promocao.jpg"
);

console.log("Link com preview criado:", linkPreview.shortLink);

5. Link com Cloaking para URLs Complexas

import requests
import json

def criar_link_cloaking(url_original, slug_personalizado):
    """
    Cria um link curto com cloaking para mascarar URLs complexas
    """
    data = {
        "url": url_original,
        "key": slug_personalizado,
        "rewrite": True,
        "title": "Acesso Direto",
        "description": "Link direto para o conteúdo",
        "trackConversion": True,
        "utm_source": "cloaking",
        "utm_medium": "clean_url"
    }

    response = requests.post(
        'https://api.codeqr.io/links',
        headers={
            'Authorization': 'Bearer codeqr_your_api_key',
            'Content-Type': 'application/json'
        },
        data=json.dumps(data)
    )

    if response.status_code == 200:
        return response.json()
    else:
        raise Exception(f"Erro: {response.status_code} - {response.text}")

# Uso
url_complexa = "https://exemplo.com/categoria/produto/123?utm_source=email&utm_medium=newsletter&utm_campaign=promocao&ref=cliente&token=abc123"
link_limpo = criar_link_cloaking(url_complexa, "produto-especial")

print(f"URL original: {url_complexa}")
print(f"Link limpo: {link_limpo['shortLink']}")

6. Link Indexável para SEO

<?php
function criarLinkIndexavel($url, $titulo, $descricao, $palavras_chave) {
    $data = [
        'url' => $url,
        'key' => strtolower(str_replace(' ', '-', $palavras_chave)),
        'title' => $titulo,
        'description' => $descricao,
        'doIndex' => true,
        'trackConversion' => true,
        'utm_source' => 'seo',
        'utm_medium' => 'organic',
        'tagNames' => ['seo', 'indexavel']
    ];

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, 'https://api.codeqr.io/links');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer sua_chave_api',
        'Content-Type: application/json'
    ]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode === 200) {
        return json_decode($response, true);
    } else {
        throw new Exception("Erro ao criar link indexável: $httpCode");
    }
}

// Uso
$link_seo = criarLinkIndexavel(
    "https://exemplo.com/guia-completo-marketing-digital",
    "Guia Completo de Marketing Digital 2025",
    "Aprenda as melhores estratégias de marketing digital para 2025. Dicas práticas, ferramentas e cases de sucesso.",
    "marketing digital 2025"
);

echo "Link indexável criado: " . $link_seo['shortLink'];
?>

Gerenciando Links

Atualizando um link

Use o ID do link para atualizá-lo:

curl --request PATCH \
  --url https://api.codeqr.io/links/link_eBKA4MT44XnI17hYLchkjUOd \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://novo-destino.com",
    "title": "Novo título"
  }'

Upsert (Criar ou Atualizar)

O upsert cria um novo link se não existir, ou atualiza se já existir:

curl --request POST \
  --url https://api.codeqr.io/links/update \
  --header 'Authorization: Bearer codeqr_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "url": "https://exemplo.com",
    "key": "link-estavel"
  }'

Deletando um link

curl --request DELETE \
  --url https://api.codeqr.io/links/link_eBKA4MT44XnI17hYLchkjUOd \
  --header 'Authorization: Bearer codeqr_your_api_key'

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 link

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

• Use operações em lote para criar múltiplos links
• 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. Organização

• Use tags para categorizar links
• Implemente externalId para integração com seu sistema
• Use tenantId para multi-tenancy
• Mantenha nomenclatura consistente

Próximos Passos

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

1. Gerenciamento de Links

• Como atualizar links existentes
• Como listar e buscar links
• Como deletar links

2. Operações em Lote

• Criação em massa de links
• 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

Recursos Adicionais

Documentação Oficial

• Documentação completa da API
• Endpoint de criação de links
• 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 links curtos programaticamente. Com este guia, você aprendeu:

• ✅ Como configurar autenticação e fazer sua primeira requisição
• ✅ Como personalizar aparência e comportamento dos links
• ✅ Conversion tracking para medir eficácia de campanhas
• ✅ Custom link preview para redes sociais
• ✅ Link cloaking para mascarar URLs complexas
• ✅ Search engine indexing para otimização SEO
• ✅ Diferentes formas de organizar e categorizar links
• ✅ 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 links curtos 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.