Notion

Descripción

Integración con la API REST de Notion (URL base https://api.notion.com/v1). Seis nodos cubren el trabajo diario de un espacio: crear una página (como fila de una base de datos o como subpágina), leer una página por su id, actualizar sus propiedades o archivarla, consultar una base de datos con filtros y orden, agregar bloques de contenido y dejar un comentario.

La autenticación se resuelve mediante el módulo de credenciales (tipo de servicio notion): token Bearer más la cabecera obligatoria Notion-Version, que se envía automáticamente en cada petición (por defecto 2022-06-28).

Operaciones

Crear página Creá una fila de base de datos o una subpágina.

Leer página Leé una página por su id.

Actualizar página Actualizá propiedades, archivá o restaurá.

Consultar base de datos Filtrá y ordená una base, obtené las filas.

Agregar contenido Sumá bloques o un párrafo a una página.

Comentar página Publicá un comentario en una página.

Configuración

Cada nodo muestra solo los campos que necesita. Esta es la lista combinada de los seis:

Parámetro	Tipo	Obligatorio	Descripción
credentials_id	credentials	Sí	Credencial de Notion (proveedor `notion`)
database_id	text	Condicional	ID de la base de datos: padre en Crear página, destino en Consultar base de datos
parent_page_id	text	Condicional	ID de la página padre en Crear página, cuando el padre no es una base de datos
page_id	text	Condicional	ID de la página: Leer, Actualizar y Comentar
block_id	text	Condicional	ID de la página o bloque padre: Agregar contenido
properties	json	Condicional	Propiedades tipadas de la página, en formato Notion
children	json	No	Array de bloques de contenido (formato Notion)
filter	json	No	Filtro de la consulta (formato Notion)
sorts	json	No	Array de orden (formato Notion)
page_size	number	No	Máximo de resultados por consulta (1-100)
text	textarea	Condicional	Texto plano: cuerpo del comentario o párrafo a agregar
archived	text	No	`true` archiva la página, `false` la restaura

Credenciales

Tipo de servicio: notion. Se guardan en la tabla servicecredentials.

token: el Internal Integration Secret de notion.so/my-integrations. Obligatorio.
notion_version: valor que se envía en la cabecera Notion-Version (por defecto: 2022-06-28). Opcional.
timeout: tiempo máximo de la petición en milisegundos (por defecto: 20000). Opcional.

El botón Test llama a GET /users/me y devuelve el nombre de la integración.

Propiedades tipadas

En Notion las propiedades de una página son objetos tipados que dependen del tipo de columna (title, rich_text, select, date, number, relation y demás). Por eso properties, filter y sorts son campos JSON en el formato propio de Notion. Un título se ve así:

{ "Name": { "title": [ { "text": { "content": "Lead nuevo" } } ] } }

Salida

{
  "nextModule": null,
  "data": {
    "object": "page",
    "id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
    "url": "https://www.notion.so/8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e",
    "properties": {
      "Name": { "title": [ { "text": { "content": "Lead nuevo" } } ] }
    }
  },
  "_meta": {
    "moduleVersion": "1.0.0",
    "success": true,
    "id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
    "url": "https://www.notion.so/8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e",
    "totalMs": 340
  }
}

Consultar base de datos es la excepción: su data es el array de páginas (results), y _meta trae count, has_more y next_cursor.

API utilizada

API REST de Notion — https://developers.notion.com/reference/intro
URL base: https://api.notion.com/v1
Endpoints: POST /pages, GET /pages/{id}, PATCH /pages/{id}, POST /databases/{id}/query, PATCH /blocks/{id}/children, POST /comments

Notas

La cabecera Notion-Version es obligatoria en toda llamada. Los nodos envían 2022-06-28 salvo que la credencial indique otro valor.
Los campos de texto e id aceptan variables dinámicas como {{data.email}}, también dentro de los campos JSON.
Los fallos transitorios (timeout, 429 por límite de peticiones, 409 de conflicto, 5xx y errores de red) se reintentan automáticamente hasta 3 veces con espera exponencial, respetando la cabecera Retry-After.
Los errores de validación (400), de autenticación (401/403) y de recurso no encontrado (404) no se reintentan: corregí el JSON, la credencial o los permisos de compartición.
Notion limita page_size a 100. Usá next_cursor de _meta para recorrer bases largas.
El tiempo máximo de la petición es de 20 segundos por defecto.
Para endpoints que estos seis nodos no cubren (búsqueda, usuarios, lectura de bloques…), usá el nodo HTTP con los mismos valores de la credencial.

Nodos relacionados

Jira, Asana, Trello y ClickUp — otras integraciones de gestión del trabajo.
Cola de reintentos (DLQ) — cómo se reintentan las ejecuciones fallidas.