<aside> ❗ Utiliza esta página como ejemplo para estructurar tus Referencias API y alójalas en Notion.

La base de datos Endpoints también incluye una plantilla para ampliar tu biblioteca

</aside>

Introducción

Usar las referencias es clave para comprender a fondo la API de Notion.

<aside> ❗ Necesitas un código de integración para interactuar con la API de Notion. Puedes encontrar un código de integración después de crear una integración en la página de configuración. Si es la primera vez que echas un vistazo a la API de Notion, te recomendamos que empieces por la Guía de iniciación para aprender a crear una integración.

</aside>

La URL base para enviar todas las solicitudes API es https://api.notion.com. Se requiere HTTPS para todas las solicitudes de la API.

La API de Notion sigue las convenciones RESTful siempre que es posible, y la mayoría de las operaciones se realizan mediante solicitudes GET, POST, PATCH y DELETE en recursos de páginas y bases de datos. Los cuerpos de solicitud y respuesta se codifican como JSON.

CONVENCIONES JSON

Los recursos de nivel superior tienen una propiedad "objeto". Esta propiedad puede utilizarse para determinar el tipo de recurso (por ejemplo, "base de datos", "usuario", etc.).
Los recursos de nivel superior se pueden direccionar mediante una propiedad "id" UUIDv4. Puedes omitir los guiones del ID cuando realices solicitudes a la API, por ejemplo, al copiar el ID de una URL de Notion.
Los nombres de las propiedades están en snake_case (no en camelCase o kebab-case).
Los valores temporales (fechas y datetimes) se codifican en cadenas ISO 8601. Las fechas incluirán el valor de la hora (2020-08-12T02:12:33.231Z), mientras que las fechas sólo incluirán la fecha (2020-08-12).
La API de Notion no admite cadenas vacías. Para anular el valor de una cadena en propiedades como url Objeto valor de propiedad, por ejemplo, utiliza un null explícito en lugar de "".

Muestras de código y SDKs

Se muestran ejemplos de solicitudes y respuestas para cada endpoint. Las solicitudes se muestran utilizando la Noción JavaScript SDK, y cURL. Estos ejemplos facilitan la tarea de copiar, pegar y modificar a medida que construyes tu integración.

Los SDK de Notion son proyectos de código abierto que puedes instalar para empezar a construir fácilmente. También puedes elegir cualquier otro lenguaje o librería que te permita hacer peticiones HTTP.

Paginación

Los endpoints que devuelven listas de objetos admiten peticiones de paginación basadas en el cursor. Por defecto, Notion devuelve diez elementos por llamada a la API. Si el número de elementos en una respuesta de un endpoint compatible supera el valor predeterminado, una integración puede utilizar la paginación para solicitar un conjunto específico de los resultados y/o limitar el número de elementos devueltos.

ENDPOINTS ADMITIDOS

HTTP method	Endpoint
GET	Lista de todos los usuarios
GET	¿Extraer block children?
GET	Recuperar un comentario
GET	Recuperar un elemento de propiedad de página
POST	Consultar una base de datos
POST	Búsqueda

RESPUESTAS

Campo	Tipo	Descripción
`has_more`	`boolean`	Si la respuesta incluye el final de la lista. `false` (falso), si no hay más resultados. En caso contrario, `true` (verdadero).
`next_cursor`	`string`	Una cadena que puede utilizarse para recuperar la siguiente página de resultados pasando el valor como parámetros `start_cursor` al mismo endpoint. Sólo disponible cuando `has_more` es verdadero.
`objet`	`"list"`	La cadena constante `"lista"`.
`results`	`array of objects`	La lista, o lista parcial, de resultados específicos del endpoint. Para más detalles, consulta la documentación individual de cada endpoint compatible. La lista, o lista parcial, de resultados específicos del endpoint. Para más detalles, consulta la documentación de endpoint compatible.

Límites de solicitud

Para garantizar una experiencia de desarrollador coherente para todos los usuarios de la API, la API de Notion tiene una tasa limitada y se aplican límites de tamaño básicos a los parámetros de solicitud.

Límites de velocidad

Las solicitudes con tasa limitada devolverán un código de error "rate_limited" (estado de respuesta HTTP 429). El límite de velocidad para las solicitudes entrantes por integración es una media de tres solicitudes por segundo. Se permite algo más allá de la velocidad media.

<aside> ❗ Los límites pueden cambiar

En el futuro, tenemos previsto ajustar los límites para equilibrar la demanda y la fiabilidad. También es posible que introduzcamos límites de tarifa distintos para espacios de trabajo en diferentes planes de precios.

</aside>

Límites de tamaño

