Visão Geral
A API de Importação NovaGestão segue um fluxo de três etapas projetado para segurança e confiabilidade:
Etapa 1: Validação Dry Run
Sempre valide seus dados antes de importar. O dry run realiza validação completa sem criar registros.
Por que Dry Run?
Identifique erros de validação, associações ausentes e problemas de formato de dados
antes do processamento.
Veja exatamente quais registros serão bem-sucedidos e quais falharão, com feedback
detalhado.
Nenhum registro é criado, nenhuma alteração no banco de dados é feita. Teste quantas vezes
for necessário.
Exemplo de Dry Run
mutation DryRunImport($data: [JSON!]!, $entityType: ImportEntityType!) {
importCreate(input: {
data: $data
entityType: $entityType
dryRun: true
}) {
success
previewData
validRecords
invalidRecords
warnings
}
}
Formato de Resposta
{
"data": {
"importCreate": {
"success": true,
"validRecords": 8,
"invalidRecords": 2,
"previewData": [
{
"transaction_date": "2025-10-01",
"amount": "150.00",
"_feedback": {
"status": "valid",
"errors": []
}
},
{
"transaction_date": "2025-10-02",
"amount": "",
"_feedback": {
"status": "invalid",
"errors": ["Amount can't be blank"]
}
}
],
"warnings": [
"Categoria 'Material de Escritório' não encontrada, será criada automaticamente"
]
}
}
}
Cada linha em previewData inclui um objeto _feedback com resultados de validação
e erros.
Etapa 2: Criar Importação
Uma vez que a validação passe, crie a importação real. Isso enfileira um job em segundo plano para processar seus dados.
Exemplo de Criar Importação
mutation CreateImport($data: [JSON!]!, $entityType: ImportEntityType!) {
importCreate(input: {
data: $data
entityType: $entityType
dryRun: false
}) {
success
import {
id
status
entityType
recordsTotal
recordsProcessed
recordsCreated
recordsFailed
progress
}
errors {
code
message
}
}
}
Formato de Resposta
{
"data": {
"importCreate": {
"success": true,
"import": {
"id": "uuid-da-importacao",
"status": "pending",
"entityType": "TRANSACTION",
"recordsTotal": 10,
"recordsProcessed": 0,
"recordsCreated": 0,
"recordsFailed": 0,
"progress": 0
},
"errors": []
}
}
}
Etapa 3: Consultar Status
Monitore o progresso da importação até a conclusão.
Exemplo de Consulta de Status
query GetImport($id: ID!) {
import(id: $id) {
id
status
progress
recordsTotal
recordsProcessed
recordsCreated
recordsFailed
errorMessage
}
}
Estados de Importação
| Estado | Descrição |
|---|
pending | Aguardando processamento |
processing | Processando registros |
completed | Concluída com sucesso |
failed | Falhou (erro fatal) |
Importações processam de forma assíncrona. Consulte o status a cada 2-5 segundos até que
status seja completed ou failed.
Exemplo Completo em JavaScript
async function importarDados(dados, tipoEntidade) {
const endpoint = 'https://api.novagestao.xyz/graphql';
const headers = {
'Content-Type': 'application/json',
'Authorization': `Bearer ${API_KEY}`,
'X-ORGANIZATION-SLUG': ORG_SLUG,
};
// Etapa 1: Validar
console.log('Validando dados...');
const validacao = await validarDados(dados, tipoEntidade, endpoint, headers);
if (!validacao) {
console.error('❌ Validação falhou');
return;
}
// Etapa 2: Criar importação
console.log('Criando importação...');
const importacao = await criarImportacao(dados, tipoEntidade, endpoint, headers);
// Etapa 3: Consultar status
console.log('Consultando status...');
const concluida = await consultarStatus(importacao.id, endpoint, headers);
if (concluida.recordsFailed > 0) {
console.log(`⚠️ Importação concluída com ${concluida.recordsFailed} falhas`);
} else {
console.log('✓ Todos os registros importados com sucesso!');
}
}
async function consultarStatus(importId, endpoint, headers) {
let status = 'pending';
while (status === 'pending' || status === 'processing') {
await sleep(2000);
const response = await fetch(endpoint, {
method: 'POST',
headers,
body: JSON.stringify({
query: `
query GetImport($id: ID!) {
import(id: $id) {
status
progress
recordsTotal
recordsProcessed
recordsFailed
}
}
`,
variables: { id: importId },
}),
});
const result = await response.json();
const importData = result.data.import;
status = importData.status;
console.log(
`Status: ${status} (${importData.progress}% - ` +
`${importData.recordsProcessed}/${importData.recordsTotal})`
);
}
return result.data.import;
}
Melhores Práticas
Sempre Use Dry Run Primeiro
Valide dados antes de importar para evitar surpresas e desperdício de processamento.
Implemente Backoff Exponencial
Ao consultar status, aumente gradualmente o intervalo entre consultas (1s, 2s, 4s, 8s…).
Agrupe Registros em Lotes
Para melhores resultados, mantenha importações abaixo de 1000 registros por vez.
Algumas importações podem ter sucesso parcial. Sempre verifique recordsFailed.
Próximos Passos
