Como Importar Dados para o Notion via API em Lote

Você quer importar grandes conjuntos de dados para o Notion sem digitar cada linha manualmente. O Notion oferece uma API REST que permite criar, atualizar e consultar páginas de banco de dados programaticamente. Este artigo explica como usar a API do Notion para fazer upload em lote de dados de um arquivo CSV para um banco de dados do Notion. Você aprenderá como configurar uma integração, autenticar requisições e escrever um script que envia várias páginas em um único lote.

O Que o Recurso de Upload em Lote da API do Notion Faz e o Que Você Precisa

A API do Notion permite que aplicativos externos criem páginas dentro de um banco de dados. Cada página corresponde a uma linha em uma tabela de banco de dados. Um upload em lote significa que você envia várias requisições de criação em sequência, normalmente a partir de um arquivo CSV ou array JSON. A API não suporta uma única requisição que crie muitas páginas de uma vez. Você deve enviar uma requisição POST por página.

Antes de começar, você precisa de três coisas. Primeiro, um token de integração do Notion. Esse token identifica seu script para os servidores do Notion. Segundo, o ID do banco de dados de destino. Terceiro, os dados de origem, geralmente em formato CSV, com cabeçalhos de coluna que correspondam aos nomes das propriedades do banco de dados.

Como o Limite de Taxa da API do Notion Afeta Uploads em Lote

O Notion impõe um limite de taxa de três requisições por segundo por integração. Se você enviar requisições mais rápido, a API retorna um erro 429 Too Many Requests. Para ficar abaixo desse limite, adicione um atraso de pelo menos 333 milissegundos entre as requisições. Um atraso prático é de 350 milissegundos para fornecer uma margem de segurança.

Tipos de Propriedade que Exigem Tratamento Especial

As propriedades do banco de dados do Notion têm estruturas JSON diferentes. Propriedades de texto aceitam uma string simples. Propriedades Select exigem um array com um campo name. Propriedades Date precisam de um objeto com uma chave start no formato ISO 8601. Propriedades Relation exigem um array de objetos, cada um contendo um database_id e um id. Seu script deve mapear cada coluna do CSV para o tipo de propriedade correto. Se o mapeamento estiver errado, a API retorna um erro 400 Bad Request.

Passos para Importar Dados para o Notion via API em Lote

Os passos a seguir assumem que você tem um arquivo CSV pronto e um banco de dados do Notion com propriedades que correspondem às colunas do CSV. Você usará Python com a biblioteca requests. Se preferir outra linguagem, as chamadas de API são idênticas.

1. Criar uma integração do Notion
   Acesse https://www.notion.so/my-integrations. Clique em New integration. Dê um nome, por exemplo Bulk Upload Script. Selecione o workspace que contém seu banco de dados de destino. Clique em Submit. Copie o token Internal Integration Secret. Esse token se parece com secret_abc123.
2. Compartilhar o banco de dados de destino com a integração
   Abra seu banco de dados do Notion no navegador. Clique em Share no canto superior direito. Clique em Invite. Cole o nome da integração do passo 1. Clique em Invite. A integração agora tem permissão para ler e escrever páginas nesse banco de dados.
3. Obter o ID do banco de dados
   Abra a página do banco de dados no navegador. Olhe a URL. Ela se parece com https://www.notion.so/nome-do-workspace/titulo-do-banco-hash?v=xxx. O ID do banco de dados é a string de 32 caracteres entre a última barra e o ponto de interrogação. Por exemplo, em https://www.notion.so/meuworkspace/abc123def456?v=xxx, o ID é abc123def456.
4. Preparar o arquivo CSV
   Certifique-se de que a primeira linha contém cabeçalhos de coluna que correspondam exatamente aos nomes das propriedades do Notion. Por exemplo, se seu banco de dados do Notion tem uma propriedade Title chamada Name e uma propriedade Select chamada Status, os cabeçalhos do CSV devem ser Name e Status. Salve o arquivo como data.csv na mesma pasta do seu script.
