Pular para conteúdo

Notion Integration - 8 Tools Documentadas

Visão Geral

Esta pasta contém a documentação completa das 8 tools de integração com Notion do Lumina Flow Builder. Todas as tools seguem o padrão de qualidade estabelecido no guia de documentação.

Configuração Inicial do Notion

Antes de usar qualquer tool Notion, você precisa:

1. Criar Integração no Notion

  1. Acesse https://www.notion.so/my-integrations
  2. Clique em "New integration"
  3. Dê um nome (ex: "Lumina Flow")
  4. Selecione seu workspace
  5. Configure permissões:
  6. ✅ Read content
  7. ✅ Update content
  8. ✅ Insert content
  9. Copie o "Internal Integration Token" (secret_...)

2. Compartilhar Páginas/Databases com a Integração

IMPORTANTE: A integração só acessa páginas/databases explicitamente compartilhados!

  1. Abra a página ou database no Notion
  2. Clique em "Share" (canto superior direito)
  3. Clique em "Invite"
  4. Procure pelo nome da sua integração
  5. Clique em "Invite"

Sem esse passo, você receberá erro 401 (Unauthorized).

3. Obter IDs

Page ID: - Abra a página no Notion - URL: https://notion.so/workspace/Nome-da-Pagina-PAGE_ID - O PAGE_ID é o código após o último traço - Exemplo: a8aec43c-6f00-4f57-89c9-e2e4aa3e8d9f

Database ID: - Abra o database no Notion - URL: https://notion.so/workspace/DATABASE_ID?v=... - O DATABASE_ID é o código entre / e ?v= - Exemplo: a8aec43c6f004f5789c9e2e4aa3e8d9f

As 8 Tools Notion

1. NOTION_CREATE_PAGE ✅

Criar novas páginas no Notion

Cria páginas dentro de databases com propriedades estruturadas e conteúdo inicial.

Use para: - Knowledge base automática - CRM de leads - Task management - Documentação dinâmica

Parâmetros principais: - databaseId: Onde criar - properties: Dados estruturados (título, status, tags, etc.) - content: Blocos de conteúdo inicial (opcional)

2. NOTION_UPDATE_PAGE ✅

Atualizar propriedades de páginas existentes

Modifica campos de páginas (status, datas, tags) sem alterar conteúdo.

Use para: - Mudança de status de tarefas - Atualizar estágio de leads - Modificar prioridades - Pipeline automation

Parâmetros principais: - pageId: Página a atualizar - properties: Campos a modificar (PATCH parcial)

3. NOTION_QUERY_DATABASE ✅

Buscar páginas com filtros e ordenação

Consulta databases com filtros complexos, ordenação e paginação.

Use para: - Listar tarefas pendentes - Buscar leads por email - Filtrar por status/data - Relatórios e contagens

Parâmetros principais: - databaseId: Database a consultar - filter: Condições de busca (AND, OR, equals, contains, etc.) - sorts: Ordenação (ascending/descending) - pageSize: Limite de resultados (1-100)

4. NOTION_ADD_BLOCK ✅

Adicionar conteúdo a páginas existentes

Anexa blocos (parágrafos, títulos, listas, código) ao final de páginas.

Use para: - Logs de conversa - Documentação incremental - Notas de reunião - Histórico de interações

Parâmetros principais: - blockId: Página onde adicionar (use pageId) - blocks: Array de blocos (paragraph, heading, list, to_do, code, etc.)

Tipos de blocos: - paragraph: Texto normal - heading_1/2/3: Títulos - bulleted_list_item: Lista com bullets - numbered_list_item: Lista numerada - to_do: Checkbox - quote: Citação - code: Bloco de código

5. NOTION_GET_PAGE ✅

Obter informações de página específica

Recupera dados completos de uma página por ID.

Use para: - Verificar status atual - Ler propriedades específicas - Validar existência - Decisões condicionais

Parâmetros principais: - pageId: ID da página

Retorna: - properties: Todas as propriedades da página - created_time: Data de criação - last_edited_time: Última edição - url: Link público

Buscar por texto livre no workspace

Busca global em páginas e databases por título.

Use para: - Encontrar página por nome - Busca sem saber onde está - Discovery de informações - Listar páginas recentes

