Como Usar a API do Notion para Sincronizar com Banco de Dados Externo

Você quer sincronizar dados entre o Notion e um banco de dados externo como PostgreSQL, MySQL ou Google Sheets. Copiar entradas manualmente é lento e sujeito a erros. A API do Notion permite automatizar essa sincronização para que seu workspace do Notion sempre reflita os dados mais recentes da sua fonte externa. Este artigo explica como configurar a API do Notion, escrever um script de sincronização e lidar com problemas comuns.

O que a API do Notion Faz para Sincronizar com Banco de Dados Externo

A API do Notion é uma interface RESTful que permite ler e escrever dados no seu workspace do Notion. Para sincronizar com um banco de dados externo, você envia requisições HTTP de um script ou aplicação para os endpoints da API do Notion. A API retorna respostas JSON que você pode analisar e comparar com seus dados externos.

Antes de começar, você precisa de três coisas:

• Uma conta do Notion com acesso ao workspace onde seu banco de dados alvo existe
• Uma integração interna criada na página de configurações de Integrações do Notion
• Um banco de dados externo que você possa consultar programaticamente (por exemplo, um banco SQL com um conector Python)

A API do Notion usa cabeçalhos de versionamento. A versão estável atual é 2022-06-28. Sempre inclua o cabeçalho Notion-Version em suas requisições. O limite de taxa da API é de três requisições por segundo por integração. Para sincronizações grandes, adicione atrasos ou use processamento em lote para ficar abaixo desse limite.

Passos para Configurar a API do Notion e Sincronizar com um Banco de Dados Externo

1. Crie uma integração interna do Notion
   Acesse https://www.notion.so/my-integrations. Clique em Nova integração. Dê um nome, por exemplo SyncDB. Selecione o workspace. Em Capacidades, certifique-se de que Ler conteúdo, Atualizar conteúdo e Inserir conteúdo estejam habilitados. Clique em Enviar. Copie o token secreto da Integração Interna. Armazene-o com segurança.
2. Conecte a integração ao seu banco de dados do Notion
   Abra a página do seu banco de dados no Notion. Clique no menu de três pontos no canto superior direito. Selecione Adicionar conexões. Encontre sua integração SyncDB e clique em Conectar. Isso concede à integração acesso a esse banco de dados específico.
3. Obtenha o ID do banco de dados
   No seu navegador, abra a página do banco de dados do Notion. Observe a URL. Ela se parece com https://www.notion.so/workspace/abc123def456?.... A parte após o nome do workspace e antes do ponto de interrogação é o ID da página. Se a URL contiver um hífen e uma string de 32 caracteres, essa string é o ID do banco de dados. Por exemplo, em https://www.notion.so/MeuBanco-abc123def4567890abcdef1234567890, o ID é abc123def4567890abcdef1234567890.
4. Configure seu ambiente de desenvolvimento
   Instale Python 3.8 ou superior. Crie um ambiente virtual. Instale a biblioteca requests com pip install requests. Instale também o conector do seu banco de dados externo, por exemplo pip install psycopg2-binary para PostgreSQL.
5. Escreva um script Python para consultar o banco de dados do Notion
   Crie um arquivo chamado sync.py. Adicione código para enviar uma requisição POST ao endpoint de consulta da API do Notion. Use o token como um token Bearer no cabeçalho Authorization. O endpoint é https://api.notion.com/v1/databases/{database_id}/query. Analise a resposta JSON para obter uma lista de páginas existentes.
6. Escreva código para buscar dados do banco de dados externo
   No mesmo script, use seu conector de banco de dados para executar uma consulta SELECT. Por exemplo, com PostgreSQL: SELECT id, nome, email FROM usuarios. Armazene os resultados em uma lista Python de dicionários.
7. Compare e sincronize os dados
   Para cada registro no banco de dados externo, verifique se já existe uma página correspondente no Notion. Use uma propriedade de identificador único, como email ou ID externo. Se o registro existir, atualize a página do Notion usando o endpoint PATCH https://api.notion.com/v1/pages/{page_id}. Se não existir, crie uma nova página usando o endpoint POST https://api.notion.com/v1/pages. Para registros que existem no Notion mas não no banco externo, opcionalmente exclua ou arquive a página do Notion.
8. Execute o script em um agendamento
   Use um agendador de tarefas como cron no Linux ou o Agendador de Tarefas no Windows. Por exemplo, para executar a cada hora, adicione um job cron: 0 * * * * /usr/bin/python3 /caminho/para/sync.py.

Problemas Comuns de Sincronização e Suas Soluções

API do Notion retorna 401 Não Autorizado

Esse erro significa que o token de integração é inválido ou a integração não está conectada ao banco de dados. Verifique se você copiou o token corretamente. Confirme se a integração está listada na página do banco de dados em Adicionar conexões. Regere o token nas configurações de integrações, se necessário.

Limite de taxa excedido (429 Muitas Requisições)

A API do Notion permite três requisições por segundo por integração. Se seu script processar muitos registros rapidamente, você atingirá esse limite. Adicione um atraso entre as requisições usando time.sleep(0.4) para ficar abaixo de três requisições por segundo. Para conjuntos de dados grandes, processe registros em lotes de 10 a 20 com um atraso entre os lotes.

ID do banco de dados não encontrado ou inválido

Verifique novamente o ID do banco de dados a partir da URL da página. Certifique-se de estar usando o ID correto, não o nome do workspace ou um título de página. Se a URL contiver uma hashtag ou parâmetros extras, extraia apenas a string hexadecimal de 32 caracteres. Teste o ID consultando o banco de dados com um comando curl simples antes de executar o script completo.

Incompatibilidade de tipo de propriedade ao criar ou atualizar páginas

A API do Notion espera estruturas JSON específicas para cada tipo de propriedade. Por exemplo, uma propriedade de título requer um array com um objeto de texto, enquanto uma propriedade de rich text requer um array semelhante, mas com uma chave pai diferente. Consulte a documentação da API do Notion para o esquema exato de cada tipo de propriedade. Use o endpoint Recuperar um banco de dados para ver o esquema atual de propriedades do seu banco de dados.

Métodos de Sincronização com a API do Notion Comparados

Item	Script Python com requests	Ferramentas no-code (Zapier, Make)
Descrição	Script personalizado usando a API do Notion diretamente	Construtor visual de fluxos com conectores pré-construídos do Notion
Tempo de configuração	1-3 horas para um desenvolvedor	15-30 minutos
Flexibilidade	Controle total sobre lógica, tratamento de erros e transformação de dados	Limitado a triggers e ações disponíveis
Custo	Gratuito (exceto custos de servidor ou função em nuvem)	Plano gratuito limitado; planos pagos a partir de $20/mês
Tratamento de limite de taxa	Atraso manual e lógica de lote necessários	Limitação integrada na maioria das ferramentas
Melhor para	Lógica de sincronização complexa, grandes conjuntos de dados, agendamentos personalizados	Sincronizações simples unidirecionais, usuários não técnicos

Escolha a abordagem com script Python se precisar de sincronização bidirecional, transformações complexas de dados ou controle total sobre a recuperação de erros. Use ferramentas no-code para configurações rápidas onde o banco de dados externo também possui um conector pré-construído.

Agora você pode sincronizar um banco de dados externo com o Notion usando a API e um script Python. Comece criando a integração e conectando-a ao seu banco de dados do Notion. Teste o script com um conjunto de dados pequeno antes de automatizá-lo com um agendador. Para uso avançado, explore o recurso de paginação da API do Notion para lidar com bancos de dados com mais de 100 páginas.