Integração do encurtador de URL com Notion: OAuth + sincronização de banco de dados em duas vias

A integração do encurtador de URL com o Notion passou de Beta para Ao vivo em 4 de junho de 2026 para a conexão em si: um clique OAuth, nenhum segredo colado manualmente. A sincronização de banco de dados construída em cima dela está planejada e ainda não disponível. Quando for lançada, o Elido vai ler as URLs em qualquer banco de dados que você escolher, criar links curtos com marca própria no seu domínio, escrevê-los de volta na tabela, e observar edições de destino, com o mapa de campos configurável por banco de dados.

Este artigo cobre a etapa de conexão OAuth, que está ao vivo, e depois a estrutura planejada de seis colunas e o fluxo de edição em duas vias com resolução de conflitos. Se você leu o passo a passo anterior de links curtos no Notion, este é o mergulho mais profundo.

OAuth em um clique: o que realmente acontece quando você aperta Conectar

Os fluxos antigos de colagem de token pediam para você gerar um token de integração interna do Notion, colá-lo, e depois compartilhar cada banco de dados com a integração manualmente. Isso acabou. O novo fluxo tem três cliques: Conectar no Elido, escolher workspace + bancos de dados na tela de consentimento do Notion, pronto. A dança OAuth segue o padrão descrito na documentação de autenticação da API do Notion. O Notion não aceita PKCE, então a troca é um fluxo simples de código de autorização protegido por um parâmetro state.

O Notion não tem seleção por escopo individual no momento da autorização; as capacidades são definidas do lado do Elido na integração, e você escolhe quais páginas e bancos de dados ela pode ver. As capacidades são propositalmente estreitas:

• read_content - ler as propriedades Destination, Tags e Title nos bancos de dados que você escolheu.
• insert_content - criar novas linhas quando você pede ao Elido para gerar um link a partir de uma fonte externa (um Zap, um webhook, um CSV).
• update_content - escrever de volta as propriedades Short URL, Clicks, QR e Last Synced.

O Elido nunca pede leitura de todo o workspace nem páginas que você não marcou. O Notion também aplica isso do lado do servidor: uma consulta contra um banco de dados fora da concessão retorna 403. A referência da API do Notion para operações de banco de dados cobre os verbos que a integração usa.

Quando você completa o consentimento, seu navegador acessa api.elido.app/v1/oauth/notion/callback com o código de autorização. O api-core troca o código por um access token, criptografa o token (conforme ADR-0036), e o armazena em external_oauth_connections. O token em texto puro nunca toca disco nem logs. Uma linha também cai no log de auditoria para que um administrador possa ver quem conectou qual workspace do Notion, e quando.

O botão de conexão fica na aba Integrações por workspace, igual a qualquer outro fornecedor no catálogo de integrações. A página de integração do Notion tem uma captura de tela da tela de consentimento. As permissões podem ser revogadas no painel Settings, Connections do Notion; Desconectar no Elido marca a conexão como revogada do lado do Elido.

Dois modos: anexar ou criar

No modo anexar, você aponta o Elido para um banco de dados existente com uma propriedade de URL. O Elido adiciona as colunas que precisa (e só essas), sem renomear nada. No modo criar, o Elido provisiona um banco de dados novo, "Elido Links", dentro da página que você escolher. A maioria das equipes escolhe anexar porque a tabela de campanha delas já existe com trimestres de histórico. De qualquer forma, o esquema abaixo é idêntico.

Mapeamento de campos: as seis colunas e por que elas são assim

Tudo daqui até o passo a passo de configuração descreve a sincronização planejada, não o que está disponível hoje. Hoje a conexão permite que o Elido liste seus bancos de dados compartilhados e crie linhas neles pelo cliente da API.

Aqui está o layout de colunas que a integração usa. Os nomes são padrões, você pode renomeá-los por banco de dados em Settings, Notion, Field map.

Coluna	Tipo no Notion	Direção	Notas
Short URL	URL	Elido escreve	Somente leitura do lado do usuário; editá-la não faz nada.
Destination	URL	Notion escreve	O alvo para o qual o link curto aponta. Editável.
Tags	Multi-select	Duas vias	As tags são mescladas por união de conjuntos em caso de conflito.
Clicks	Number	Elido escreve	Consultado a cada 5 minutos. Somente leitura.
QR	Files	Elido escreve	Um PNG de 1024px do QR code para a URL curta.
Last Synced	Date	Elido escreve	Timestamp UTC do toque de sincronização mais recente.

