Ana Kowalska é engenheira de soluções no Elido e já acompanhou uma dúzia de projetos de migração através da transição do Bitly. Na sua opinião, a maior parte da dor é evitável se auditar antes de mover, não depois.
O guia técnico de migração do Bitly cobre o arco estratégico: auditar o que tem, exportar, importar, mudar o DNS. Esse artigo é o ponto de partida certo se ainda não fez uma migração do Bitly.
Este artigo é diferente. Foca-se no que falha - os modos de falha específicos que surgem depois de o plano conceptual estar pronto e estar a executar a migração contra dados de produção. Sete deles aparecem repetidamente, e todos são evitáveis se souber onde procurar.
Resumo#
- Os slugs do Bitly são sensíveis a maiúsculas/minúsculas; muitas plataformas de redirecionamento não são.
bit.ly/AbCdebit.ly/abcdsão links distintos no Bitly e comportar-se-ão de forma diferente se o seu script de migração converter os slugs para minúsculas na importação. - As lacunas de TTL de DNS causam uma interrupção no redirecionamento mesmo depois de o CNAME ser alterado. Reduza o TTL para 60 segundos pelo menos 24 horas antes da transição, não cinco minutos antes.
- Os webhooks que apontam para endpoints de
api-ssl.bitly.comdeixam de disparar no momento em que cancelar ou desativar a conta Bitly. Reconfigure todos os consumidores antes de tocar no estado da conta. - Os deeplinks com segmentos de caminho (
bit.ly/app/account/settings) entram em conflito com quaisquer regras de roteamento do Elido que também correspondam por prefixo de caminho. Audite os slugs de deeplinks separadamente dos slugs de redirecionamento padrão.
As sete coisas que realmente falham#
Antes de qualquer discussão sobre ferramentas, é útil ter a taxonomia de falhas à frente. A maioria das análises pós-migração aponta para uma destas:
1. Sensibilidade a maiúsculas/minúsculas nos slugs. O Bitly preserva as maiúsculas nos slugs - bit.ly/SummerSale e bit.ly/summersale são links distintos. Se o seu script de importação normalizar os slugs para minúsculas (um padrão comum nas bibliotecas de tratamento de URLs), cria silenciosamente o slug errado e a variante com letras maiúsculas devolve erro 404. Isto afeta campanhas de e-mail onde o slug foi incorporado com maiúsculas e minúsculas misturadas.
2. Comportamento da barra final. bit.ly/campaign/ e bit.ly/campaign são tratados como o mesmo link no router do Bitly. Algumas plataformas tratam a variante com barra final como um caminho distinto. Se o seu workspace no Elido for precedido por um proxy reverso com normalização estrita de URL ativa, um pedido com barra final pode resolver de forma diferente do slug canónico.
3. Preservação da query string. Se o URL de destino de um link do Bitly já contiver parâmetros de consulta - https://acme.example/landing?source=bitly - e o clique também transportar parâmetros UTM adicionados no momento da partilha, precisa de verificar que o comportamento de fusão no destino é idêntico no Elido. O comportamento padrão do Bitly para UTMs adicionados é fundi-los na query string existente. Teste isto explicitamente para qualquer link cujo URL de destino já contenha parâmetros.
4. Adição de UTM ao nível da plataforma. O plano enterprise do Bitly suporta adição de UTM ao nível do workspace: cada redirecionamento de saída recebe um UTM adicionado independentemente do que o URL de destino original contém. Se tiver isto ativo no Bitly e não o documentou, pode ter análises que dependem de UTMs que o Elido ainda não está a adicionar. Verifique as definições do seu workspace no Bitly para regras de adição automática antes de exportar. O equivalente no Elido são os modelos UTM ao nível do workspace ou campanha - a página de funcionalidade de domínios personalizados indica onde essa configuração se encontra.
5. Lacuna de TTL de DNS. Esta é a causa mais comum de uma interrupção no redirecionamento na transição. Os resolvedores de DNS guardam em cache o CNAME antigo pelo tempo do TTL atual. Se o seu TTL estiver em 86400 segundos há dois anos, alterá-lo para 300 segundos cinco minutos antes de mudar o registo A significa que a maioria dos resolvedores ainda tem o registo antigo em cache por mais 23 horas e 55 minutos. A transição não é imediata; propaga-se.
6. Reconfiguração de webhooks. Qualquer sistema que consuma eventos de webhook do Bitly - pipelines de análise, tarefas de enriquecimento de CRM, atribuição de pedidos no Shopify - dispara contra o URL do endpoint do Bitly. Esse endpoint fica inativo quando cancela ou faz downgrade da conta Bitly para um plano que não suporta webhooks. A configuração de webhooks do Bitly encontra-se ao nível da conta e não é exportada com os dados dos links. Cada consumidor precisa de ser inventariado e reconfigurado manualmente.
7. Colisões de caminho em deeplinks. Os deeplinks para mobile utilizam frequentemente o caminho do URL curto para codificar o estado de navegação da aplicação - bit.ly/app/profile/edit pode mapear para um destino como yourapp://profile/edit. Quando migra estes slugs para o Elido, o slug app/profile/edit contém barras. O router do Elido pode tratar caminhos com barras de forma diferente do tratamento de slug opaco do Bitly. Verifique que os slugs de deeplinks com segmentos de caminho são criados com a string de slug exata, não reinterpretados como caminhos aninhados.
Auditoria pré-migração: segmentação por nível de risco#
A API do Bitly (acedida em 2026-05-12) expõe contagens de cliques por link via GET /v4/bitlink/{bitlink}/clicks/summary. Antes de exportar e importar qualquer coisa, utilize isto para segmentar o seu inventário.
A segmentação prática:
- Nível não pode falhar (top 1%): links com ≥10× a contagem média de cliques nos últimos 30 dias. Estes estão ativos em e-mails, materiais impressos, páginas de destino de anúncios pagos. Precisam de verificação manual após a transição, não apenas verificações automatizadas.
- Nível de monitorização (próximos 9%): links com volume de cliques acima da média. A verificação automática de 301 é suficiente, mas sinalize qualquer um que resolva de forma inesperada.
- Nível de volume (restantes 90%): slugs de baixo tráfego ou zero tráfego. Verifique programaticamente; aceite uma pequena taxa de erro e corrija mediante relatório.
Exporte um resumo de cliques de 30 dias por link durante a etapa de inventário. Um ciclo de paginação simples contra a referência da API do Bitly (acedida em 2026-05-12) fornece estes dados; o campo link_clicks no endpoint de bitlinks do grupo é o contador vitalício, que é mais grosseiro mas suficiente para triagem:
# Paginar todos os links num grupo Bitly e escrever em JSONL
NEXT_URL="https://api-ssl.bitly.com/v4/groups/${GROUP_GUID}/bitlinks?size=100"
while [ -n "$NEXT_URL" ]; do
RESP=$(curl -s -H "Authorization: Bearer ${BITLY_TOKEN}" "$NEXT_URL")
echo "$RESP" | jq -c '.links[]' >> bitly-links.jsonl
NEXT_URL=$(echo "$RESP" | jq -r '.pagination.next // empty')
done
Ordene o resultado por link_clicks de forma descendente. O top 1% é o seu nível não pode falhar. Exporte os seus slugs para um ficheiro separado antes de executar a importação em massa.
Preservação de slugs: a chamada de importação que importa#
O endpoint de importação em massa do Elido em POST /v1/links/bulk aceita um campo slug por link. Se não o definir explicitamente, o Elido gera um novo slug aleatório - o que é o comportamento errado para uma migração. Passe sempre o slug de origem.
# Importação em massa com preservação de slugs - 100 links por chamada
curl -s -X POST "https://api.elido.app/v1/links/bulk" \
-H "Authorization: Bearer ${ELIDO_API_KEY}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: mig-batch-$(date +%s)" \
-d '{
"workspace_id": "'"${WORKSPACE_ID}"'",
"domain_id": "'"${DOMAIN_ID}"'",
"links": [
{
"slug": "SummerSale",
"destination_url": "https://acme.example/summer",
"tags": ["bitly-migrated", "campaign-summer"]
},
{
"slug": "AbCd",
"destination_url": "https://acme.example/landing",
"tags": ["bitly-migrated"]
}
]
}'
Dois aspetos a notar nesta chamada. Primeiro, os valores de slug são "SummerSale" e "AbCd" - maiúsculas e minúsculas preservadas exatamente como apareciam no Bitly. Não as converta para minúsculas. Segundo, o cabeçalho Idempotency-Key significa que pode re-executar um lote parcial em segurança; o Elido devolve o link existente em vez de criar um duplicado. Este é o padrão correto para uma migração que pode precisar de retomar.
Para o nível não pode falhar, execute a importação de forma interativa por link em vez de em lote, e verifique cada um antes de avançar. Para o nível de volume, processe em lotes de 100 por chamada e analise o array de erros na resposta para detetar slugs que tenham entrado em conflito ou falhado.
Transição de DNS sem interrupção#
A transição de DNS é o momento em que o tráfego ao vivo muda. Feita corretamente, os utilizadores não sentem qualquer interrupção. Feita com um TTL antigo, há uma lacuna que se mede em horas, não em minutos.
A sequência importa. Veja o diagrama de linha temporal abaixo.
A linha temporal em detalhe:
T−7 dias: Reduza o TTL no CNAME ou registo A para 60 segundos. Este é o passo crítico que a maioria das equipas falha. O RFC 1034 §3.6 (IETF datatracker, secção sobre caching de registos de recursos) define o TTL como a duração máxima de cache que um resolvedor pode manter o registo. Se o seu TTL atual for 86400 (um dia), alterá-lo só tem efeito após a versão em cache atual expirar. Precisa de reduzir o TTL pelo menos um período completo do TTL atual antes da transição. Uma semana é seguro; 24 horas é o mínimo.
T−1 hora: Verifique que o TTL baixo se propagou. Use uma ferramenta como dig @8.8.8.8 links.suamarca.com +ttl a partir de pelo menos três endpoints de resolvedores diferentes. O TTL reportado deve estar próximo de 60 segundos.
T−0: Troque o destino do CNAME do edge do Bitly para o edge do Elido. Do lado do Elido, o domínio já deve estar registado e verificado no seu workspace - não mude o DNS antes de o edge do Elido estar pronto para aceitar o tráfego. O primeiro pedido após a propagação desencadeia a emissão do certificado TLS automático sob demanda, que fica concluída em aproximadamente 2-3 segundos nesse único pedido. Os pedidos seguintes atingem a cache e resolvem em milissegundos de um único dígito na região da UE.
T+5 minutos: Execute uma verificação pontual a partir de uma segunda rede (use um hotspot móvel para ignorar a cache do resolvedor do seu escritório). curl -sI https://links.suamarca.com/qualquer-slug-conhecido deve devolver um 301 Moved Permanently apontando para o destino esperado, com cabeçalhos originados no edge do Elido.
T+1 hora: Restaure o TTL para o seu valor operacional normal (300 ou 3600 segundos). Manter o TTL em 60 segundos indefinidamente adiciona carga ao seu provedor de DNS e à infraestrutura de resolvedores.
T+24 horas: Execute a auditoria completa de slugs (veja a próxima secção).
De acordo com o RFC 7231 §6.4.2, uma resposta 301 Moved Permanently pode ser guardada em cache por intermediários indefinidamente, a menos que um cabeçalho de cache-control explícito a substitua. Isto significa que qualquer cliente que tenha atingido o destino antigo do Bitly durante a lacuna de TTL pode ter guardado em cache um 301 apontando para a infraestrutura do Bitly. Esses redirecionamentos em cache resolvem corretamente enquanto a infraestrutura do Bitly estiver ativa, razão pela qual a janela de sobreposição de 30 dias com a conta Bitly é importante.
A auditoria da cadeia 301: verificação automatizada noturna#
Após a transição, execute um ciclo de verificação noturno sobre o seu nível não pode falhar. O objetivo é detetar qualquer slug cujo comportamento mudou - quer devolvendo um destino inesperado, quer devolvendo um 404, quer criando uma cadeia de redirecionamentos com mais de dois saltos.
# Verificar que os slugs principais resolvem corretamente via Elido
# top-slugs.txt: um slug por linha, sem prefixo de protocolo
DOMAIN="links.suamarca.com"
FAIL=0
while IFS= read -r slug; do
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
--max-redirs 0 \
"https://${DOMAIN}/${slug}")
LOCATION=$(curl -s -I --max-redirs 0 \
"https://${DOMAIN}/${slug}" \
| grep -i '^location:' | tr -d '\r' | cut -d' ' -f2)
if [ "$STATUS" != "301" ]; then
echo "FAIL [$STATUS] $slug → esperado 301"
FAIL=$((FAIL + 1))
else
echo "OK [301] $slug → $LOCATION"
fi
done < top-slugs.txt
echo "---"
echo "Falhas: $FAIL"
exit $FAIL
Execute isto contra o nível não pode falhar (tipicamente 50–200 slugs para a maioria das equipas) todas as noites durante as primeiras duas semanas após a transição. Encaminhe o resultado para o seu canal de alertas. Se FAIL for diferente de zero, quer que um humano o analise antes do pico de tráfego matinal.
O sinalizador --max-redirs 0 é intencional: quer o redirecionamento do Elido, não o destino final. Se o Status for 200 em vez de 301, algo do lado do Elido está a servir o destino diretamente em vez de redirecionar, o que significa que o slug resolveu para um link configurado como passagem direta. Vale a pena investigar.
Para o nível de monitorização, execute uma análise semanal mais ligeira. Para o nível de volume, recorra a relatórios de erro de sistemas a jusante - links quebrados em e-mails geram alterações na taxa de rejeição que a sua plataforma de e-mail irá evidenciar.
Reconfiguração de webhooks#
Os webhooks do Bitly estão documentados na referência da API do Bitly (acedida em 2026-05-12) na secção Webhooks. Cada webhook dispara em eventos de clique e inclui o bitlink, o referrer e os campos de user-agent. Consumidores comuns:
- Shopify: aplicações de atribuição que rastreiam qual link curto gerou uma conversão. Configurado no painel de administração da aplicação Shopify, apontando para um endpoint de terceiros que chama a verificação de webhook do Bitly.
- Stripe: alguns pipelines de atribuição de faturação marcam os novos registos de trial de entrada com os dados UTM do link curto de origem, obtidos via webhook do Bitly.
- Slack: bots de desempenho de links que publicam resumos de cliques num canal
#marketing. - Pipelines ETL personalizados: qualquer pipeline de data warehouse que ingere eventos de clique do Bitly para enriquecimento ou joins de atribuição.
A lista de verificação de migração para webhooks:
- Exporte a configuração de webhook do Bitly antes de qualquer alteração na conta. A API do Bitly
GET /v4/workspaces/{workspace_guid}/webhooksdevolve a lista. Guarde-a num ficheiro. - Para cada consumidor, identifique o URL do endpoint a receber eventos do Bitly e o segredo utilizado para verificação HMAC.
- Configure o endpoint de webhook equivalente no Elido. Os payloads de webhook do Elido têm um esquema diferente do do Bitly - os campos são semelhantes mas não idênticos. Ajuste o handler do consumidor para aceitar o novo esquema.
- Execute ambos os webhooks em paralelo durante a janela de sobreposição. Configure o Elido para disparar webhooks a partir do dia da transição, mantendo o webhook do Bitly ativo. O seu consumidor recebe dois eventos por clique durante a sobreposição - faça deduplicação com base no URL curto + timestamp, ou aceite a dupla contagem durante a janela de sobreposição como um artefacto conhecido.
- Após 72 horas de entrega confirmada de webhooks do Elido, remova a configuração de webhook do Bitly de cada consumidor.
A janela de carência de rotação de segredos é o período de sobreposição. Não rotacione o segredo de webhook do Elido até que todos os consumidores tenham sido verificados. Rodar o segredo antes de um consumidor ser atualizado significa que esse consumidor descarta silenciosamente eventos sem erro - a verificação HMAC falha e a maioria dos handlers de webhook descarta payloads com assinatura inválida sem alertar.
Plano de rollback: manter o Bitly ativo durante 30 dias#
O procedimento de rollback é simples: reverter o CNAME de DNS para o destino do Bitly. Como pré-preparou a redução de TTL e o registo DNS ainda está a 60 segundos (até restaurá-lo), uma reversão de DNS propaga-se em menos de dois minutos.
Prepare o comando de rollback antes de começar:
# Script de rollback - execute isto para reverter o DNS para o Bitly (adapte para o seu provedor de DNS)
# Exemplo com Route 53 usando AWS CLI
aws route53 change-resource-record-sets \
--hosted-zone-id "${HOSTED_ZONE_ID}" \
--change-batch '{
"Changes": [{
"Action": "UPSERT",
"ResourceRecordSet": {
"Name": "links.suamarca.com",
"Type": "CNAME",
"TTL": 60,
"ResourceRecords": [{"Value": "cname.bitly.com"}]
}
}]
}'
Guarde isto num ficheiro no seu portátil e num local de runbook partilhado antes da transição. O pior momento para escrever comandos de infraestrutura é durante um incidente ativo.
Mantenha a conta Bitly ativa num plano pago que garanta a resolução de links durante 30 dias após a transição. O guia técnico de migração do Bitly recomenda 90 dias; 30 é o mínimo prático para equipas que precisam de controlar custos. Durante a janela de 30 dias, qualquer tráfego que ainda resolva via Bitly (redirecionamentos em cache, links antigos bit.ly em materiais impressos) continua a funcionar. Após 30 dias, avalie o tráfego residual do Bitly nas suas análises e decida se quer prolongar.
O que monitorizar durante a janela de 30 dias:
- Taxa de erros do Elido no seu domínio personalizado (fique atento a 404s inesperados no registo de acesso).
- Quaisquer picos de tráfego para o Bitly (o dashboard do Bitly mostra o tráfego; um pico pode significar que um redirecionamento em cache ainda está a resolver através do Bitly para um slug de alto volume).
- Taxas de erro dos consumidores de webhook para quaisquer consumidores que reconfigurou.
Auditoria pós-migração: o que registar#
Após a janela de 30 dias, execute uma passagem de auditoria final. O que deve constar no registo de auditoria:
| Verificação | Método | Critério de passagem |
|---|---|---|
| Contagem de slugs corresponde | wc -l bitly-export.jsonl vs contagem da API do Elido | Dentro de 1% (tendo em conta links arquivados intencionalmente eliminados) |
| Verificação 301 do nível não pode falhar | Script de auditoria noturno | Zero falhas durante 7 dias consecutivos |
| Reconciliação do volume de cliques | Comparar total de cliques de 30 dias do Elido vs total de 30 dias do Bitly do mesmo período no ano anterior | Dentro da variação sazonal esperada |
| Confirmação do consumidor de webhook | Verificar que cada consumidor está a receber e processar corretamente eventos do Elido | Sem descartes silenciosos durante 7 dias |
| TTL de DNS restaurado | dig +ttl links.suamarca.com | TTL no valor operacional (300+ segundos) |
Registe isto na tabela de auditoria da sua equipa. Se o seu workspace estiver num plano Business ou Enterprise, o registo de auditoria do Elido captura todas as operações da API durante a importação e pode ser consultado via API. Extraia os registos do lote de importação e guarde um snapshot ao lado desta tabela.
Erros comuns: três padrões do campo#
A marca de ecommerce DACH que perdeu uma semana de atribuição de e-mail. Um retalhista alemão executou uma campanha de newsletter usando slugs do Bitly com UTMs por subscritor adicionados no momento do envio. O script de migração normalizou todos os slugs para minúsculas antes de os importar para o Elido. Após a transição, a plataforma de e-mail estava a gerar links com os slugs originais com maiúsculas e minúsculas misturadas. Esses links devolviam 404 no Elido porque as maiúsculas/minúsculas do slug não correspondiam. A correção foi re-executar a importação com slugs com capitalização preservada, mas nessa altura sete dias de tráfego de e-mail tinham chegado a páginas 404. A atribuição ficou irrecuperável para essa coorte. A lição: teste um link ao vivo de cada canal ativo antes de declarar a migração concluída.
A startup SaaS que triplicou os redirecionamentos para utilizadores móveis. Uma equipa de crescimento tinha um domínio personalizado Bitly precedido pelo Cloudflare em modo proxy (nuvem laranja). Após a transição, os utilizadores móveis estavam a obter três redirecionamentos: Cloudflare → edge do Elido → destino. O salto extra veio de uma Regra de Página do Cloudflare que reescrevia HTTP para HTTPS antes de passar para o Elido, e depois o Elido emitia o seu próprio 301. O Safari para iOS guardou em cache o redirecionamento intermédio do Cloudflare como redirecionamento permanente durante 30 dias. A correção foi definir o registo do Cloudflare para nuvem cinzenta (DNS-only) e remover a Regra de Página conflituante. Os redirecionamentos em cache no Safari demoraram 30 dias a expirar naturalmente. Verifique o modo de proxy da sua CDN antes da transição, não depois.
A agência que falhou um grupo do Bitly. Uma agência geria três marcas de clientes numa única conta Bitly, cada uma sob um grupo Bitly diferente com o seu próprio domínio personalizado. O script de migração consultou apenas o grupo predefinido - aquele sob o qual o token do utilizador da API foi criado. Dois domínios de clientes migraram sem problemas. O terceiro, sob um grupo secundário, nunca foi exportado. Após a transição, uma campanha de e-mail de lançamento de produto foi enviada apontando para o domínio não migrado. O domínio ainda tinha o CNAME do Bitly com TTL completo, e o Bitly estava a servir os links corretamente - mas a janela de transição para esse domínio tinha sido declarada concluída. A correria foi uma re-migração completa sob prazo. A lição: enumere todos os grupos via GET /v4/user/groups antes de iniciar qualquer passo de exportação. Verifique que o token tem acesso a todos os grupos.
Para onde ir a seguir#
O guia técnico de migração do Bitly cobre a sequência estratégica completa para equipas que começam do zero no planeamento da migração. Este artigo é o complemento de modos de falha - use-os em conjunto.
Para o lado do produto para o qual está a migrar, a página solutions/marketers cobre as funcionalidades de atribuição e rastreamento de campanhas a que a maioria dos projetos de migração procura aceder. A página /compare/vs-bitly é a referência de paridade de funcionalidades se ainda estiver a confirmar que a mudança vale a pena.
Se estiver a avaliar o Elido ao lado do Rebrandly ou do Short.io, a comparação elido-vs-bitly cobre as contrapartidas de preço e funcionalidades em quatro volumes de tráfego. A página de funcionalidade de domínios personalizados documenta em detalhe a verificação DNS e a mecânica de provisionamento TLS - vale a pena ler antes da sua janela de transição DNS.
As falhas de migração são quase sempre evitáveis. O script de auditoria, a disciplina de TTL e o inventário de webhooks levam duas horas de trabalho antes da transição. Poupam dias de resposta a incidentes depois.
Citações e fontes
- Referência da API do Bitly - dev.bitly.com/api-reference, acedida em 2026-05-12
- RFC 1034 - Nomes de Domínio: Conceitos e Instalações, §3.6 (caching de registos de recursos) - datatracker.ietf.org/doc/html/rfc1034
- RFC 7231 §6.4.2 - Semântica e Conteúdo HTTP/1.1: 301 Moved Permanently - datatracker.ietf.org/doc/html/rfc7231#section-6.4.2
- API do Bitly - endpoints de Grupos e Bitlinks - dev.bitly.com/api-reference, acedida em 2026-05-12
Experimente Elido
Cole uma URL, obtenha um link curto
Sem cadastro. O link vive 30 dias. Cadastre-se para mantê-lo para sempre.
Grátis, sem necessidade de registo · 2 por dia