API•
How to Create Short Links via the CodeQR API: Complete Guide
Learn how to use the CodeQR API to programmatically create short links and integrate this functionality into your applications.
CodeQR Team
콘텐츠 팀
Learn how to use the CodeQR API to programmatically create short links and integrate this functionality into your applications.
Como Criar QR Codes via API da CodeQR: Guia Completo
The CodeQR API is a RESTful interface that lets you create, manage, and track short links programmatically. With it, you can:
To get started, you need a valid API key:
All requests must include your API key in the authorization header:
Authorization: Bearer codeqr_xxxxxxxx
In addition to your API key, you need your project's project slug. This parameter is required for all requests:
How to find your project slug:
All requests must be made to:
https://api.codeqr.io
Important: All requests must include the projectSlug parameter in the query string.
The minimum required parameter is the destination url:
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"}'
API response:
{
"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"
}
The API response contains several useful fields you can use in your application:
shortLink - Short link URL
id - Unique identifier
key - Link slug
url - Destination URL
domain - Short link domain
qrCode - QR code image URL
title - Link title
description - Link description
image - Link image
clicks - Click counter
leads - Leads counter
sales - Sales counter
saleAmount - Total sales amount
lastClicked - Last click
createdAt - Creation date
updatedAt - Last update date
externalId - External ID
userId - User ID
projectId - Project ID
trackConversion - Conversion tracking
proxy - Custom preview
rewrite - Link cloaking
doIndex - SEO indexing
archived - Archived link
expiresAt - Expiration date
password - Password protection
comments - Comments
tags - Associated tags
💡 Tip: The fields shortLink, clicks, leads, sales, and lastClicked are especially useful for monitoring the real-time performance of your links.
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);
Now that you've created the short link, you can use it anywhere:
Practical example:
Marketing Campaign
Access our special promotion: https://codeqr.link/site
Click the link for quick access!
💡 Tip: Use the shortLink field from the API response to share the link in campaigns, on social networks, in emails, or any platform.
You can completely customize your short link:
Customize the look of your links when shared on social networks:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com",
"proxy": true,
"title": "Special Promotion - 50% OFF",
"description": "Take advantage of our special promotion with 50% off on all products. Offer valid for a limited time!",
"image": "https://example.com/promo-banner.jpg"
}'
Custom Link Preview parameters:
proxy (boolean) - If the short link uses the Custom Link Preview feature
title (string | null) - The title of the short link
description (string | null) - The description of the short link
image (string | null) - The short link image
💡 Tip: When proxy is true, the short link will display a custom preview page before redirecting to the final URL, giving full control over how the link appears on social networks.
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": "marketing-campaign"
}'
Protect your links with password and expiration date:
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://examplo.com/expirado"
}'
Click the link below and use password 123456 to access:
Redirect users to different URLs based on device:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://examplo.com",
"ios": "https://apps.apple.com/app/examplo",
"android": "https://play.google.com/store/apps/details?id=com.examplo"
}'
Personalize the experience based on user's location:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://examplo.com",
"geo": {
"BR": "https://examplo.com/brasil",
"US": "https://examplo.com/usa",
"GB": "https://examplo.com/uk"
}
}'
Track your link performance:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://examplo.com",
"utm_source": "marketing",
"utm_medium": "email",
"utm_campaign": "promotion_2025",
"utm_term": "product",
"utm_content": "banner"
}'
Monitor conversions to measure your marketing campaign effectiveness:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://examplo.com",
"trackConversion": true,
"utm_source": "facebook",
"utm_medium": "social",
"utm_campaign": "black_friday"
}'
Conversion Tracking parameters:
trackConversion (boolean) - Whether to track conversions for the short link
💡 Tip: With conversion tracking enabled, you can monitor leads, sales, and conversion values directly from the CodeQR dashboard.
Mask your destination URL so users only see the short link in the address bar:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com/very-long-and-complex-page",
"rewrite": true,
"key": "clean-link"
}'
Link Cloaking parameters:
rewrite (boolean) - Whether the short link uses link cloaking
💡 Tip: With rewrite: true, the destination URL is completely hidden. Users will always see only the short link in the address bar, even after redirection.
Allow search engines to index your short link:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com",
"doIndex": true,
"title": "Important Page",
"description": "Content that should be indexed by search engines"
}'
Search Engine Indexing parameters:
doIndex (boolean) - Allow search engines to index your short link
💡 Tip: By default, short links are not indexed by search engines. Use doIndex: true only if you want your short link to appear in search results. Learn more: https://codeqr.link/noindex
Create up to 100 links at once:
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://product1.com",
"key": "product-1"
},
{
"url": "https://product2.com",
"key": "product-2"
},
{
"url": "https://product3.com",
"key": "product-3"
}
]'
⚠️ Batch operation limitations:
Update up to 100 links with the same data:
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": ["campaign-2025"]
}
}'
curl --request DELETE \ --url https://api.codeqr.io/links/bulk?linkIds=link1,link2,link3 \ --header 'Authorization: Bearer codeqr_your_api_key'
Use externalId to associate links with your system:
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com",
"externalId": "12345"
}'
Retrieve link by externalId:
curl --request GET \ --url "https://api.codeqr.io/links/info?external_id=12345" \ --header 'Authorization: Bearer codeqr_your_api_key'
Group links by tenant (user/team):
curl --request POST \
--url https://api.codeqr.io/links \
--header 'Authorization: Bearer codeqr_your_api_key' \
--header 'Content-Type: application/json' \
--data '{
"url": "https://example.com",
"tenantId": "usuario123"
}'
Retrieve links by tenantId:
curl --request GET \ --url "https://api.codeqr.io/links?tenantId=usuario123" \ --header 'Authorization: Bearer codeqr_your_api_key'
Organize links with 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://example.com",
"tagIds": ["clux0rgak00011..."]
}'
Retrieve links by tags:
curl --request GET \ --url "https://api.codeqr.io/links?tagNames=marketing" \ --header 'Authorization: Bearer codeqr_your_api_key'
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);
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']}")
<?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'];
?>
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);
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']}")
<?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'];
?>
Use the link ID to update it:
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 creates a new link if it doesn't exist, or updates it if it does:
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"
}'
curl --request DELETE \ --url https://api.codeqr.io/links/link_eBKA4MT44XnI17hYLchkjUOd \ --header 'Authorization: Bearer codeqr_your_api_key'
bad_request (400) - Badly formed request
unauthorized (401) - Invalid API key
forbidden (403) - No permission
not_found (404) - Resource not found
conflict (409) - Conflict (e.g., duplicate key)
rate_limit_exceeded (429) - Rate limit exceeded
internal_server_error (500) - Internal server error
Now that you know how to create short links via API, explore these advanced features:
The CodeQR API offers a complete and flexible solution for programmatically creating short links. With this guide, you have learned:
Now you are ready to integrate short link creation into your applications and take full advantage of the CodeQR platform!
Was this article helpful? Share it with your team and explore other resources in the CodeQR documentation.