Migrar do Bitly para o Elido: um guia técnico

Migrar uma infraestrutura de links é uma operação de alto risco. Cada link curto que já imprimiu, incorporou no rodapé de um e-mail ou estampou num código QR é agora uma dependência. Uma migração descuidada pode gerar erros 404 para uma fatia significativa do tráfego de entrada durante semanas antes que alguém note.

Este guia abrange a migração do Bitly para o Elido. Parte do princípio de que já tomou a decisão de mudar - geralmente por residência de dados na UE, uma experiência de plano gratuito mais limpa, revenda com marca branca ou acesso à API que não exige o plano Premium ($199/mês anual ou $300/mês mensal, a partir de maio de 2026). Se ainda estiver a avaliar, a página de comparação em /compare/vs-bitly é o melhor ponto de partida.

O que é realmente necessário migrar#

Três coisas migram; mais nada importa ao nível da rede.

1. Links curtos ativos. O slug, o destino, etiquetas e pastas opcionais e o domínio personalizado (se existir).
2. DNS do domínio personalizado. O registo CNAME que aponta para o edge do Bitly precisa de passar a apontar para o edge do Elido.
3. Histórico de cliques. Os contadores agregados do Bitly - não os eventos brutos (esses não são exportáveis).

Todo o resto - dashboards do Bitly Sights, códigos QR com marca, configurações de deep links - é uma configuração de raiz no Elido, não uma migração. Não tente portá-los; reconstrua de uma vez na nova plataforma.

Passo 1: Inventário#

O Bitly limita a exportação de dados históricos por plano. A exportação CSV pelo dashboard funciona até cerca de 10 mil links; para além disso, o processo expira ou a paginação funciona mal. Para inventários maiores, percorra a API diretamente:

curl -H "Authorization: Bearer $BITLY_TOKEN" \
  "https://api-ssl.bitly.com/v4/groups/$GROUP_GUID/bitlinks?size=100"

Pagine através do URL pagination.next em cada resposta. O tamanho máximo de página é 100. Guarde os resultados como JSONL - um link por linha - para poder retomar caso a exportação fique suspensa.

O que precisa de cada linha:

