Você tem 500 produtos no Mercado Livre e precisa gerar links curtos para cada um via script. Copiar e colar manualmente não é opção. Um api encurtador de url python tutorial resolve exatamente isso: automatizar a criação de links curtos dentro do seu código, sem interface gráfica, sem cliques manuais.
Neste tutorial, você vai aprender a integrar a API do HitURL em Python usando a biblioteca requests, desde a primeira requisição até casos avançados como encurtamento em lote, targeting geográfico e geração de QR Codes.
Por que usar uma API de encurtador de URL com Python?
Python é a linguagem mais usada em automação de marketing e ciência de dados no Brasil. Quando você combina Python com uma API de encurtamento, você ganha controle total sobre seus links: cria, rastreia, atualiza e remove sem nunca abrir um painel.
O cenário típico é uma campanha no Instagram ou WhatsApp Business com dezenas de URLs rastreadas. Sem automação, alguém precisa encurtar cada link individualmente, adicionar parâmetros UTM, configurar redirecionamentos. Com Python e uma API, todo esse fluxo vira um script de 30 linhas.
Automatizar o encurtamento de URLs via API reduz o tempo de setup de campanhas em até 90%, eliminando etapas manuais repetitivas que geram erros de digitação e perda de dados de rastreamento.
Segundo uma pesquisa da Python Software Foundation, a biblioteca requests é o pacote mais baixado do ecossistema Python, com mais de 200 milhões de downloads mensais. Isso significa que a base para consumir qualquer API REST já está pronta e testada por milhões de desenvolvedores.
Como funciona a API do HitURL
A API do HitURL segue o padrão REST. Você envia uma requisição HTTP POST com sua chave de API e a URL longa. A API responde com um JSON contendo o link curto, dados de rastreamento e metadados.
Para começar, você precisa de uma conta gratuita no HitURL e uma chave de API. A chave fica disponível no painel assim que você cria sua conta. Se você ainda não tem uma, acesse o HitURL e crie agora mesmo. É grátis.
Endpoints principais
- POST /api/v1/links: cria um novo link curto
- GET /api/v1/links: lista todos os links criados
- GET /api/v1/links/{id}: retorna detalhes e estatísticas de um link
- POST /api/v1/qr-codes: gera um QR Code dinâmico para um link
A API do HitURL retorna JSON em todas as respostas, o que significa que você pode integrar com Python, JavaScript, PHP, ou qualquer linguagem que faça requisições HTTP e parseie JSON.
Se você quiser explorar integrações com ferramentas no-code antes de mergulhar no Python, confira nosso guia sobre como automatizar envios de links com n8n e a API do HitURL. É uma boa introdução ao conceito de automação antes de programar.
Passo a passo: integrar API encurtador de URL em Python
Aqui está o tutorial completo, do zero ao primeiro link curto gerado por código. Vamos usar a biblioteca requests, que é o padrão de fato para consumo de APIs em Python.
Passo 1: Instalar a biblioteca requests
Abra o terminal e instale a biblioteca:
pip install requests
A documentação oficial da biblioteca está disponível em requests.readthedocs.io e cobre desde o básico até casos avançados como autenticação OAuth e sessões persistentes.
Passo 2: Obter sua chave de API no HitURL
Faça login no painel do HitURL. Vá até Configurações e depois API. Sua chave de API aparece ali. Copie e guarde em uma variável de ambiente, nunca no código diretamente.
Defina a variável de ambiente no terminal:
export HITURL_API_KEY="sua-chave-aqui"
Passo 3: Fazer a primeira requisição
Crie um arquivo chamado encurtar.py e adicione o seguinte código:
import os
import requests
API_KEY = os.environ.get("HITURL_API_KEY")
BASE_URL = "https://hiturl.at/api/v1/links"
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json"
}
payload = {
"url": "https://www.mercadolivre.com.br/anuncio/exemplo-produto-123",
"alias": "promo-iphone-13"
}
response = requests.post(BASE_URL, headers=headers, json=payload)
data = response.json()
print(f"Link curto: {data.get('short_url')}")
print(f"Total de cliques: {data.get('clicks', 0)}")Ao executar o script, você recebe o link curto hiturl.at/promo-iphone-13 como resposta. O alias é opcional: se você não enviar, a API gera um código aleatório.
Passo 4: Adicionar parâmetros UTM
Você pode adicionar parâmetros UTM diretamente no payload da requisição. Isso permite rastrear a origem do tráfego no Google Analytics sem precisar concatenar strings manualmente.
payload = {
"url": "https://www.lojaexemplo.com.br/produto/camiseta-basica",
"alias": "camiseta-instagram",
"utm_source": "instagram",
"utm_medium": "social",
"utm_campaign": "black-friday-2024"
}Adicionar parâmetros UTM no momento do encurtamento garante que cada link já nasça rastreado, eliminando o risco de URLs sem dados de origem circulando em campanhas ativas.
Passo 5: Disparar retargeting pixels via API
O HitURL permite associar pixels de Facebook, Google, LinkedIn e outras plataformas diretamente ao link curto. Quando alguém clica no link, o pixel dispara antes do redirecionamento.
payload = {
"url": "https://www.lojaexemplo.com.br/landing-page",
"alias": "promo-blackfriday",
"pixel_id": "fb_pixel_123456789",
"pixel_type": "facebook"
}Isso significa que você pode construir listas de retargeting mesmo sem o usuário visitar sua página diretamente. O clique no link curto já conta como evento.
Veja como HitURL tracks every click, fires your pixels, and generates QR codes — free at hiturl.at. Crie sua conta e teste a API hoje mesmo.
Como tratar erros e exceções na API
Toda integração de API precisa de tratamento de erros. Sem isso, um problema de rede ou uma chave inválida derruba seu script inteiro sem mensagem útil.
Aqui está uma versão robusta da função de encurtamento com tratamento completo:
import os
import requests
from requests.exceptions import RequestException
def encurtar_url(url_longa, alias=None, utm=None):
api_key = os.environ.get("HITURL_API_KEY")
if not api_key:
raise ValueError("HITURL_API_KEY nao definida nas variaveis de ambiente")
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
payload = {"url": url_longa}
if alias:
payload["alias"] = alias
if utm:
payload.update(utm)
try:
response = requests.post(
"https://hiturl.at/api/v1/links",
headers=headers,
json=payload,
timeout=10
)
response.raise_for_status()
return response.json()
except requests.HTTPError as e:
print(f"Erro HTTP {response.status_code}: {response.text}")
return None
except RequestException as e:
print(f"Erro de conexao: {e}")
return NoneOs principais códigos de erro que você deve tratar:
- 401 Unauthorized: chave de API inválida ou expirada
- 409 Conflict: alias já existe em outra conta
- 429 Too Many Requests: você excedeu o limite de requisições por minuto
- 500 Internal Server Error: problema no servidor, tente novamente em alguns segundos
Use o parametro timeout em todas as chamadas com requests. Sem timeout, seu script pode travar indefinidamente se o servidor nao responder, comprometendo toda a automacao.
Encurtamento de links em lote com Python
Para quem gerencia catálogos grandes, o encurtamento em lote é onde a API mostra seu valor real. Imagine uma loja na Shopee com 200 produtos. Cada produto precisa de um link curto rastreado para uma campanha de WhatsApp.
Chamamos isso de The Batch Shortening Method: um método estruturado para encurtar múltiplas URLs com tratamento individual de erros e log de resultados.
import csv
import time
import os
import requests
def encurtar_em_lote(arquivo_csv, saida_csv):
api_key = os.environ.get("HITURL_API_KEY")
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
with open(arquivo_csv, "r") as f:
produtos = list(csv.DictReader(f))
resultados = []
for produto in produtos:
payload = {
"url": produto["url"],
"alias": produto.get("alias", ""),
"utm_source": produto.get("utm_source", "whatsapp"),
"utm_medium": produto.get("utm_medium", "broadcast"),
"utm_campaign": produto.get("utm_campaign", "promocao-janeiro")
}
try:
resp = requests.post(
"https://hiturl.at/api/v1/links",
headers=headers,
json=payload,
timeout=10
)
if resp.status_code == 201:
data = resp.json()
produto["short_url"] = data.get("short_url")
produto["status"] = "ok"
else:
produto["short_url"] = ""
produto["status"] = f"erro_{resp.status_code}"
except Exception as e:
produto["short_url"] = ""
produto["status"] = f"excecao: {str(e)}"
resultados.append(produto)
time.sleep(0.5)
with open(saida_csv, "w", newline="") as f:
writer = csv.DictWriter(f, fieldnames=resultados[0].keys())
writer.writeheader()
writer.writerows(resultados)
return resultadosO time.sleep(0.5) entre requisições evita atingir o limite de rate limiting. Para volumes maiores, considere usar urllib.request ou bibliotecas assíncronas como aiohttp para paralelizar as chamadas.
O Batch Shortening Method consiste em três etapas: ler as URLs de uma fonte estruturada (CSV, banco de dados ou planilha), encurtar cada uma com tratamento individual de erros e exportar os resultados com o status de cada operacao. Isso garante que um unico falha nao comprometa o lote inteiro.
Como automatizar o envio de links curtos após o encurtamento?
Depois de gerar os links curtos, o próximo passo costuma ser enviá-los para algum canal: WhatsApp, email, Slack ou um webhook. Você pode fazer isso dentro do mesmo script Python ou usar uma ferramenta de automação.
Se você quer enviar links curtos via webhook imediatamente após a criação, confira nosso tutorial sobre como automatizar o envio de links curtos com webhooks em Python e Node.js. Lá mostramos como configurar webhooks para disparar mensagens no WhatsApp Business assim que o link é gerado.
Outra opção é combinar Python com n8n, uma plataforma de automação visual. Nosso guia sobre integração da API de encurtador com n8n mostra como criar fluxos completos sem código, e o artigo sobre criar automação de links curtos com n8n, webhooks e API detalha como orquestrar tudo em um pipeline visual.
Dicas avançadas: targeting, pixels e QR Codes via API
Targeting geográfico
Com a API do HitURL, você pode criar um único link curto que redireciona para destinos diferentes dependendo do país do usuário. Isso é útil para campanhas que rodam em múltiplos estados do Brasil.
payload = {
"url": "https://www.lojaexemplo.com.br/br",
"alias": "promo-nacional",
"targeting": [
{"country": "BR", "url": "https://www.lojaexemplo.com.br/br"},
{"country": "PT", "url": "https://www.lojaexemplo.com.pt/pt"}
]
}QR Code dinâmico
Um QR Code dinâmico, aquele onde o destino pode ser trocado depois de impresso, é essencial para materiais físicos como flyers e embalagens. Se você imprimir um QR Code estático e a URL mudar, o código para de funcionar. Com QR dinâmico, você atualiza o destino via API sem reimprimir nada.
def gerar_qr_code(link_id):
api_key = os.environ.get("HITURL_API_KEY")
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
response = requests.post(
f"https://hiturl.at/api/v1/qr-codes",
headers=headers,
json={"link_id": link_id, "format": "png", "size": 500}
)
return response.json()QR Codes dinâmicos gerados via API permitem trocar o destino do link apos a impressao do material fisico, eliminando custos de reimpressao e garantindo que campanhas impressas continuem funcionando mesmo apos mudancas de URL.
FAQ: Perguntas frequentes sobre API de encurtador em Python
Preciso pagar para usar a API do HitURL?
Não. O HitURL é gratuito para começar. Você cria links curtos, gera QR Codes e usa a API sem custo inicial. Funcionalidades avançadas como volume elevado de requisições podem exigir um plano pago.
Posso usar urllib em vez de requests?
Sim. A biblioteca urllib vem nativa no Python e funciona para consumir a API. A vantagem do requests é a sintaxe mais limpa e o tratamento automático de JSON, headers e redirecionamentos.
Qual o limite de requisições por minuto na API?
O limite varia conforme o plano. No plano gratuito, você tem um limite generoso para desenvolvimento e testes. Para volumes altos, como encurtamento de catálogos com milhares de URLs, adicione um time.sleep() entre chamadas para evitar erro 429.
Como armazenar a chave de API com segurança?
Use variáveis de ambiente. Nunca coloque a chave diretamente no código. Em produção, use ferramentas como python-dotenv para carregar variáveis de um arquivo .env que não deve ser versionado no Git.
A API funciona com Python 2?
Não. Use Python 3.7 ou superior. A biblioteca requests e o HitURL não oferecem suporte a Python 2, que foi descontinuado em janeiro de 2020.
Conclusão: comece a encurtar links com Python hoje
Você viu como integrar uma API de encurtador de URL em Python com poucas linhas de código. Da primeira requisição ao encurtamento em lote, a combinação de Python com a API do HitURL elimina trabalho manual e dá controle programático sobre seus links.
Os próximos passos dependem do seu caso de uso. Se você gerencia campanhas no WhatsApp e Instagram, comece pelo encurtamento com UTM. Se trabalha com e-commerce na Shopee ou Mercado Livre, implemente o Batch Shortening Method. Se precisa de materiais físicos, explore os QR Codes dinâmicos.
Veja como HitURL tracks every click, fires your pixels, and generates QR codes — free at hiturl.at. Crie sua conta gratuita e comece a integrar a API agora mesmo.
