API Pública GDASH: integração simples e segura com nossos serviços

Base URL: https://public-api.gdash.io/api/v1
Documentação interativa (Swagger): https://public-api.gdash.io/swagger
Autenticação: parâmetro apikey na query string de todas as requisições

Por que disponibilizamos uma API pública

Com o objetivo de facilitar integrações e ampliar as possibilidades de uso da plataforma, disponibilizamos uma API pública que permite que desenvolvedores e sistemas externos acessem nossos serviços de forma padronizada e segura.

Na prática, isso significa que os dados que você já acompanha no GDASH — usinas, clientes, unidades consumidoras, faturas de energia, cobranças, negociações e chamados — podem ser lidos e, em alguns casos, criados diretamente pelo seu próprio sistema, sem depender de exportações manuais ou de alguém abrindo a plataforma para copiar informação.

O que é uma API pública

Uma API pública é uma interface que permite que aplicações externas se comuniquem com um sistema de maneira estruturada. Ela possibilita que outras plataformas, softwares ou automações utilizem funcionalidades do nosso sistema sem precisar acessar diretamente a aplicação principal.

A disponibilização de uma API pública tem como principal objetivo permitir integrações mais flexíveis. Empresas e desenvolvedores podem automatizar processos, conectar diferentes sistemas e criar novas soluções utilizando os dados e recursos disponibilizados pela plataforma.

Além disso, a API pública também facilita a escalabilidade das integrações. Em vez de processos manuais ou importações de dados, sistemas podem se comunicar automaticamente, garantindo mais eficiência, consistência e rapidez nas operações.

O que dá para construir com ela

Alguns cenários que a API atende bem hoje:

Como começar a utilizar a API pública

Para acessar as rotas da API pública, é necessário possuir uma API Key, que funciona como uma chave de autenticação para identificar e autorizar as requisições feitas ao sistema. É ela que diz à API qual organização está fazendo a chamada — por isso, todos os dados retornados são sempre e exclusivamente os da sua organização.

O processo para gerar uma API Key é simples:

1. Acesse o menu Configurações da plataforma.

2. Entre na seção API Keys.

3. Clique na opção Chave de API habilitada

4. Após a criação, copie a Chave de API gerada.

⚠️ Trate a API Key como uma senha. Ela dá acesso de leitura e escrita aos dados da sua organização. Guarde-a em variáveis de ambiente ou em um cofre de segredos — nunca no código-fonte versionado, em repositórios públicos ou no front-end de uma aplicação web (onde qualquer visitante conseguiria lê-la). Se suspeitar que a chave vazou, desabilite e gere uma nova pela mesma tela.

Documentação da API

Para facilitar o uso da API pública, disponibilizamos a documentação por meio do Swagger. O Swagger permite visualizar todas as rotas disponíveis, entender quais parâmetros são necessários e até mesmo testar requisições diretamente pela interface.

Com ele, desenvolvedores conseguem explorar a API de forma mais prática, verificando exemplos de requisição, formatos de resposta e detalhes de cada endpoint.

A documentação completa da API pode ser acessada no link abaixo:

https://public-api.gdash.io/swagger

Após gerar sua API Key, basta acessar a documentação no Swagger, inserir a chave nas requisições e começar a utilizar as rotas da API pública para integrar sua aplicação.

💡 Dica: o Swagger é a fonte da verdade sempre atualizada. Este guia explica os conceitos e o comportamento da API; o Swagger reflete os campos exatos de cada versão em produção. Quando houver divergência, confie no Swagger.

Convenções gerais

Estas regras valem para todas as rotas da API.

Formato de resposta

Em caso de sucesso, a resposta segue o envelope abaixo. O conteúdo útil está sempre em data:

{
  "ok": true,
  "data": [
    { "id": "...", "name": "..." }
  ]
}

Nas rotas paginadas, o envelope também traz o cursor da próxima página:

{
  "ok": true,
  "data": [ ... ],
  "nextCursor": "2026-01-15T10:32:00.000Z"
}

Tratamento de erros

Quando algo dá errado, a API responde com o status HTTP apropriado e um corpo descritivo:

{
  "success": false,
  "status": 400,
  "error": "BadRequestException",
  "message": "Invalid key or organization not found",
  "path": "/api/v1/solar/customers?apikey=***",
  "data": []
}

💡 Boa prática: implemente retry apenas para erros 5xx. Erros 4xx indicam problema na requisição e vão falhar de novo do mesmo jeito.

