Skip to content

The open alternative to Salesforce, designed for AI.

3.9 KB
Raw Blame
---
title: APIs
sidebarTitle: Resumen
description: APIs REST y GraphQL generadas a partir del esquema de tu espacio de trabajo.
---

import { PageBanner } from "/snippets/page-banner.mdx"
import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

## APIs con esquema por tenant

No existe una referencia estática de la API para Twenty. Cada espacio de trabajo tiene su propio esquema — cuando agregas un objeto personalizado (por ejemplo, `Invoice`), inmediatamente obtiene endpoints REST y GraphQL idénticos a los objetos integrados como `Company` o `Person`. La API se genera a partir del esquema, por lo que los endpoints usan directamente los nombres de tus objetos y campos — sin identificadores opacos.

La documentación de la API específica de tu espacio de trabajo está disponible en **Configuración → Desarrolladores → API** después de crear una clave de API. Incluye un entorno de pruebas interactivo donde puedes ejecutar llamadas reales contra tus datos.

## Dos APIs

**API principal** — `/rest/` y `/graphql/`

CRUD sobre registros: Personas, Empresas, Oportunidades y tus objetos personalizados. Consultar, filtrar, recorrer relaciones.

**API de metadatos** — `/rest/metadata/` y `/metadata/`

Gestión del esquema: crear/modificar/eliminar objetos, campos y relaciones. Así es como cambias tu modelo de datos de forma programática.

Ambas están disponibles como REST y GraphQL. GraphQL añade operaciones upsert por lotes y la capacidad de recorrer relaciones en una única consulta. Los mismos datos subyacentes en ambos casos.

## URLs base

| Entorno         | URL base                  |
| --------------- | ------------------------- |
| Nube            | `https://api.twenty.com/` |
| Autoalojamiento | `https://{your-domain}/`  |

## Autenticación

```
Authorization: Bearer YOUR_API_KEY
```

Crea una clave de API en **Configuración → Desarrolladores → API → + Crear clave**. Cópiala de inmediato — se muestra una sola vez. Las claves pueden acotarse a un rol específico en **Configuración → Members → Roles → Assignment tab** para limitar a qué pueden acceder.

<VimeoEmbed videoId="928786722" title="Creación de clave de API" />

Para el acceso basado en OAuth (aplicaciones externas que actúan en nombre de los usuarios), consulta [OAuth](/es/developers/extend/oauth).

## Operaciones por lotes

Tanto REST como GraphQL admiten el procesamiento por lotes de hasta 60 registros por solicitud — crear, actualizar o eliminar. GraphQL también admite upsert por lotes (crear o actualizar en una sola llamada) usando nombres en plural como `CreateCompanies`.

## Seleccionar campos (REST)

Los endpoints de registros REST aceptan un parámetro de consulta `fields` para devolver solo los campos que necesitas:

```
GET /rest/people?fields=id,name,emails,company
```

* Siempre se devuelve `id`.
* Los campos compuestos (como `emails` o `name`) se seleccionan en su totalidad mediante su nombre de campo.
* Un campo de relación de varios a uno devuelve su columna de unión (p. ej., `companyId`) con `depth=0`. Los campos de relación de uno a varios solo se devuelven con `depth=1`. Con `depth=1`, solo se expanden los campos de relación enumerados en `fields`.
* Los campos desconocidos, o los campos que tu rol no puede leer, devuelven un error `400`.

Cuando se omite `fields` en un objeto con más de 200 campos legibles, cada registro devuelve un conjunto predeterminado de 200 campos: `id`, los campos de identificador de etiqueta e imagen, `createdAt`, `updatedAt`, `deletedAt`, `position` y, a continuación, los campos estándar antes que los campos personalizados, ordenados por nombre. Pasa `fields` explícitamente para leer cualquier campo más allá de ese conjunto predeterminado.

## Límites de tasa

| Límite          | Valor                      |
| --------------- | -------------------------- |
| Solicitudes     | 100 solicitudes por minuto |
| Tamaño del lote | 60 registros por llamada   |

<PageBanner illustration="dev-api" />