Algumas escolhas que vale destacar.

Clicks é intencionalmente não ao vivo. O Notion não tem um mecanismo de streaming, e martelar o endpoint deles a cada clique consumiria o limite de taxa. Cinco minutos combina com a atualidade que a maioria das equipes de operações precisa. Para tempo real, um evento de webhook por clique está no roadmap; até ser lançado, extraia os cliques da API de analytics. O Notion é a visão de campanha; o feed de analytics é o hidrante.

QR é uma propriedade Files, não uma URL. O Notion não renderiza URLs de imagem externas em tabelas, mas renderiza arquivos anexados como miniaturas. O Elido envia o PNG na primeira sincronização e reenvia apenas se a URL curta mudar. Veja a página do recurso de QR codes e o guia de QR GS1.

Tags é de duas vias com união de conjuntos. A única coluna onde os dois lados escrevem. Marque uma linha com "launch-2026" no Notion, o Elido tem "winter-promo" vindo de um Zap, na próxima sincronização as duas tags existem nos dois lados. Remoções se propagam. O log de auditoria registra cada mudança.

Para parâmetros de UTM, o guia de templates de UTM anexa um template a uma pasta para que todo link herde o utm_source certo. A coluna Destination permanece limpa, e o Elido acrescenta parâmetros no momento da resolução do clique via regras de smart link.

O fluxo de edição em duas vias: quem vence quando Notion e Elido discordam

Esta é a parte que mais importa para as equipes, porque ferramentas de sincronização têm um histórico de sobrescritas silenciosas. Aqui está o contrato.

O worker planejado dentro do api-core faz polling em cada banco de dados conectado a cada cinco minutos por mudanças desde a última marca d'água de last_edited_time. Em uma mudança de propriedade, ele carrega o mapa de campos e decide a titularidade. As regras são fixas:

• Notion é dono de: Destination, Tags (lado de escrita), Title.
• Elido é dono de: Short URL, Clicks, QR, Last Synced.
• Compartilhado: Tags (lado de leitura, os dois lados veem o conjunto mesclado).

Se um campo de propriedade do Notion mudou no Notion, o Elido atualiza o estado interno e emite um evento integration.notion.sync. Se um campo de propriedade do Elido mudou (um tique na contagem de clique), o Elido escreve de volta na próxima sincronização.

O caso interessante é uma colisão. Suponha que você mude Destination no Notion às 14h02min10s e um Zap escreva um novo Destination no Elido às 14h02min30s, dentro da mesma janela de cinco minutos. O Notion é dono de Destination, então o Notion vence. O Elido descarta a escrita do Zap, posta um comentário na linha ("Conflito em Destination às 14h02min30s, mantido o valor do Notion, veja o log de auditoria"), e emite um evento de conflito que pode ser assinado via webhooks. O Zap escuta, decide se tenta de novo ou alerta.

Nenhuma sobrescrita silenciosa em lugar nenhum. Toda escrita é registrada. Todo conflito ganha um comentário na linha. Para um registro permanente, envie o fluxo de auditoria para o seu data warehouse via o guia de exportação para ClickHouse ou acesse a API GraphQL diretamente.

Quando a mudança de destino NÃO deve se propagar

Às vezes você edita um Destination como rascunho. Dois padrões ajudam.

Propriedade de status como guarda. Adicione um Select chamado "Sync" com Draft, Live, Paused. A integração só sincroniza linhas onde Sync = Live. Prepare em Draft, mude para Live, a próxima verificação pega a mudança. A maioria das equipes de marketing acaba usando isso.

Pausar o banco de dados inteiro. Settings, Notion, pausar por banco de dados. Útil durante uma migração ou edições em massa.

Passo a passo de configuração: de zero à primeira linha sincronizada em 4 minutos

O passo 1 funciona hoje. Os passos 2 a 5 chegam com a sincronização planejada.