Notion limita el tamaño de ciertos parámetros y la profundidad de los hijos en las peticiones. Una solicitud que supere cualquiera de estos límites devolverá el código de error "validation_error" (estado de respuesta HTTP 400) y contendrá detalles más específicos en la propiedad "message".

Tipo de valor de la propiedad	Propiedad interior	Límite de tamaño
Rich text object	`texto.contenido`	2000 caracteres
Rich text object	`texto.link.url`	2000 caracteres
Rich text object	`ecuación.expression`	1000 caracteres
Cualquier conjunto de rich text objects		100 elementos

Códigos de estado

Los códigos de respuesta HTTP se utilizan para indicar clases generales de éxito y error.

Código (ha funcionado)

HTTP Status Quote	Description
200	Successfully processed request.

Código de error

Las respuestas de error contienen más detalles sobre el error en el cuerpo de la respuesta, en las propiedades "código" y "mensaje".

HTTP Status Quote	`code`	`message`
400	invalid_json	El cuerpo de la petición no se ha podido descodificar como JSON
	invalid_request_url	Esta URL de solicitud no es válida.
	invalid_request	Esta petición no es compatible.
401	unauthorized	La ficha del token no es válida.

Versiones

Las versiones de nuestra API se denominan según la fecha de publicación de la versión. Por ejemplo, nuestra última versión es 2022-06-28.

Estableces la versión incluyendo una cabecera Notion-Version. Establecer la cabecera Notion-Version en requerido.

Versiones

Las versiones de nuestra API se denominan según la fecha de publicación de la versión. Por ejemplo, nuestra última versión es 2022-06-28.

Estableces la versión incluyendo una cabecera Notion-Version. Establecer la cabecera Notion-Version en requerido.

curl <https://api.notion.com/v1/users/01da9b00-e400-4959-91ce-af55307647e5> \\
  -H "Authorization: Bearer secret_t1CdN9S8yicG5eWLUOfhcWaOscVnFXns"
  -H "Notion-Version: 2022-06-28"

Objetos

Usuarios

Dónde aparecen los objetos de usuario en la API

Los objetos de usuario aparecen en casi todos los objetos devueltos por la API, incluyendo:

Objeto bloque en creado_por y última_edición_por.
Objeto de página en creado_por y última_edición_por y en los elementos de propiedad gente.
Objeto de base de datos en creado_por y última_edición_por.
Objeto de texto enriquecido, como menciones de usuario.
Objeto propiedad cuando la propiedad es una propiedad people.

Los objetos de usuario contendrán siempre las claves objecto e id, como se describe a continuación. Las propiedades restantes pueden aparecer si el usuario está siendo renderizado en un contexto de texto enriquecido o de propiedades de página, y el bot tiene las capacidades correctas para acceder a esas propiedades. Para más información sobre las capacidades, consulta la Guía de capacidades y la Guía de autorización.

Todos los usuarios

Estos campos son compartidos por todos los usuarios, incluyendo personas y bots. Los campos marcados con * están siempre presentes.

Propiedad	Actualizable	Tipo	Description	Valor de ejemplo
`objeto`*	Sólo en pantalla	`"user"`	Siempre "user"	`"user"`
`id`*	Sólo en pantalla	`string`(UUID)	Identificador único para este usuario.	`"e79a0b74-3aba-4149-9f74-0bb5791a6ee6"`
`tipo`	Sólo en pantalla	`string`(optional, enum)	Tipo de usuario. Los valores posibles son `"person"` y `"bot"`.	`"person"`
`nombre`	Sólo en pantalla	`string`(optional)	Nombre del usuario, tal y como aparece en Notion.	`"Avocado Lovelace"`
`avatar_url`	Sólo en pantalla	`string`(optional)	Imagen de avatar elegida.	`"<https://secure.notion-static.com/e6a352a8-8381-44d0-a1dc-9ed80e62b53d.jpg>"`

Archivo

Los objetos Archivo contienen datos sobre un archivo que se sube a Notion, o datos sobre un archivo externo al que se enlaza en Notion.

{
  "type": "file",
  "file": {
    "url": "<https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject>",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

Página, incrustar, imagen, vídeo, archivo, pdf y marcador tipos de bloque contienen objetos de archivo. Icono y portada valores de objeto de página también contienen objetos de archivo.

Cada objeto de archivo incluye los siguientes campos:

Campo	Tipo	Descripción	Valor de ejemplo
`tipo`	`string` (enum)	El tipo del objeto archivo. Los posibles valores de tipo son: `"externo"`, `"archivo"`.	`"externo"`
`external`	`file`	`objeto`	Un objeto que contiene la configuración específica del tipo. La clave del objeto es `externa` para los `archivos` externos, y archivo para los archivos alojados en Notion.Consulta las secciones de tipo que aparecen a continuación para obtener más detalles sobre los valores específicos de cada tipo.