Twenty fue creado para ser amigable con los desarrolladores, ofreciendo APIs potentes que se adaptan a tu modelo de datos personalizado. Proveemos cuatro tipos de API distintos para satisfacer diferentes necesidades de integración.
Enfoque centrado en el desarrollador
Twenty genera APIs específicamente para tu modelo de datos:
- No se requieren IDs largos: Usa los nombres de tus objetos y campos directamente en los endpoints.
- Objetos estándar y personalizados tratados por igual: Tus objetos personalizados reciben el mismo tratamiento de API que los incorporados.
- Endpoints dedicados: Cada objeto y campo recibe su propio endpoint de API.
- Documentación personalizada: Generada específicamente para el modelo de datos de tu espacio de trabajo.
Tu documentación personalizada de la API está disponible en Configuración → API & Webhooks después de crear una clave de API. Como Twenty genera APIs que coinciden con tu modelo de datos personalizado, la documentación es única para tu espacio de trabajo.
Los dos tipos de API
API Principal
Accesible en /rest/ o /graphql/
Trabaja con tus registros reales (los datos):
- Crear, leer, actualizar y eliminar Personas, Empresas, Oportunidades, etc.
- Consultar y filtrar datos
- Gestionar relaciones de registros
Accesible en /rest/metadata/ o /metadata/
Administra tu espacio de trabajo y modelo de datos:
- Crear, modificar o eliminar objetos y campos
- Configurar ajustes del espacio de trabajo
- Define relaciones entre objetos
REST vs GraphQL
Tanto las API Core como las de Metadatos están disponibles en formatos REST y GraphQL:
| Formato | Operaciones disponibles |
|---|
| REST | CRUD, operaciones por lotes, upserts |
| GraphQL | Lo mismo + upserts por lotes, consultas de relaciones en una sola llamada |
Puntos de Acceso de API
| Entorno | URL base |
|---|
| Nube | https://api.twenty.com/ |
| Autoalojamiento | https://{your-domain}/ |
Autenticación
Cada solicitud a la API requiere una clave de API en el encabezado:
Authorization: Bearer YOUR_API_KEY
Crear una Clave de API
- Ve a Configuración → APIs y Webhooks
- Haz clic en + Crear clave
- Configurar:
- Nombre: Nombre descriptivo para la clave
- Fecha de vencimiento: Cuándo expira la clave
- Haga clic en Guardar
- Copia de inmediato — la clave solo se muestra una vez
Tu clave de API concede acceso a datos sensibles. No la compartas con servicios no confiables. Si se ve comprometida, desactívala de inmediato y genera una nueva.
Asignar un rol a una clave de API
Para mayor seguridad, asigna un rol específico para limitar el acceso:
- Ve a Configuración → Roles
- Haz clic en el rol que deseas asignar
- Abre la pestaña Asignación
- En Claves de API, haz clic en + Asignar a clave de API
- Selecciona la clave de API
La clave heredará los permisos de ese rol. Consulta Permisos para más detalles.
Gestionar Claves de API
Regenerar: Configuración → APIs & Webhooks → Haz clic en la clave → Regenerar
Eliminar: Configuración → APIs & Webhooks → Haz clic en la clave → Eliminar
Playground de la API
Prueba tus API directamente en el navegador con nuestro playground integrado — disponible tanto para REST como para GraphQL.
Accede al Playground
- Ve a Configuración → APIs y Webhooks
- Crea una clave de API (obligatorio)
- Haz clic en REST API o GraphQL API para abrir el playground
Lo que obtienes
- Documentación interactiva: Generada para tu modelo de datos específico
- Pruebas en vivo: Ejecuta llamadas reales a la API en tu espacio de trabajo
- Explorador de esquemas: Navega por los objetos, campos y relaciones disponibles
- Constructor de solicitudes: Crea consultas con autocompletado
El playground refleja tus objetos y campos personalizados, por lo que la documentación siempre es precisa para tu espacio de trabajo.
Operaciones por Lotes
Tanto REST como GraphQL admiten operaciones por lotes:
- Tamaño del lote: Hasta 60 registros por solicitud
- Operaciones: Crear, actualizar y eliminar múltiples registros
Características exclusivas de GraphQL:
- Upsert por lotes: Crear o actualizar en una llamada
- Usa nombres de objetos en plural (por ejemplo,
CreateCompanies en lugar de CreateCompany)
Límites de tasa
Las solicitudes a la API se limitan para garantizar la estabilidad de la plataforma:
| Límite | Valor |
|---|
| Solicitudes | 100 solicitudes por minuto |
| Tamaño del lote | 60 registros por llamada |
Usa operaciones por lotes para maximizar el rendimiento — procesa hasta 60 registros en una sola llamada a la API en lugar de hacer solicitudes individuales.