1. Conecte o Notion. Configurações do workspace, Integrações, Notion, Conectar. Escolha o workspace, marque os bancos de dados, Permitir.
2. Escolha um banco de dados. Settings, Notion, "Add database." O menu suspenso lista todo banco de dados que você concedeu. Escolha um.
3. Mapeie os campos. Confirme Destination, Title e o resto. Faltam propriedades? O Elido se oferece para criá-las.
4. Escolha um domínio. Selecione um domínio com marca própria para os links curtos. Ainda não tem um domínio personalizado? Escolha o padrão; a migração é um clique depois.
5. Salve e preencha retroativamente. O Elido lê cada linha, gera um link curto para qualquer uma com Destination mas sem Short URL, e escreve de volta. URLs curtas existentes são deixadas em paz.

O tempo real é de cerca de 4 minutos para 200 linhas. Preenchimentos retroativos maiores esbarram no limite de três requisições por segundo do Notion em workspaces gratuitos. Um banco de dados de 5.000 linhas preenche retroativamente em cerca de 30 minutos; o worker faz lotes e retoma sozinho quando limitado por taxa.

Quando usar isso versus o Zapier versus a API diretamente

Existem três caminhos, não mutuamente exclusivos.

A integração nativa é a escolha certa por padrão se o Notion é onde o trabalho acontece. OAuth, resolução de conflitos, log de auditoria, mapa de campos, sem código.

Um Zap é certo para workflows multi-etapa ("quando uma linha é adicionada E uma reação no Slack chega, então crie um link"). Para mapeamento um-para-um de linha para link, a integração nativa é mais rápida e mais barata. Veja o post de automação do Zapier.

A API REST é certa se você está construindo um workflow personalizado em cima do Elido. Para desenvolvedores construindo integrações de produto, o código-fonte em services/api-core/internal/integrations/notion/ é pequeno o suficiente para ler de uma sentada.

Comparando com Bitly ou Rebrandly: nenhum dos dois tem uma integração nativa com o Notion até o momento desta publicação. Os dois exigem o Zapier ou um script personalizado. Veja a página vs Bitly para a diferença e a página de preços para saber quais planos incluem bancos de dados ilimitados no Notion.

Solução de problemas: os quatro problemas que enfrentamos no Beta

Durante o Beta, quatro classes de problema apareceram. Vários dizem respeito à sincronização planejada em vez da conexão ao vivo, mas ajuda saber o que procurar.

"Banco de dados não encontrado" depois de renomear o workspace. Se um administrador do Notion renomeia o workspace, o ID do workspace permanece estável, mas os metadados em cache ficam desatualizados do nosso lado por até uma hora. Solução alternativa: clique em "Forçar nova sincronização" em Settings, Notion. O TTL do cache está definido em 15 minutos em produção, então isso é principalmente um artefato do Beta.

Limite de taxa durante um preenchimento retroativo grande. O limite por integração do Notion é de três requisições por segundo. Um banco de dados de 5.000 linhas esbarra nisso com força durante o preenchimento retroativo inicial. O worker recua exponencialmente (250ms, 500ms, 1s, 2s, limitado a 8s) e retoma. Você verá "Throttled by Notion, resuming" no log de atividade; isso é normal.

Incompatibilidade de tipo de propriedade. O bug mais comum do Beta. Um usuário escolheu uma coluna do Notion do tipo "Text" para Destination em vez de "URL". O validador do mapa de campos agora sinaliza isso no momento de salvar e recusa continuar. Se você vir "Destination must be a URL property," mude o tipo da coluna no Notion primeiro.

Usuário multi-workspace com bancos de dados compartilhados. Se a mesma pessoa é membro de dois workspaces do Notion e ambos querem conectar o Elido, cada workspace precisa da própria concessão OAuth. O token é por workspace, não por usuário. O fluxo de conexão lida com isso corretamente; apenas espere clicar em Conectar duas vezes.

Para qualquer coisa que não esteja nesta lista, a página de contato vai direto para a equipe de integrações. Vemos os problemas mais rápido lá do que no suporte genérico.

O que vem a seguir

Dois desdobramentos no roadmap. Uma receita "formulário do Notion para link curto" para que o envio de um formulário gere um link rastreado. E sincronização em duas vias em uma propriedade Workspace para que um link possa acompanhar quando você mover uma linha entre bancos de dados. Os dois estão no caminho para o terceiro trimestre; vamos anotá-los no changelog.

Para medir o impacto, o manual de analytics de link curto cobre quais métricas realmente importam e como configurar as linhas do painel no Notion para que respondam às perguntas certas.