Resumen
Twenty ofrece tanto GraphQL como API REST para la importación programática de datos. Utiliza la API cuando la importación mediante CSV no sea práctica para tu volumen de datos o cuando necesites importaciones automatizadas y recurrentes.Cuándo usar la importación mediante API
| Escenario | Método recomendado |
|---|---|
| Menos de 10.000 registros | Importación CSV |
| 10.000 - 50.000 registros | Importación CSV (dividida en archivos) |
| 50.000+ registros | Importación mediante API |
| Migración de una sola vez | Cualquiera (según el volumen) |
| Importaciones recurrentes | Importación mediante API |
| Sincronización en tiempo real | Importación mediante API |
| Integración con otros sistemas | Importación mediante API |
Para conjuntos de datos de cientos de miles, la API es significativamente más rápida y más fiable que múltiples importaciones CSV.
Límites de tasa de la API
Twenty aplica límites de tasa para garantizar la estabilidad del sistema:| Límite | Valor |
|---|---|
| Solicitudes por minuto | 100 |
| Registros por llamada en lote | 60 |
| Rendimiento máximo | ~6.000 registros/minuto |
Primeros pasos
Paso 1: Obtén tu clave de API
- Ve a Configuración → Desarrolladores
- Haz clic en + Crear clave de API
- Dale un nombre descriptivo a tu clave de API
- Copia la clave de API inmediatamente (no se mostrará de nuevo)
- Guárdala de forma segura
Paso 2: Elige tu API
Twenty admite dos tipos de API:| API | Ideal para | Documentación |
|---|---|---|
| GraphQL | Consultas flexibles, obtención de datos relacionados, operaciones complejas | Documentación de la API |
| REST | Operaciones CRUD simples, patrones REST familiares | Documentación de la API |
- Crear, leer, actualizar y eliminar registros
- Operaciones por lotes — crear o actualizar hasta 60 registros por llamada
Paso 3: Planifica el orden de importación
Al igual que en las importaciones CSV, el orden importa para las relaciones:- Empresas primero (sin dependencias)
- Personas en segundo lugar (pueden vincularse a Empresas)
- Oportunidades en tercer lugar (pueden vincularse a Empresas y Personas)
- Tareas/Notas (pueden vincularse a cualquiera de las anteriores)
- Objetos personalizados (siguiendo sus dependencias)
Mejores prácticas
Agrupa tus solicitudes
- No envíes los registros de uno en uno
- Agrupa hasta 60 registros por llamada a la API
- Esto maximiza el rendimiento dentro de los límites de tasa
Gestiona los límites de tasa
- Implementa retardos entre solicitudes (600 ms como mínimo para importaciones sostenidas)
- Usa backoff exponencial cuando alcances los límites
- Supervisa las respuestas 429 (Too Many Requests)
Valida los datos primero
- Limpia y valida tus datos antes de importar
- Comprueba que los campos obligatorios estén completos
- Verifica que los formatos cumplan los requisitos de Twenty (consulta Asignación de campos)
Registra todo
- Registra cada registro importado (incluidos los ID)
- Registra los errores con todo el contexto
- Esto ayuda a depurar problemas y verificar la finalización
Prueba primero
- Prueba con un lote pequeño (10-20 registros)
- Verifica que los datos aparezcan correctamente en Twenty
- Luego ejecuta la importación completa
Upsert para evitar duplicados
La API de GraphQL admite upsert por lotes — actualizar si el registro existe, crear si no. Esto evita duplicados al volver a ejecutar importaciones.Encontrar nombres de objetos y campos
Para ver los objetos y campos disponibles:- Ve a Configuración → API y Webhooks
- Explora la Metadata API
- Visualiza todos los objetos estándar y personalizados con sus campos
Servicios profesionales
Para migraciones complejas mediante API, nuestros socios pueden ayudar:| Servicio | Qué incluye |
|---|---|
| Diseño del modelo de datos | diseñar tu estructura de datos óptima |
| Scripts de migración | escribir y ejecutar los scripts de importación |
| Transformación de datos | gestionar asignaciones complejas y limpieza |
| Validación y control de calidad | verificar que la migración esté completa |
- Migraciones de más de 100.000 registros
- Transformaciones de datos complejas
- Plazos ajustados
- Equipos sin recursos de desarrollo
Preguntas frecuentes
¿Cuál es la diferencia entre GraphQL y REST?
¿Cuál es la diferencia entre GraphQL y REST?
GraphQL te permite solicitar exactamente los datos que necesitas en una sola consulta y es mejor para operaciones complejas. REST utiliza métodos HTTP estándar (GET, POST, PUT, DELETE) y puede resultarte más familiar si has trabajado con APIs tradicionales.
¿Puedo actualizar registros existentes mediante la API?
¿Puedo actualizar registros existentes mediante la API?
¡Sí! Usa mutaciones de actualización (GraphQL) o solicitudes PUT/PATCH (REST) con el
id del registro.¿Cómo gestiono los duplicados?
¿Cómo gestiono los duplicados?
Consulta primero si existen registros utilizando identificadores únicos (email, dominio). Actualiza si existe, crea si no.
¿Puedo eliminar registros mediante la API?
¿Puedo eliminar registros mediante la API?
Sí, usa mutaciones de eliminación (GraphQL) o solicitudes DELETE (REST).
¿Hay un SDK para Python o Node.js?
¿Hay un SDK para Python o Node.js?
Por el momento no, pero ambas APIs funcionan con cualquier cliente HTTP en cualquier lenguaje.