Skip to main content

​
Visão Geral

Este guia mostra como criar sua primeira importação usando a API de Importação NovaGestão.
1

Gerar Chave de API

  1. Vá para Configurações → Chaves de API no seu painel
  2. Clique em “Gerar Nova Chave”
  3. Nome: "Integração de Importação"
  4. Escopo: read_write
  5. Copie o token (mostrado apenas uma vez!)
2

Testar Autenticação

Verifique se sua chave de API funciona com uma consulta simples:
query TestarAuth {
  imports(page: 1, pageSize: 10) {
    edges {
      node {
        id
        entityType
        status
      }
    }
  }
}
Use o painel Experimente para testar esta consulta com sua chave de API.
3

Validar Dados (Dry Run)

Sempre valide seus dados antes de importar:
mutation DryRunImport {
  importCreate(input: {
    data: [
      {
        transaction_date: "2025-10-01"
        amount: "150.00"
        description: "Transação de teste"
        external_id: "TEST-001"
      }
    ]
    entityType: TRANSACTION
    accountId: "uuid-da-sua-conta"
    dryRun: true
  }) {
    success
    previewData
    validRecords
    invalidRecords
    warnings
  }
}
Dry run valida seus dados sem criar nenhum registro. Sempre use isso antes da importação real!
4

Criar Importação

Uma vez que a validação passe, crie a importação real:
mutation CriarImportacao {
  importCreate(input: {
    data: [
      {
        transaction_date: "2025-10-01"
        amount: "150.00"
        description: "Transação de teste"
        external_id: "TEST-001"
      }
    ]
    entityType: TRANSACTION
    accountId: "uuid-da-sua-conta"
    dryRun: false
  }) {
    success
    import {
      id
      status
      recordsTotal
    }
  }
}
5

Monitorar Status da Importação

Monitore a importação até que seja concluída:
query ObterStatusImportacao($id: ID!) {
  import(id: $id) {
    id
    status
    progress
    recordsTotal
    recordsProcessed
    recordsCreated
    recordsFailed
  }
}
Importações processam de forma assíncrona. Consulte o status a cada 2-5 segundos até que status seja completed ou failed.

​
Exemplo de Código Completo

Aqui está um exemplo funcional completo em JavaScript: 
const API_KEY = process.env.NOVAGESTAO_API_KEY;
const ORG_SLUG = 'slug-da-sua-org';
const ACCOUNT_ID = 'uuid-da-sua-conta';

async function criarPrimeiraImportacao() {
  const endpoint = 'https://api.novagestao.xyz/graphql';
  const headers = {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`,
    'X-ORGANIZATION-SLUG': ORG_SLUG,
  };

  // Passo 1: Validação dry run
  const dryRunResponse = await fetch(endpoint, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      query: `
        mutation DryRunImport($data: [JSON!]!, $accountId: ID!) {
          importCreate(input: {
            data: $data
            entityType: TRANSACTION
            accountId: $accountId
            dryRun: true
          }) {
            success
            validRecords
            invalidRecords
            warnings
          }
        }
      `,
      variables: {
        data: [{
          transaction_date: '2025-10-01',
          amount: '150.00',
          description: 'Transação de teste',
          external_id: 'TEST-001',
        }],
        accountId: ACCOUNT_ID,
      },
    }),
  });

  const dryRun = await dryRunResponse.json();

  if (dryRun.data.importCreate.invalidRecords > 0) {
    console.error('❌ Validação falhou');
    return;
  }

  console.log('✓ Validação aprovada');

  // Passo 2: Criar importação real
  const importResponse = await fetch(endpoint, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      query: `
        mutation CreateImport($data: [JSON!]!, $accountId: ID!) {
          importCreate(input: {
            data: $data
            entityType: TRANSACTION
            accountId: $accountId
            dryRun: false
          }) {
            success
            import {
              id
              status
            }
          }
        }
      `,
      variables: {
        data: [{
          transaction_date: '2025-10-01',
          amount: '150.00',
          description: 'Transação de teste',
          external_id: 'TEST-001',
        }],
        accountId: ACCOUNT_ID,
      },
    }),
  });

  const importResult = await importResponse.json();
  const importId = importResult.data.importCreate.import.id;

  console.log(`✓ Importação criada: ${importId}`);

  // Passo 3: Consultar até conclusão
  let status = 'pending';
  while (status === 'pending' || status === 'processing') {
    await sleep(2000); // Aguardar 2 segundos

    const statusResponse = await fetch(endpoint, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        query: `
          query GetImport($id: ID!) {
            import(id: $id) {
              status
              progress
              recordsCreated
              recordsFailed
            }
          }
        `,
        variables: { id: importId },
      }),
    });

    const statusResult = await statusResponse.json();
    const importData = statusResult.data.import;
    status = importData.status;

    console.log(`Status: ${status} (${importData.progress}%)`);
  }

  console.log('✓ Importação concluída!');
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

// Executar
criarPrimeiraImportacao();

​
Próximos Passos

Fluxo de Importação

Aprenda o processo completo de importação em detalhes

Tipos de Entidade

Explore todos os 12 tipos de entidades suportados

Tratamento de Erros

Trate erros de forma elegante em sua integração

Solução de Problemas

Problemas comuns e soluções