Paginação por cursor

As rotas com maior volume de dados usam paginação por cursor em vez de paginação por número de página. O cursor é a **data de criação (created_at / createdAt) do último item recebido**: para buscar a próxima página, envie esse valor no parâmetro cursor.

Esse modelo é mais confiável que paginar por número de página porque não "pula" nem "repete" registros quando novos dados são inseridos durante a sua leitura — algo comum em bases que recebem faturas e cobranças o tempo todo.

Parâmetros:

Como saber que acabou:

• Em energy-billing, a resposta devolve nextCursor. Quando ele vier null, não há mais resultados.
• Nas demais rotas, continue paginando enquanto data.length === limit. Quando vier menos itens que o limit pedido, você chegou ao fim.

Associations: trazendo dados relacionados

Várias rotas aceitam o parâmetro opcional associations, que inclui na resposta os identificadores de entidades relacionadas. Os valores são separados por vírgula.

GET /solar/customers?apikey=SUA_API_KEY&associations=plant,consumer_unit,deal

Isso evita o clássico problema de fazer uma chamada para listar clientes e depois N chamadas para descobrir a quais usinas cada um pertence.

⚠️ Importante: associations retorna apenas os IDs das entidades relacionadas, não os objetos completos. Para obter os dados completos de um cliente a partir de um ID, use GET /solar/customers/search.

CRM

GET /crm/task — Tarefas do CRM

Retorna as tarefas (to-dos) registradas no CRM da organização. Útil para acompanhar pendências da equipe comercial ou operacional em painéis externos.

Query params: apikey (obrigatório), associations (opcional — aceita customer).

GET /crm/deal — Negociações (deals)

Retorna as oportunidades/negociações do CRM, com o funil e a etapa em que cada uma se encontra. É a rota indicada para espelhar o pipeline comercial em um BI ou calcular métricas de conversão.

Query params: apikey (obrigatório), associations (opcional — aceita customer).

POST /crm/deal/create — Criar negociação

Cria uma nova oportunidade no funil. Os campos pipeline_id e phase_id devem existir previamente na plataforma — consulte-os no GDASH antes de integrar.

Body:

Solar

GET /solar/plants — Usinas

Retorna as usinas de geração da organização. Cada usina pode trazer suas instalações (unidades consumidoras) em installations.

Query params: apikey (obrigatório), associations (opcional — aceita customer).

GET /solar/consumer-units — Unidades consumidoras

Retorna as unidades consumidoras (UCs) da organização, com filtros e paginação por cursor. É a rota mais direta para trabalhar com UCs sem precisar percorrer usinas ou clientes.

Query params:

Campos da resposta:

⚠️ O campo percentualExcedente está depreciado. Ele existe apenas por compatibilidade e não representa mais o rateio real quando há múltiplas fontes de crédito. Use energyCreditSources em integrações novas.

GET /solar/customers — Clientes

Retorna todos os clientes da organização, incluindo as usinas (plants) e as unidades consumidoras (installations) vinculadas a cada um.

Query params: apikey (obrigatório), associations (opcional — aceita deal, plant, ticket, consumer_unit, task).

GET /solar/customers/search — Buscar clientes com filtros

Mesmo retorno de /solar/customers, mas com filtros. Todos os parâmetros são opcionais e combináveis — quando você envia mais de um, eles se somam (comportamento "E", não "OU").

Esta é também a rota que você usa para resolver um ID vindo de associations em dados completos do cliente.

POST /solar/customers/create — Criar cliente

Cria um cliente já vinculado a uma usina. Os campos de envio (email_sending_enabled, whatsapp_message_sending_enabled) controlam se o cliente passará a receber as comunicações automáticas da plataforma — defina-os conscientemente ao integrar, para não disparar mensagens inesperadas durante uma carga inicial de dados.

Body:

GET /solar/payments/charges — Cobranças

Retorna as cobranças/pagamentos da organização. Suporta filtros e paginação por cursor. É a rota central para conciliação financeira e para acompanhar inadimplência.

Query params:

Campos da resposta:

Objeto customer: id, name, document, email, phone, number, street, district, city, state.

GET /solar/payments/charges/{charge_id} — Detalhe de uma cobrança

Retorna os dados de uma cobrança específica (mesma estrutura acima), pelo charge_id.

GET /solar/energy-billing — Faturas de energia