• link - o URL curto completo (https://bit.ly/abc ou https://seudomain.com/abc)
• long_url - o destino
• tags, archived, created_at
• link_clicks (total vitalício) - o único histórico de cliques que consegue obter do Bitly

Filtre os links arquivados, a menos que tenha razão para os manter. A maioria das equipas descobre que 30–50% do seu inventário está inativo - campanhas antigas, partilhas pontuais - e a migração é o momento certo para eliminar esse lixo.

Passo 2: Pré-provisionar no Elido#

Antes de tocar no DNS, reserve todos os links no Elido sob o mesmo domínio personalizado e slug.

Para inventários grandes, utilize links.bulkCreate em vez de criações individuais. Vai precisar do ID do seu workspace no Elido e do ID numérico do domínio (consulte primeiro o domínio com workspaceDomains.list(workspaceId)):

import { ElidoApi } from "@elido/sdk";

const api = new ElidoApi({ apiKey: process.env.ELIDO_API_KEY! });

// Resolva o ID numérico do seu domínio personalizado uma vez, antes do ciclo de importação
const { items: domains } = await api.workspaceDomains.list(WORKSPACE_ID);
const domain = domains.find((d) => d.hostname === "links.suamarca.com");
if (!domain) throw new Error("Domain not registered in workspace");

// Divida o JSONL em blocos de 100 (o máximo do endpoint bulk)
async function migrateChunk(rows: BitlyRow[]) {
  return api.links.bulkCreate(
    WORKSPACE_ID,
    {
      domain_id: domain.id,
      links: rows.map((row) => ({
        slug: row.slug,
        destination_url: row.long_url,
        tags: [
          ...row.tags,
          `bitly-migrated`, // etiqueta para filtrar nas análises
        ],
        title: row.title ?? undefined,
      })),
    },
    { idempotencyKey: `mig-batch-${rows[0].slug}` },
  );
}

O endpoint links.bulkCreate (POST /v1/workspaces/{workspace_id}/links/bulk) aceita até 100 links por chamada e devolve o estado de sucesso/falha por item, pelo que uma falha parcial não aborta o lote. Para importações de link único, links.create(workspaceId, input, { idempotencyKey }) aceita os mesmos campos domain_id / slug / destination_url / tags e uma chave de idempotência opcional para que um script parcialmente executado possa retomar com segurança.

Alguns aspetos a ter em conta antes de executar o script:

• Registo do domínio primeiro. O domain_id no corpo do pedido deve referir-se a um domínio já registado no seu workspace. Registe e verifique o domínio através do fluxo de domínios personalizados antes de iniciar a importação. O domínio não precisa de estar ativo ainda - pode registá-lo no Elido antes de fazer a transição do DNS.
• Limites de plano. O Elido impõe limites de links ao nível do workspace por plano. O pré-provisionamento de um inventário de 100 mil links requer um plano Business.
• Limites de taxa. A criação em massa está sujeita aos mesmos limites de taxa ao nível do workspace que as criações individuais. Uma migração de 50 mil links demora cerca de 10 minutos com lotes de 100 links por chamada e paralelismo moderado. Mantenha a execução em série ou com pouca concorrência a partir de um único servidor para que o registo de auditoria mostre um bloco de importação limpo.

Passo 3: Redirecionar o domínio personalizado#

Esta é a transição. Tudo antes deste passo é reversível; tudo depois está em produção.

Reduza o TTL no CNAME existente do Bitly pelo menos 24 horas antes da janela de transição:

links.suamarca.com.  300  IN  CNAME  cname.bitly.com.

Se o seu TTL tiver sido 86400 durante anos, "reduzir o TTL" implica uma espera de 24 horas, não uma tarefa de cinco minutos. Planeie em conformidade.

Quando a janela de mudança abrir, troque o destino:

links.suamarca.com.  300  IN  CNAME  edge.elido.me.

O edge do Elido usa TLS automático sob demanda. O primeiro pedido após a propagação do DNS desencadeia uma emissão de certificado pelo Let's Encrypt - tipicamente 1–3 segundos de latência nesse único pedido; depois, o certificado fica em cache e os pedidos seguintes são servidos a partir do edge na região da UE em milissegundos de um único dígito. O certificado é provisionado automaticamente; não há nenhum passo manual de pedido de certificado.

Verifique com dig a partir de várias redes antes de declarar a transição concluída. A propagação DNS é desigual; verificar apenas a partir do seu portátil significa que verificou apenas um resolvedor.

Passo 4: Reconciliar o histórico de cliques#

O Bitly não exporta eventos de clique brutos. Não orce tempo para "importar o seu histórico" - não é possível, e qualquer ferramenta que o prometa está a ler agregados e a chamá-los de eventos.

O que obtém é o contador link_clicks por link da exportação da API do Bitly. Guarde-o algures onde possa fazer join com o seu inventário de links no Elido - uma coluna separada num conjunto de dados do Metabase, ou uma etiqueta se quiser tê-lo inline. O Elido começa a contar a partir de zero na transição.

Para a camada de relatórios, a fórmula é: total_clicks = elido_clicks + bitly_lifetime_clicks. A API de análises expõe os dados de cliques do Elido em /v1/analytics/workspaces/{workspace_id}/timeseries; uma consulta de 20 linhas no Metabase ou no Hex une os dois números se tiver guardado a linha de base do Bitly.

Se precisar de análises históricas granulares - distribuição geográfica por mês, tendências de referência - elas não voltarão. Reconstrua as questões no registo de eventos brutos do Elido daqui para a frente; a migração é o corte definitivo.

Cinco armadilhas que aparecem na segunda semana#

1. Links bit.ly codificados de forma rígida em recursos estáticos. PDFs, material impresso, snippets incorporados em e-mails de boas-vindas. Estes apontam para o domínio do Bitly, não para o seu domínio personalizado. Continuam a funcionar enquanto mantiver a conta Bitly; quebram no momento em que a cancelar. Pode manter uma conta gratuita do Bitly ativa como cemitério de apenas redirecionamentos, ou aceitar a perda e não cancelar durante pelo menos um ano.

2. Duplo redirecionamento via CDN. Se utilizar o Cloudflare em modo proxy (nuvem laranja), o handshake SSL para o Elido pode entrar em conflito com o Universal SSL do Cloudflare. Defina o SSL do Cloudflare para "Full (Strict)" e remova quaisquer Regras de Página que referenciem o antigo destino do Bitly. Ou desative temporariamente o proxy no registo durante a janela de transição.

3. Truncagem de UTM na exportação. O Bitly mostra por vezes um URL de destino encurtado no dashboard, mas guarda o URL canónico completo. A exportação CSV normalmente tem o URL completo; a vista do dashboard pode não ter. Se fizer scraping do dashboard em vez de chamar a API, perderá os UTMs. Use sempre a API.

4. Limites de taxa da API do Bitly no lado da leitura. A API do Bitly é bastante restritiva nos throttles de GET /bitlinks para contas de alto volume. Ler 1 milhão de links de forma sequencial pode demorar dias. Pagine em paralelo (4–8 paginadores concorrentes) mas fique atento aos erros 429; recue quando ocorrerem.

5. Escopo ao nível da conta vs. ao nível do grupo no Bitly. Os grupos do Bitly não são workspaces. Uma única conta Bitly pode ter vários grupos, cada um com a sua própria configuração de domínio personalizado. Se a sua equipa adicionou domínios em grupos diferentes ao longo dos anos, a exportação precisa de enumerar todos os grupos, não apenas o predefinido. Se falhar um grupo, esse domínio não migra.

Conformidade: a razão real pela qual a maioria das equipas muda#

A migração é geralmente motivada por conformidade, não por funcionalidades. O padrão típico:

• O DPO sinaliza o Bitly como sub-processador com sede nos EUA; a dependência do Data Privacy Framework recebe objeções numa auditoria.
• O departamento de compras pede a lista de sub-processadores; a do Bitly inclui mais de 20 fornecedores.
• Um BAA no plano Premium ($300/mês faturado mensalmente, ou $199/mês com compromisso anual, a partir de maio de 2026 - verifique o preço atual) torna-se um requisito para clientes da área da saúde, e a mudança de plano é o gatilho.

O Elido é alojado na UE por padrão - os eventos de clique passam pela região da UE, com Leste dos EUA e Ásia-Pacífico disponíveis como regiões opt-in para Business+. A lista de sub-processadores tem cinco fornecedores, publicada em /legal/subprocessors. A ISO 27001 está atual; o SOC 2 Tipo II está em auditoria. O BAA está disponível no Business+. O Schrems II não é uma preocupação na configuração predefinida porque os dados não saem do EEE, a menos que um workspace fixe explicitamente uma região fora da UE.

Se a conformidade for o motor, o plano de migração deve incluir um diagrama de fluxo de dados lado a lado: onde viviam os eventos de clique antes, onde vivem agora. Esse diagrama é o que o seu auditor quer na próxima avaliação.

Self-hosting como alternativa#

Para equipas cujo perfil de segurança exclui qualquer serviço SaaS de encurtamento de links - serviços financeiros, governo, saúde - o Elido fornece um Helm chart com licença Apache 2.0. Os mesmos binários que correm na nossa região da UE, implementados na sua VPC, com KMS próprio para encriptação, sem sub-processadores de terceiros. A migração é idêntica, exceto no passo 3 (DNS), onde aponta para o seu ingress no cluster em vez de edge.elido.me.

O guia de self-hosting cobre a instalação do Helm, o bootstrapping de segredos e a configuração da camada de autenticação; reserve meio dia para uma implementação nova num cluster k8s existente.

Fluxo de trabalho para programadores após a migração#

Uma vez no Elido, a API é a superfície principal para qualquer equipa que crie mais do que alguns links por semana. A especificação OpenAPI 3.1 está em /help; o pacote @elido/sdk cobre a API em TypeScript, e um SDK Go está disponível em packages/sdk-go.

Para fluxos de trabalho orientados por agentes, o servidor MCP open-source liga o Elido ao Claude, ao Cursor ou a qualquer cliente compatível com MCP:

{
  "mcpServers": {
    "elido": {
      "command": "npx",
      "args": ["-y", "@elido/mcp-server"],
      "env": { "ELIDO_API_KEY": "elido_pk_..." }
    }
  }
}

Apenas leitura por padrão - os agentes podem consultar análises e pesquisar links sem escrever. A concessão de permissão de escrita é uma definição deliberada por workspace.

Lista de verificação final antes da transição#

• O token da API do Bitly tem acesso a todos os grupos, não apenas ao predefinido
• Inventário exportado como JSONL, links arquivados filtrados, contagem verificada contra o dashboard do Bitly
• Todos os slugs pré-provisionados no Elido sob o domínio personalizado correto; o script devolveu 100% de sucesso numa execução de teste
• Domínio personalizado registado e verificado no workspace do Elido antes de tocar no DNS
• TTL do DNS no CNAME existente do Bitly reduzido para 300s, pelo menos 24 horas antes da transição
• Modo proxy do Cloudflare e configuração SSL verificados como compatíveis com o edge do Elido
• Contagens de cliques vitalícias do Bitly capturadas na hora da transição e guardadas para relatórios
• Pelo menos um link de teste impresso e digitalizado para confirmar o funcionamento end-to-end
• Conta Bitly programada para permanecer ativa durante 90 dias após a transição como seguro para links bit.ly codificados de forma rígida

Feita corretamente, a mudança é invisível para o utilizador final. Feita incorretamente, passa duas semanas a responder a tickets de "porque é que o bit.ly não funciona?" de alguém que não percebe que não é culpa dele.

O trabalho técnico é simples. A disciplina está no planeamento.

Relacionados no blogue#

• Migrar do Bitly sem quebrar links: um guia de modos de falha
• Migrar do Rebrandly: transferência de domínio com marca sem perder slugs
• Residência de dados na UE para ferramentas de marketing: o que o seu DPO realmente pergunta
• Configurar links curtos com marca: escolha um domínio, em produção numa tarde