Parâmetros principais: - query: Texto a buscar (vazio = retorna tudo) - filter: Filtrar por tipo (page ou database) - sort: Ordenar por last_edited_time - pageSize: Limite de resultados

Importante: - Busca apenas em títulos (não no conteúdo) - Case-insensitive - Só retorna páginas/databases compartilhados com a integração

7. NOTION_CREATE_DATABASE ✅

Criar novos databases programaticamente

Cria databases com estrutura de colunas definida.

Use para: - Setup automático de projetos - Multi-tenancy (database por cliente) - Templates dinâmicos - Replicar estruturas

Parâmetros principais: - pageId: Página parent (onde criar database) - title: Nome do database - properties: Definição de colunas

Tipos de propriedades: - title: Título (obrigatório, apenas 1) - rich_text: Texto rico - number: Números - select: Seleção única - multi_select: Múltipla seleção - date: Datas - checkbox: Sim/Não - url, email, phone_number: Campos específicos

8. NOTION_UPDATE_BLOCK ✅

Modificar blocos de conteúdo existentes

Edita texto de blocos já criados (parágrafos, títulos, etc.).

Use para: - Corrigir textos - Marcar/desmarcar to-dos - Atualizar listas - Revisões de conteúdo

Parâmetros principais: - blockId: ID do bloco a modificar - blockType: Tipo do bloco (paragraph, to_do, etc.) - content: Novo conteúdo

Importante: - Não pode mudar o tipo do block - Precisa saber o blockId específico - Útil para marcar to-dos como checked

Fluxos de Trabalho Comuns

1. Knowledge Base Automática

INPUT (pergunta/resposta)
  → NOTION_CREATE_PAGE (criar artigo FAQ)
  → MESSAGE (confirmar publicação)

2. CRM de Leads

EMAIL/PHONE (capturar dados)
  → NOTION_CREATE_PAGE (registrar lead)
  → [após qualificação]
  → NOTION_QUERY_DATABASE (buscar lead)
  → NOTION_UPDATE_PAGE (mudar status)

3. Task Management

NOTION_QUERY_DATABASE (buscar tarefas pendentes)
  → CONDITION (tem tarefas?)
  → MESSAGE (listar tarefas)
  → [ao concluir]
  → NOTION_UPDATE_PAGE (marcar concluída)

4. Documentação Incremental

NOTION_GET_PAGE (página de documentação)
  → NOTION_ADD_BLOCK (adicionar nova seção)
  → MESSAGE (confirmar atualização)

5. Logs e Histórico

[durante conversa]
  → NOTION_ADD_BLOCK (adicionar log de interação)
  → [repetir a cada mensagem importante]

Estrutura de Dados Notion

Properties (Campos de Database)

Title: 

{
  "Nome": {
    "title": [
      {
        "text": {
          "content": "Texto do título"
        }
      }
    ]
  }
}

Rich Text: 

{
  "Descrição": {
    "rich_text": [
      {
        "text": {
          "content": "Texto da descrição"
        }
      }
    ]
  }
}

Select: 

{
  "Status": {
    "select": {
      "name": "Em Progresso"
    }
  }
}

Multi-select: 

{
  "Tags": {
    "multi_select": [
      { "name": "Urgente" },
      { "name": "Bug" }
    ]
  }
}

Date: 

{
  "Prazo": {
    "date": {
      "start": "2025-01-20"
    }
  }
}

Checkbox: 

{
  "Concluída": {
    "checkbox": true
  }
}

Number: 

{
  "Prioridade": {
    "number": 5
  }
}

Email, URL, Phone: 

{
  "Email": {
    "email": "email@exemplo.com"
  },
  "Site": {
    "url": "https://exemplo.com"
  },
  "Telefone": {
    "phone_number": "+5511999999999"
  }
}

Filtros de Query

Filtros Simples

Igual: 

{
  "property": "Status",
  "select": {
    "equals": "Concluído"
  }
}

Contém: 

{
  "property": "Título",
  "rich_text": {
    "contains": "API"
  }
}

Maior que: 

{
  "property": "Prioridade",
  "number": {
    "greater_than": 5
  }
}

Data: 

{
  "property": "Prazo",
  "date": {
    "on_or_before": "2025-01-20"
  }
}

