Importar dados via API
Quando e como usar as APIs do Vecta Desk para importações de dados em larga escala.
Visão geral
O Vecta Desk 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 registros | Importação CSV |
| 10.000 a 50.000 registros | Importação CSV (dividida em arquivos) |
| Mais de 50.000 registros | 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 confiável do que múltiplas importações CSV.
Limites de taxa da API
O Vecta Desk impõe limites de taxa para assegurar a estabilidade do sistema:
| Limite | Valor |
|---|---|
| Requisições por minuto | 100 |
| Registros por chamada em lote | 60 |
| Taxa de transferência máxima | ~6.000 registros/minuto |
Planeje a sua importação em função destes limites. Para 100.000 registros à taxa de transferência máxima, conte com aproximadamente 17 minutos de tempo de importação. Adicione tempo de margem para tratamento de erros e novas tentativas.
Primeiros passos
Passo 1: Obtenha a sua chave de API
- Vá para Configurações → Desenvolvedores
- 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
Mantenha a sua chave de API em segredo. Qualquer pessoa com a sua chave de API pode acessar e modificar os dados do seu espaço de trabalho. Nunca a inclua em repositórios de código nem a partilhe publicamente.
Passo 2: Escolha a sua API
O Vecta Desk suporta dois tipos de API:
| API | Melhor para |
|---|---|
| GraphQL | Consultas flexíveis, obtenção de dados relacionados, operações complexas |
| REST | Operações CRUD simples, padrões REST familiares |
Ambas as APIs suportam:
- Criar, ler, atualizar e excluir registros
- Operações em lote — criar ou atualizar até 60 registros por chamada
Para importações, use operações em lote para maximizar a taxa de transferência dentro dos limites de taxa.
Passo 3: Planeje 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 registros um de cada vez
- Agrupe até 60 registros 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
- Monitore 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 do Vecta Desk (veja Mapeamento de campos)
Registre tudo
- Registre cada registro importado (incluindo IDs)
- Registre erros com todo o contexto
- Isto ajuda a depurar problemas e a verificar a conclusão
Teste primeiro
- Teste com um pequeno lote (10 a 20 registros)
- Verifique se os dados aparecem corretamente no Vecta Desk
- Depois, execute a importação completa
Upsert para evitar duplicados
A API GraphQL suporta upsert em lote — atualize se o registro existir, crie se não existir. Isto evita duplicados ao reexecutar 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
A documentação mostra todos os objetos padrão e personalizados, os seus campos e os tipos de dados esperados.
Perguntas frequentes
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 registros existentes via API?
Sim. Utilize mutations de atualização (GraphQL) ou pedidos PUT/PATCH (REST) com o id do registro.
Como devo lidar com duplicados?
Pesquise primeiro por registros existentes usando identificadores únicos (e-mail, domínio). Atualize se existir, crie se não existir.
Posso excluir registros via API?
Sim, utilize mutations de exclusão (GraphQL) ou pedidos DELETE (REST).
Existe um SDK para Python ou Node.js?
De momento não, mas ambas as APIs funcionam com qualquer cliente HTTP em qualquer linguagem.