Tipo de Entidade
Campos Obrigatórios
| Campo | Tipo | Descrição | Exemplo |
|---|
name | String | Nome da conta | "Conta Corrente - Itaú" |
account_type | String | Tipo de conta | "checking", "savings", "investment" |
Campos Opcionais
| Campo | Tipo | Descrição | Exemplo |
|---|
currency | String | Código da moeda (ISO 4217) | "BRL", "USD" |
initial_balance | Decimal | Saldo inicial | "10000.00" |
bank_name | String | Nome do banco | "Banco Itaú" |
bank_code | String | Código do banco | "341" |
agency | String | Número da agência | "1234" |
account_number | String | Número da conta | "56789-0" |
Tipos de Conta
| Tipo | Descrição |
|---|
checking | Conta corrente |
savings | Conta poupança |
investment | Conta de investimento |
credit_card | Cartã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