Visão Geral
A Twenty oferece tanto GraphQL como APIs REST para a importação programática de dados. Use a API quando a importação por CSV não for prática para o seu volume de dados ou quando precisar de importações automatizadas e recorrentes.Quando usar a importação via API
| Cenário | Método recomendado |
|---|---|
| Menos de 10 000 registos | Importação CSV |
| 10 000 - 50 000 registos | Importação CSV (dividida em ficheiros) |
| Mais de 50 000 registos | Importação via API |
| Migração única | Qualquer um dos dois (com base no volume) |
| Importações recorrentes | Importação via API |
| Sincronização em tempo real | Importação via API |
| Integração com outros sistemas | Importação via API |
Para conjuntos de dados na casa das centenas de milhares, a API é significativamente mais rápida e mais fiável do que múltiplas importações CSV.
Limites de taxa da API
A Twenty impõe limites de taxa para assegurar a estabilidade do sistema:| Limite | Valor |
|---|---|
| Pedidos por minuto | 100 |
| Registos por chamada em lote | 60 |
| Taxa de transferência máxima | ~6 000 registos/minuto |
Primeiros passos
Passo 1: Obtenha a sua chave de API
- Vá para Configurações → Programadores
- Clique em + Criar chave de API
- Dê à sua chave um nome descritivo
- Copie imediatamente a chave de API (não será mostrada novamente)
- Guarde-a em segurança
Passo 2: Escolha a sua API
A Twenty suporta dois tipos de API:| API | Melhor para | Documentação |
|---|---|---|
| GraphQL | Consultas flexíveis, obtenção de dados relacionados, operações complexas | Documentação da API |
| REST | Operações CRUD simples, padrões REST familiares | Documentação da API |
- Criar, ler, atualizar e eliminar registos
- Operações em lote — criar ou atualizar até 60 registos por chamada
Passo 3: Planeie a ordem da importação
Tal como nas importações por CSV, a ordem importa para as relações:- Empresas primeiro (sem dependências)
- Pessoas em segundo (podem ligar-se a Empresas)
- Oportunidades em terceiro (podem ligar-se a Empresas e Pessoas)
- Tarefas/Notas (podem ligar-se a qualquer um dos anteriores)
- Objetos personalizados (seguindo as suas dependências)
Melhores Práticas
Agrupe os seus pedidos
- Não envie registos um de cada vez
- Agrupe até 60 registos por chamada de API
- Isto maximiza a taxa de transferência dentro dos limites de taxa
Lide com os limites de taxa
- Implemente atrasos entre pedidos (mínimo de 600 ms para importações contínuas)
- Use backoff exponencial quando atingir os limites
- Monitorize respostas 429 (Too Many Requests)
Valide os dados primeiro
- Limpe e valide os seus dados antes de importar
- Verifique se os campos obrigatórios estão preenchidos
- Verifique se os formatos correspondem aos requisitos da Twenty (veja Mapeamento de Campos)
Registe tudo
- Registe cada registo importado (incluindo IDs)
- Registe erros com todo o contexto
- Isto ajuda a depurar problemas e a verificar a conclusão
Teste primeiro
- Teste com um pequeno lote (10-20 registos)
- Verifique se os dados aparecem corretamente na Twenty
- Depois, execute a importação completa
Upsert para evitar duplicados
A API GraphQL suporta upsert em lote — atualize se o registo existir, crie se não existir. Isto evita duplicados ao voltar a executar importações.Encontrar nomes de objetos e campos
Para ver os objetos e campos disponíveis:- Vá para Configurações → API e Webhooks
- Explore a API de Metadados
- Veja todos os objetos padrão e personalizados com os seus campos
Serviços Profissionais
Para migrações de API complexas, os nossos parceiros podem ajudar:| Serviço | O que está incluído |
|---|---|
| Conceção do Modelo de Dados | conceber a sua estrutura de dados ideal |
| Scripts de migração | escrever e executar os scripts de importação |
| Transformação de dados | tratar de mapeamentos complexos e limpeza |
| Validação e Garantia de Qualidade | verificar que a migração está concluída |
- Migrações de mais de 100 000 registos
- Transformações de dados complexas
- Prazos apertados
- Equipas sem recursos de programadores
Perguntas Frequentes
Qual é a diferença entre GraphQL e REST?
Qual é a diferença entre GraphQL e REST?
O GraphQL permite solicitar exatamente os dados de que precisa numa única consulta e é melhor para operações complexas. O REST utiliza métodos HTTP padrão (GET, POST, PUT, DELETE) e pode ser mais familiar se já trabalhou com APIs tradicionais.
Posso atualizar registos existentes via API?
Posso atualizar registos existentes via API?
Sim! Utilize mutations de atualização (GraphQL) ou pedidos PUT/PATCH (REST) com o
id do registo.Como devo lidar com duplicados?
Como devo lidar com duplicados?
Pesquise primeiro por registos existentes usando identificadores únicos (email, domínio). Atualize se existir, crie se não existir.
Posso eliminar registos via API?
Posso eliminar registos via API?
Sim, utilize mutations de eliminação (GraphQL) ou pedidos DELETE (REST).
Existe um SDK para Python ou Node.js?
Existe um SDK para Python ou Node.js?
De momento não, mas ambas as APIs funcionam com qualquer cliente HTTP em qualquer linguagem.