Notion’s Developer Platform

O que é a Plataforma de Desenvolvedores do Notion?

A Plataforma de Desenvolvedores do Notion é um conjunto de capacidades para desenvolvedores construírem com o Notion como workspace compartilhado — sincronizando dados externos no Notion, criando ferramentas personalizadas que os Notion Agents podem usar e orquestrando fluxos de agentes multi-etapa.

Seu propósito principal é permitir conectar sistemas externos ao Notion (por exemplo, manter um Database do Notion atualizado de outra fonte) e estender Notion Agents com ações e interfaces de ferramentas específicas.

Principais Recursos

• Upsert contínuo de registros externos em um Database do Notion usando Workers com schema declarativo e cursor persistente, para que atualizações possam ser retomadas entre execuções.
• Sincronização agendada de um dataset externo no Notion (ex.: definindo um cronograma de sync como 5m no exemplo).
• Ferramentas personalizadas para Notion Agents que geram saídas (como assets) e interagem com APIs externas ou dados em tempo real.
• Interfaces de ferramentas estruturadas que definem o schema de entrada de uma ferramenta (ex.: string pageId para criar uma apresentação, ou string query SQL para executar uma consulta em warehouse).
• Orquestração de fluxos via webhook que escuta webhooks de outros apps e aciona fluxos do Notion com Notion Agents, páginas, databases e chamadas de API externas.

Como Usar a Plataforma de Desenvolvedores do Notion

1. Crie ou aponte para um Database do Notion e defina um mapeamento de schema entre esse database e seus campos de dados externos.
2. Construa um Worker para sincronizar dados: configure uma conexão de database gerenciada, forneça schema/chave primária inicial e escreva uma função de sync que retorna mudanças de registros (ex.: mapeando campos de origem em propriedades do Notion).
3. Defina um cronograma de sync e um identificador estável (chave primária) para que registros sejam upsertados em vez de duplicados.
4. Opcionalmente adicione ferramentas personalizadas para seus Notion Agents registrando ferramentas com nome, descrição, schema de entrada e um handler de execução que realiza ações (ex.: gerando um asset .pptx de uma página do Notion e fazendo upload de volta para a página).
5. Se precisar de automação orientada a eventos, configure listeners de webhook que acionam fluxos do Notion para executar com agents e chamar APIs externas.

Casos de Uso

• Ingestão de tickets de suporte no Notion: Sincronize continuamente tickets de um helpdesk externo em um Database do Notion usando um Worker, fazendo upsert por ID de ticket e mapeando campos como assunto, CSAT e tags.
• Geração automatizada de assets de conteúdo do Notion: Crie uma ferramenta personalizada (ex.: createPresentation) que lê uma página do Notion como markdown, converte headings em slides, faz upload de um .pptx gerado e anexa à página.
• Consulta a data warehouse de uma ferramenta de agent: Defina uma ferramenta (ex.: queryRevenue) que aceita uma string de query SQL, executa contra uma tabela de warehouse e retorna resultados para o fluxo de agent.
• Fluxos de ação acionados por eventos externos: Construa um fluxo via webhook que escuta eventos de qualquer app e executa fluxos do Notion usando Notion Agents com páginas/databases e chamadas de API externas.
• Ações de app baseado em browser controladas por ferramenta de agent: Implemente uma ferramenta de agent que usa um provedor de automação de browser para executar tarefas multi-etapa em um app externo (exemplo: listar refeições salvas, confirmar pedido e verificar status de entrega).

FAQ

A plataforma suporta manter databases do Notion sincronizados ao longo do tempo?

Sim. Os exemplos descrevem Workers que fazem upsert contínuo de registros externos em um Database do Notion, usando cursor persistente para retomar atualizações.

Que tipos de saídas ferramentas personalizadas podem gerar?

Os exemplos incluem gerar um PowerPoint (.pptx) do conteúdo de uma página do Notion e fazer upload de volta para a página.

Ferramentas de agent podem consultar sistemas externos em tempo real?

Sim. Uma ferramenta de exemplo executa uma query SQL contra uma tabela de warehouse de deals, e outro exemplo descreve ações de apps externos via automação de browser.

Como funcionam as automações orientadas a eventos?

A página descreve escutar webhooks de qualquer app e executar fluxos do Notion que usam Notion Agents, páginas, databases e chamadas de API externas.

O que é necessário para fazer upsert de registros no Notion?

Nos exemplos, você define uma conexão de database gerenciada com schema e propriedade de chave primária, depois fornece uma função de sync que mapeia registros externos em propriedades do Notion como upserts.

Alternativas

• Ferramentas ETL/ELT de uso geral (apenas para sincronização de dados): Se o seu objetivo principal é mover e transformar dados em um banco de dados, ferramentas ETL podem lidar com ingestão periódica, enquanto a Notion Developer Platform também abrange ferramentas para agentes e orquestração de fluxos.
• Plataformas de automação de fluxos (para gatilhos e orquestração): Ferramentas dessa categoria podem coordenar webhooks e ações entre apps, mas podem não oferecer o mesmo acoplamento estreito com Notion Agents que operam em páginas e databases do Notion.
• Frameworks de ferramentas para agentes com integrações externas (para chamadas de ferramentas personalizadas): Se você já está construindo sistemas de agentes, pode usar um framework de ferramentas para chamar APIs e gerar assets; a plataforma do Notion foca especificamente em interações de agentes e sincronização de dados em torno de workspaces do Notion.