5. Escrever o script Python
   Crie um arquivo chamado bulk_upload.py. Use o seguinte modelo de código. Substitua YOUR_TOKEN pelo token do passo 1 e YOUR_DATABASE_ID pelo ID do passo 3.

   import requests
   import csv
   import time
   
   NOTION_TOKEN = 'YOUR_TOKEN'
   DATABASE_ID = 'YOUR_DATABASE_ID'
   HEADERS = {
       'Authorization': f'Bearer {NOTION_TOKEN}',
       'Content-Type': 'application/json',
       'Notion-Version': '2022-06-28'
   }
   
   def create_page(data):
       url = 'https://api.notion.com/v1/pages'
       payload = {
           'parent': { 'database_id': DATABASE_ID },
           'properties': data
       }
       response = requests.post(url, headers=HEADERS, json=payload)
       return response
   
   with open('data.csv', newline='', encoding='utf-8') as csvfile:
       reader = csv.DictReader(csvfile)
       for row in reader:
           properties = {}
           for key, value in row.items():
               # Mapear cada coluna do CSV para o tipo de propriedade do Notion
               # Ajuste este mapeamento com base no esquema do seu banco de dados
               if key == 'Name':
                   properties[key] = {
                       'title': [
                           { 'text': { 'content': value } }
                       ]
                   }
               elif key == 'Status':
                   properties[key] = {
                       'select': { 'name': value }
                   }
               elif key == 'Due Date':
                   properties[key] = {
                       'date': { 'start': value }
                   }
               else:
                   # Padrão para rich text nas outras colunas
                   properties[key] = {
                       'rich_text': [
                           { 'text': { 'content': value } }
                       ]
                   }
           response = create_page(properties)
           if response.status_code == 200:
               print(f'Página criada: {response.json()["id"]}')
           else:
               print(f'Erro: {response.status_code} {response.text}')
           time.sleep(0.35)  # Respeitar limite de taxa

6. Executar o script
   Abra um terminal na pasta que contém bulk_upload.py e data.csv. Execute python bulk_upload.py. O script lê cada linha, envia uma requisição POST e imprime o ID da página criada ou um erro. Aguarde até que todas as linhas sejam processadas.
7. Verificar os dados no Notion
   Abra seu banco de dados do Notion. Você deve ver novas páginas para cada linha do CSV. Se algumas páginas estiverem faltando, verifique as mensagens de erro no terminal. Erros comuns incluem mapeamento incorreto de propriedades ou propriedades obrigatórias ausentes.

Erros Comuns no Upload em Lote e Como Corrigi-los

API retorna 400 Bad Request com erro de validação

Esse erro significa que o payload JSON não corresponde ao esquema do banco de dados. Verifique se cada nome de propriedade no payload corresponde exatamente ao nome da propriedade no Notion. Confirme também se o tipo de propriedade está correto. Por exemplo, se uma propriedade é do tipo Select, você deve enviar um objeto com uma chave name, não uma string.

API retorna 401 Unauthorized

O token de integração é inválido ou a integração não tem acesso ao banco de dados. Regere o token na página de integrações. Em seguida, verifique se você compartilhou o banco de dados com a integração clicando em Share no Notion e garantindo que o nome da integração aparece na lista.

API retorna 429 Too Many Requests

Seu script enviou requisições mais rápido que o limite de taxa. Aumente o atraso entre as requisições para pelo menos 0,35 segundos. Se o erro persistir, adicione um mecanismo de repetição que espera 1 segundo e tenta novamente a requisição falha.

Algumas linhas estão faltando após o upload

O script pode ter parado cedo devido a um erro não tratado. Adicione um bloco try-except em torno da chamada de API para capturar exceções e continuar com a próxima linha. Registre as linhas com falha em um arquivo separado para que você possa tentar novamente mais tarde.

Upload em Lote via API do Notion vs. Entrada Manual vs. Ferramentas de Terceiros

Item	Upload em Lote via API	Entrada Manual	Ferramentas de Terceiros
Velocidade	Rápido para milhares de linhas	Lento para mais de 10 linhas	Rápido, mas limitado pela capacidade da ferramenta
Custo	Gratuito com a API do Notion	Gratuito (custo de mão de obra)	Geralmente assinatura paga
Personalização	Controle total sobre o mapeamento de propriedades	Controle total, mas manual	Limitado aos recursos da ferramenta
Tratamento de erros	Deve escrever lógica de repetição	Feedback visual imediato	Tratamento de erros integrado
Curva de aprendizado	Requer conhecimento de programação	Nenhum aprendizado necessário	Baixa a média

O método da API oferece o maior controle e é gratuito, mas requer habilidades de programação. A entrada manual funciona para conjuntos de dados pequenos. Ferramentas de terceiros como Zapier ou Make oferecem um meio-termo com uma taxa de assinatura.

Agora você pode importar dados para o Notion usando a API com um script que lê um CSV e cria páginas automaticamente. Para melhorar a confiabilidade, adicione registro de erros e lógica de repetição. Como dica avançada, use o parâmetro filter_properties da API do Notion para acelerar o upload enviando apenas as propriedades que o banco de dados realmente usa. Isso reduz o tamanho do payload e evita erros de validação.