Filtros Compostos

AND (todos devem ser true): 

{
  "and": [
    {
      "property": "Status",
      "select": {
        "equals": "A Fazer"
      }
    },
    {
      "property": "Prioridade",
      "select": {
        "equals": "Alta"
      }
    }
  ]
}

OR (pelo menos um deve ser true): 

{
  "or": [
    {
      "property": "Status",
      "select": {
        "equals": "A Fazer"
      }
    },
    {
      "property": "Status",
      "select": {
        "equals": "Em Progresso"
      }
    }
  ]
}

Erros Comuns e Soluções

Erro 401 - Unauthorized

Causa: Database/página não compartilhado com integração Solução: Share a página/database com sua integração no Notion

Erro 404 - Not Found

Causa: ID inválido ou página deletada Solução: Verifique se o ID está correto e página existe

Erro 400 - Invalid Property

Causa: Nome de propriedade incorreto (case-sensitive!) Solução: Verifique os nomes exatos das colunas no database

Erro 400 - Invalid Block Type

Causa: Tentando atualizar block com tipo incompatível Solução: Use blockType correto para o block que está atualizando

results[0] undefined

Causa: Query não retornou resultados Solução: Use CONDITION antes de acessar results[0]

Boas Práticas Gerais

Segurança

  • ✅ Use variáveis para apiKey (não hardcode)
  • ✅ Não exponha tokens em logs/mensagens
  • ✅ Valide dados do usuário antes de criar páginas

Performance

  • ✅ Use QUERY com filtros ao invés de buscar tudo
  • ✅ Limite pageSize para queries grandes
  • ✅ Use GET quando você tem o ID ao invés de QUERY

Arquitetura

  • ✅ Salve pageIds/databaseIds em variáveis
  • ✅ Combine operations: QUERY → CONDITION → UPDATE
  • ✅ Use SEARCH para discovery, QUERY para dados estruturados

Manutenção

  • ✅ Nomes de properties são case-sensitive
  • ✅ Valide se results.length > 0 antes de acessar índices
  • ✅ Trate erros com CONDITION nodes

Exemplos de Uso Real

CRM Completo

1. NOTION_CREATE_DATABASE (criar database "Leads")
2. INPUT (capturar nome)
3. EMAIL (capturar email)
4. PHONE (capturar telefone)
5. NOTION_CREATE_PAGE (criar lead no database)
6. MESSAGE (confirmar cadastro)

Task Management

1. NOTION_QUERY_DATABASE (buscar tarefas "A Fazer")
2. CONDITION (tem tarefas?)
3. MESSAGE (listar tarefas)
4. INPUT (qual tarefa concluir?)
5. NOTION_UPDATE_PAGE (marcar como "Concluído")
6. MESSAGE (confirmar)

Documentação Automática

1. INPUT (tópico da documentação)
2. INPUT (conteúdo)
3. NOTION_SEARCH (buscar página de docs)
4. NOTION_ADD_BLOCK (adicionar seção com conteúdo)
5. MESSAGE (link da página atualizada)

Recursos Adicionais

  • Notion API Docs: https://developers.notion.com
  • API Reference: https://developers.notion.com/reference
  • Property Types: https://developers.notion.com/reference/property-object
  • Filter Types: https://developers.notion.com/reference/post-database-query-filter

Status da Documentação

Tool Status Arquivo
NOTION_CREATE_PAGE ✅ Completo notion_create_page.md
NOTION_UPDATE_PAGE ✅ Completo notion_update_page.md
NOTION_QUERY_DATABASE ✅ Completo notion_query_database.md
NOTION_ADD_BLOCK ✅ Completo notion_add_block.md
NOTION_GET_PAGE ✅ Completo notion_get_page.md
NOTION_SEARCH ✅ Completo notion_search.md
NOTION_CREATE_DATABASE ✅ Completo notion_create_database.md
NOTION_UPDATE_BLOCK ✅ Completo notion_update_block.md

Total: 8/8 tools documentadas ✅

Padrão: Todas seguem o guia de documentação estabelecido em /home/zielinski/develop/gptapi/docs/DOCUMENTATION_GUIDE.md

Última atualização: 2025-01-15 Autor: Sistema de documentação automatizada Versão da API Notion: 2022-06-28