Skip to main content

Tipo de Entidade

entityType: ACCOUNT

Campos Obrigatórios

CampoTipoDescriçãoExemplo
nameStringNome da conta"Conta Corrente - Itaú"
account_typeStringTipo de conta"checking", "savings", "investment"

Campos Opcionais

CampoTipoDescriçãoExemplo
currencyStringCódigo da moeda (ISO 4217)"BRL", "USD"
initial_balanceDecimalSaldo inicial"10000.00"
bank_nameStringNome do banco"Banco Itaú"
bank_codeStringCódigo do banco"341"
agencyStringNúmero da agência"1234"
account_numberStringNúmero da conta"56789-0"

Tipos de Conta

TipoDescrição
checkingConta corrente
savingsConta poupança
investmentConta de investimento
credit_cardCartão de crédito

Exemplo: Conta Básica

{
  "name": "Conta Corrente - Itaú",
  "account_type": "checking"
}

Exemplo: Conta Completa

{
  "name": "Conta Corrente Empresarial - Itaú",
  "account_type": "checking",
  "currency": "BRL",
  "initial_balance": "25000.00",
  "bank_name": "Banco Itaú",
  "bank_code": "341",
  "agency": "1234",
  "account_number": "56789-0"
}

Mutação GraphQL

Validação (Dry Run)

mutation ValidarContas {
  importCreate(
    input: {
      data: [
        {
          name: "Conta Corrente - Itaú"
          account_type: "checking"
          currency: "BRL"
          initial_balance: "25000.00"
        }
      ]
      entityType: ACCOUNT
      dryRun: true
    }
  ) {
    success
    previewData
    validRecords
    invalidRecords
  }
}

Importação Real

mutation ImportarContas {
  importCreate(
    input: {
      data: [
        {
          name: "Conta Corrente - Itaú"
          account_type: "checking"
          currency: "BRL"
          initial_balance: "25000.00"
        }
      ]
      entityType: ACCOUNT
      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 importarContas() {
  const contas = [
    {
      name: "Conta Corrente - Itaú",
      account_type: "checking",
      currency: "BRL",
      initial_balance: "25000.00",
      bank_name: "Banco Itaú",
      bank_code: "341",
    },
  ];

  const response = 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 ImportarContas($data: [JSON!]!) {
          importCreate(input: {
            data: $data
            entityType: ACCOUNT
            dryRun: false
          }) {
            success
            import { id status }
          }
        }
      `,
      variables: { data: contas },
    }),
  });

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

Regras de Validação

Detecção de Duplicatas: Contas com o mesmo name dentro de uma organização irão atualizar a conta existente ao invés de criar uma nova.
Nome da conta deve ser único dentro da sua organização.

Erros Comuns

“Name has already been taken”Uma conta com este nome já existe. Use um nome diferente ou atualize a conta existente.
“Account type is not valid”Deve ser um dos seguintes: checking, savings, investment, credit_card.

Melhores Práticas

Use nomes descritivos que incluam o nome do banco e o tipo de conta.
Configure initial_balance ao importar contas que já possuem transações.
Inclua detalhes do banco (bank_code, agency, account_number) para melhor reconciliação.

Entidades Relacionadas