Skip to main content

​
Tipo de Entidade

entityType: TRANSACTION

​
Campos Obrigatórios

CampoTipoDescriçãoExemplo
amountDecimalValor da transação150.00 ou -75.50
descriptionStringDescrição da transação"Pagamento a fornecedor"
transaction_dateDateData da transação"2025-10-01"
external_id OU reference_numberStringIdentificador único"TXN-001"
Parâmetro Obrigatório:
  • accountId (ID) - UUID da conta bancária

​
Campos Opcionais

CampoTipoDescrição
category_nameStringBusca de categoria por nome
cost_center_nameStringBusca de centro de custo por nome

​
Convenção de Valores

  • Valores positivos: Dinheiro saindo (despesas, pagamentos)
  • Valores negativos: Dinheiro entrando (receitas, recebimentos)

​
Exemplo: Transação Básica

{
  "transaction_date": "2025-10-01",
  "amount": "150.00",
  "description": "Pagamento a fornecedor XYZ",
  "external_id": "TXN-001"
}

​
Exemplo: Com Categoria e Centro de Custo

{
  "transaction_date": "2025-10-03",
  "amount": "850.50",
  "description": "Compra de material de escritório",
  "reference_number": "REF-12345",
  "category_name": "Despesas de Escritório",
  "cost_center_name": "Administração"
}

​
Mutação GraphQL

​
Validação (Dry Run)

mutation ValidarTransacoes {
  importCreate(
    input: {
      data: [
        {
          transaction_date: "2025-10-01"
          amount: "150.00"
          description: "Pagamento a fornecedor"
          external_id: "TXN-001"
        }
      ]
      entityType: TRANSACTION
      accountId: "uuid-da-sua-conta"
      dryRun: true
    }
  ) {
    success
    previewData
    validRecords
    invalidRecords
  }
}

​
Importação Real

mutation ImportarTransacoes {
  importCreate(
    input: {
      data: [
        {
          transaction_date: "2025-10-01"
          amount: "150.00"
          description: "Pagamento a fornecedor"
          external_id: "TXN-001"
        }
      ]
      entityType: TRANSACTION
      accountId: "uuid-da-sua-conta"
      dryRun: false
    }
  ) {
    success
    import {
      id
      status
      recordsTotal
    }
  }
}

​
Exemplo em JavaScript

const API_KEY = process.env.NOVAGESTAO_API_KEY;
const ORG_SLUG = "sua-organizacao";

async function importarTransacoes(accountId) {
  const transacoes = [
    {
      transaction_date: "2025-10-01",
      amount: "150.00",
      description: "Pagamento a fornecedor",
      external_id: "TXN-001",
    },
  ];

  // Passo 1: Validação (dry run)
  const validacao = await fetch("https://api.novagestao.xyz/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
      "X-ORGANIZATION-SLUG": ORG_SLUG,
    },
    body: JSON.stringify({
      query: `
        mutation ValidarTransacoes($data: [JSON!]!, $accountId: ID!) {
          importCreate(input: {
            data: $data
            entityType: TRANSACTION
            accountId: $accountId
            dryRun: true
          }) {
            success
            validRecords
            invalidRecords
          }
        }
      `,
      variables: { data: transacoes, accountId },
    }),
  });

  const resultado = await validacao.json();

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

  console.log(
    ` Validadas ${resultado.data.importCreate.validRecords} transações`
  );

  // Passo 2: Criar importação real
  const importResponse = await fetch("https://api.novagestao.xyz/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${API_KEY}`,
      "X-ORGANIZATION-SLUG": ORG_SLUG,
    },
    body: JSON.stringify({
      query: `
        mutation ImportarTransacoes($data: [JSON!]!, $accountId: ID!) {
          importCreate(input: {
            data: $data
            entityType: TRANSACTION
            accountId: $accountId
            dryRun: false
          }) {
            success
            import { id status }
          }
        }
      `,
      variables: { data: transacoes, accountId },
    }),
  });

  const resultadoImport = await importResponse.json();
  console.log(
    `Importação criada: ${resultadoImport.data.importCreate.import.id}`
  );
}

​
Erros Comuns

“Account is required for transaction imports”Parâmetro accountId ausente. Forneça-o nos argumentos da mutação, não no array de dados.
“Amount can’t be blank”Toda transação deve ter um campo amount válido.

​
Melhores Práticas

Sempre use dry run primeiro para validar os dados antes de criar importações reais.
Inclua external_id para habilitar reconciliação e prevenir duplicatas.
Tamanho do lote: Mantenha abaixo de 1000 transações por importação para desempenho ideal.

​
Entidades Relacionadas