Retorna as faturas de energia lidas pela plataforma, já estruturadas em campos — consumo, compensação, tarifas, impostos e saldo de créditos. É a rota mais rica da API e a base para relatórios de economia e de geração distribuída.

Paginação por cursor — a resposta inclui nextCursor.

Query params:

Campos principais da resposta (data[]):

⚠️ Atenção ao campo errorMessage. Faturas são lidas automaticamente a partir dos portais das concessionárias, e nem toda leitura é bem-sucedida. Quando errorMessage estiver preenchido, os valores numéricos daquela fatura podem estar incompletos ou ausentes. Sempre verifique esse campo antes de usar a fatura em cálculos financeiros.

Objeto hfp / hp / hr (EnergyObject) — detalhamento por posto tarifário:

Postos tarifários: HFP = horário fora de ponta, HP = horário de ponta, HR = horário reservado. Em instalações convencionais (baixa tensão, grupo B), normalmente **só o hfp é preenchido** — os demais vêm zerados. Instalações de média tensão (grupo A) tipicamente trazem hfp e hp preenchidos.

Ticket

GET /ticket — Chamados

Retorna os tickets/chamados (ordens de serviço) da organização.

Query params: apikey (obrigatório), associations (opcional — aceita customer).

Exemplos em TypeScript

1. Buscar todas as cobranças, página por página

const API_KEY = process.env.GDASH_API_KEY!;
const BASE_URL = 'https://public-api.gdash.io/api/v1';

async function getAllCharges() {
  const limit = 50;
  let cursor: string | undefined;
  const allCharges: any[] = [];

  while (true) {
    const params = new URLSearchParams({ apikey: API_KEY, limit: String(limit) });
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(`${BASE_URL}/solar/payments/charges?${params}`);
    if (!response.ok) throw new Error(`Falha na API: ${response.status}`);

    const { data } = await response.json();
    allCharges.push(...data);

    // Menos itens que o limite significa que chegamos ao fim
    if (data.length < limit) break;

    // O próximo cursor é o created_at do último item recebido
    cursor = data[data.length - 1].created_at;
  }

  return allCharges;
}

2. Faturas de energia usando nextCursor

async function getEnergyBillings() {
  const all: any[] = [];
  let cursor: string | null = null;

  do {
    const params = new URLSearchParams({ apikey: API_KEY, limit: '100' });
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(`${BASE_URL}/solar/energy-billing?${params}`);
    const { data, nextCursor } = await response.json();

    // Ignora faturas cuja leitura falhou antes de usar em cálculos
    all.push(...data.filter((bill: any) => !bill.errorMessage));

    cursor = nextCursor; // null indica fim dos resultados
  } while (cursor);

  return all;
}

3. Buscar um cliente e suas unidades consumidoras

async function getCustomerWithUnits(cnpj: string) {
  const params = new URLSearchParams({
    apikey: API_KEY,
    cnpj,
    associations: 'consumer_unit,plant',
  });

  const response = await fetch(`${BASE_URL}/solar/customers/search?${params}`);
  const { data } = await response.json();

  return data[0];
}

4. Criar um cliente

async function createCustomer() {
  const response = await fetch(
    `${BASE_URL}/solar/customers/create?apikey=${API_KEY}`,
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        plant_id: 'plant_123',
        name: 'Empresa Exemplo LTDA',
        cnpj: '12345678000190',
        email: 'contato@exemplo.com.br',
        provider: 'enelsp',
        // Desligue os envios durante uma carga inicial de dados
        email_sending_enabled: false,
        whatsapp_message_sending_enabled: false,
      }),
    },
  );

  const { ok, data } = await response.json();
  return data;
}

Boas práticas de integração

Dúvidas frequentes

A API tem limite de requisições?
Não há um limite rígido publicado, mas integrações devem ser conscientes: prefira cargas incrementais e limit maior a laços de requisições pequenas e frequentes.

Consigo acessar dados de outra organização?
Não. A API Key define o escopo, e toda resposta é restrita à organização dona da chave.

O que acontece se eu gerar uma nova API Key?
A chave anterior deixa de funcionar. Atualize suas integrações antes de desabilitar a antiga.

A ordem dos resultados é garantida?
Nas rotas paginadas por cursor, os resultados vêm ordenados por data de criação — é isso que torna o cursor confiável.

Onde vejo a lista sempre atualizada de rotas e campos?
No Swagger: https://public-api.gdash.io/swagger

Atualizado em: 07/08/2026