Migrar do Quip para o Notion exige mover tanto o conteúdo dos documentos quanto os comentários anexados. O Notion não oferece um importador direto do Quip, então você precisa construir um pipeline personalizado. Este artigo explica como exportar dados do Quip, transformá-los para o Notion e importar comentários usando a API do Notion. Ao final, você terá um processo repetível que preserva o histórico de discussões da sua equipe.
Principais Pontos: Migração do Quip para o Notion com Comentários
- Exportação do Quip > CSV + HTML: Exporte todos os documentos e threads para obter o conteúdo e os metadados dos comentários.
- API do Notion > Criar Página: Use o endpoint Criar Página para inserir o conteúdo do documento como blocos do Notion.
- API do Notion > Anexar Blocos Filhos: Adicione blocos de comentários após o corpo do documento usando o endpoint Anexar Blocos Filhos.
- Gerenciamento de Limite de Taxa: Insira um atraso de 1 segundo entre chamadas de API para evitar o limite de 3 requisições por segundo do Notion.
Por que um Pipeline Personalizado é Necessário para a Migração do Quip
O Quip armazena documentos e comentários em um formato proprietário que o Notion não consegue interpretar nativamente. Os importadores integrados do Notion suportam CSV, HTML, Markdown e outros formatos comuns, mas não reconhecem a estrutura de exportação do Quip. Para migrar comentários, você deve extraí-los da exportação de threads do Quip, mapear cada comentário ao seu documento pai e inseri-los como blocos separados no Notion. O pipeline usa a API de exportação do Quip para baixar todos os dados, um script Python para transformar os dados em requisições da API do Notion e processamento em lote para respeitar os limites de taxa.
O que Você Precisa Antes de Começar
Você precisa de uma conta Quip com privilégios de administrador para exportar todos os documentos e threads. Você também precisa de um token de integração do Notion, obtido na página de Integrações do Notion. É necessário conhecimento básico de Python e APIs REST. Instale Python 3.8 ou superior e a biblioteca requests. Prepare um banco de dados do Notion onde cada documento importado se tornará uma página.
Passos para Construir o Pipeline de Importação
- Exportar Dados do Quip
Acesse o Console de Administração do Quip > Exportar. Selecione Exportar Todos os Dados. Escolha o formato JSON. Aguarde a conclusão da exportação. Baixe o arquivo. Ele contém pastas para cada documento e um arquivo threads.json com os dados dos comentários. - Analisar o Arquivo de Exportação
Extraia o arquivo. Abra threads.json. Cada objeto de thread possui thread_id, title, html (conteúdo do documento) e um array comments. Cada objeto de comentário possui author_id, created_at e text. Armazene esses dados em um dicionário Python indexado por thread_id. - Criar uma Integração no Notion
Acesse a página de Integrações do Notion. Clique em Nova Integração. Nomeie como Quip Importer. Selecione o workspace. Copie o token secreto da Integração Interna. Compartilhe o banco de dados de destino com a integração abrindo a página do banco de dados, clicando em Compartilhar e adicionando o nome da integração. - Escrever o Script Python
Crie um novo arquivo Python. Importe requests e json. Defina a URL base da API do Notion como https://api.notion.com/v1. Configure os cabeçalhos com Authorization: Bearer SEU_TOKEN e Content-Type: application/json. Defina Notion-Version como 2022-06-28. - Criar uma Página para Cada Documento
Percorra cada thread em threads.json. Monte um payload JSON para o endpoint Criar Página. Defina parent.database_id como o ID do banco de dados de destino. Defina properties.title.title[0].text.content como o título da thread. Defina children como um array de objetos de bloco convertidos do HTML da thread. Use os tipos de bloco do Notion: paragraph, heading_1, heading_2, heading_3, bulleted_list_item, numbered_list_item e to_do. Envie uma requisição POST para /pages. Armazene o ID da página retornado. - Migrar Comentários
Após criar a página, percorra o array de comentários da thread. Para cada comentário, monte um objeto de bloco do tipo paragraph com o texto do comentário. Anexe um bloco callout com o nome do autor e timestamp como rich_text. Envie uma requisição PATCH para /blocks/{page_id}/children com os blocos de comentários no array children. Isso adiciona os comentários abaixo do conteúdo do documento. - Gerenciar Limites de Taxa
Adicione uma chamada time.sleep(1) após cada requisição de API. O Notion permite 3 requisições por segundo. Um atraso de 1 segundo garante que você fique abaixo do limite. Para exportações grandes, considere agrupar requisições e usar backoff exponencial em respostas 429. - Executar o Script e Verificar
Execute o script Python. Monitore a saída do console em busca de erros. Abra o banco de dados de destino no Notion. Confirme que cada página contém o conteúdo do documento seguido pelos blocos de comentários. Verifique alguns comentários para garantir que o nome do autor e o timestamp apareçam corretamente.
Problemas Comuns Durante a Migração do Quip para o Notion
HTML do Quip Contém Tags Não Suportadas
As exportações do Quip incluem tags HTML como
Comentários Não Aparecem na Ordem Correta
O array de comentários em threads.json é ordenado por data de criação crescente. Se você anexar os comentários na mesma ordem, eles aparecerão cronologicamente. Se a ordem estiver errada, ordene o array de comentários por created_at antes de montar a lista de blocos.
Erros de Limite de Taxa (HTTP 429)
O Notion retorna 429 Too Many Requests quando você excede 3 requisições por segundo. Aumente o atraso para 1,5 segundos ou implemente um loop de repetição. Use o valor do cabeçalho Retry-After para aguardar o tempo necessário antes de tentar novamente.
Falha na Criação da Página Devido a Estrutura de Bloco Inválida
O Notion exige um objeto de bloco válido para cada filho. Campos obrigatórios ausentes, como type ou paragraph.rich_text, causam um erro 400. Valide cada objeto de bloco contra o esquema de blocos do Notion antes de enviar a requisição. Use o playground da API do Notion para testar payloads de exemplo.
Métodos da API do Notion para Migração Comparados
| Item | Criar Página | Anexar Blocos Filhos |
|---|---|---|
| Endpoint | POST /pages | PATCH /blocks/{block_id}/children |
| Finalidade | Cria uma nova página em um banco de dados com conteúdo inicial | Adiciona blocos a uma página ou bloco existente |
| Limite de tamanho do payload | 4 MB | 4 MB por requisição |
| Limite de taxa | 3 requisições por segundo | 3 requisições por segundo |
| Melhor para | Inserir o corpo principal do documento | Adicionar comentários após o corpo |
Agora você tem um pipeline funcional para migrar documentos e comentários do Quip para o Notion. Execute o script em um pequeno conjunto de teste primeiro para confirmar a conversão HTML e o posicionamento dos comentários. Após a validação, processe a exportação completa. Para melhorar o pipeline, adicione registro de erros em um arquivo e reenvie requisições com falha automaticamente. Para exportações muito grandes, divida o threads.json em lotes de 50 threads para reduzir o uso de memória.