Skip to main content

​
Visão Geral

A API de Importação NovaGestão usa autenticação baseada em chave de API com esquema Bearer token. Todas as requisições devem incluir sua chave de API no cabeçalho Authorization.

​
Gerando uma Chave de API

1

Navegue para Configurações

Vá para Configurações → Chaves de API no painel da sua organização
2

Criar Nova Chave

Clique em “Gerar Nova Chave”
3

Configurar Chave

  • Nome: Nome descritivo (ex: “Serviço de Importação de Produção”)
  • Escopo: Escolha read_write (necessário para importações)
  • Expiração: Opcional (recomendado: 90 dias)
4

Copiar Token

Copie o token imediatamente - ele não será mostrado novamente!
Armazene sua chave de API com segurança. Nunca a commit em controle de versão ou compartilhe em chat/email.

​
Fazendo Requisições Autenticadas

​
Cabeçalhos Obrigatórios

Todas as requisições à API devem incluir estes cabeçalhos: 
Authorization: Bearer SUA_CHAVE_API_DE_64_CARACTERES
X-ORGANIZATION-SLUG: slug-da-sua-organizacao
Content-Type: application/json

​
Cabeçalhos Opcionais

X-COMPANY-SLUG: slug-da-sua-empresa
Use isso ao importar dados para uma empresa específica dentro de uma organização.

​
Exemplos de Código

const API_KEY = process.env.NOVAGESTAO_API_KEY;
const ORG_SLUG = 'acme';

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: `
      query ListarImportacoes {
        imports(page: 1, pageSize: 10) {
          edges {
            node {
              id
              entityType
              status
            }
          }
        }
      }
    `,
  }),
});

const data = await response.json();
console.log(data);

​
Limite de Taxa

A API impõe limites de taxa por chave de API:
Limite: 1000 requisições por hora por chave de API

​
Cabeçalhos de Resposta

Verifique estes cabeçalhos para monitorar seu uso: 
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1728409573

​
Tratando Limites de Taxa

const response = await fetch(url, options);

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'));
const reset = parseInt(response.headers.get('X-RateLimit-Reset'));

if (remaining < 10) {
  console.warn(`Apenas ${remaining} requisições restantes`);
}

if (response.status === 429) {
  const waitMs = (reset * 1000) - Date.now();
  console.log(`Limite de taxa atingido. Aguardando ${waitMs}ms...`);
  await sleep(waitMs);
  // Tentar novamente
}

​
Escopos de Chave de API

EscopoConsultasMutaçõesCaso de Uso
read_only✓ Permitido✗ BloqueadoDashboards somente leitura, relatórios
read_write✓ Permitido✓ PermitidoIntegração completa, importações
Para importações, você deve usar o escopo read_write.

​
Práticas Recomendadas de Segurança

  • Use variáveis de ambiente ou gerenciadores de segredos
  • Nunca faça hardcode de chaves de API em sua aplicação
  • Use chaves diferentes para desenvolvimento e produção
  • Rotacione chaves regularmente (ex: a cada 90 dias)
  • Defina expiração automática ao criar chaves
  • Revogue chaves quando não forem mais necessárias
  • Verifique os cabeçalhos de limite de taxa regularmente
  • Configure alertas para uso alto
  • Revise a atividade das chaves de API no painel
  • Use chaves diferentes para serviços diferentes
  • Facilita revogar chaves comprometidas
  • Fornece melhores trilhas de auditoria

​
Solução de Problemas

Causa: Cabeçalho X-ORGANIZATION-SLUG inválido ou ausenteSolução:
  • Verifique se o cabeçalho está definido corretamente
  • Verifique se seu usuário tem acesso à organização
  • Certifique-se de que o slug corresponde exatamente (sensível a maiúsculas)
Causa: O escopo da sua chave de API é read_onlySolução:
  • Gere uma nova chave com escopo read_write
  • Atualize sua aplicação para usar a nova chave
  • Revogue a antiga chave read_only
Causa: Você excedeu 1000 requisições por horaSolução:
  • Aguarde até o horário de reset (verifique o cabeçalho X-RateLimit-Reset)
  • Implemente backoff exponencial em seu código
  • Considere agrupar suas requisições em lotes

​
Próximos Passos

Início Rápido

Faça sua primeira importação em 5 minutos

Fluxo de Importação

Aprenda o processo completo de importação