Introdução#
Bem-vindo à documentação da API da Plataforma de Gestão Comercial da Groner, o maior CRM do mercado de Energia Solar. Esta documentação foi elaborada para desenvolvedores parceiros que desejam integrar seus sistemas com a plataforma Groner.A API da Groner oferece acesso programático a diversos recursos da plataforma, permitindo que você gerencie projetos, leads, propostas e muito mais. Com mais de 300 endpoints disponíveis, a API proporciona uma integração completa e flexível com o ecossistema Groner.Importante: Cada cliente possui seu próprio subdomínio para acesso à API. Por exemplo, se o nome do cliente for "Projeto Solar", a URL de acesso será projetosolar.api.groner.app. A URL base http://testes.api.groner.app é utilizada apenas para ambiente de testes, uma outra forma de descobrir sua URL Base é ir no seu grupo de atendimento e digitar !link.
Nota: Esta documentação utiliza os termos da API. Para facilitar o entendimento, consulte o Glossário de Termos para mapear os termos da API para os termos utilizados na plataforma.
Autenticação#
A API da Groner utiliza autenticação baseada em token. Para acessar os endpoints protegidos, você precisa obter um token de acesso válido e incluí-lo no cabeçalho de suas requisições.Gerando um Token de Acesso#
Para gerar um token de acesso com validade de 1 ano, utilize o endpoint /api/Conta/GerarToken. Este endpoint requer que você forneça suas credenciais de acesso no corpo da requisição.POST /api/Conta/GerarTokenCorpo da Requisição#
{
"email": "seu_email@dominio.com",
"senha": "sua_senha"
}
Exemplo de Requisição#
Resposta de Sucesso#
{
"Version": "1.0.0.0",
"StatusCode": 200,
"Message": "Requisição efetuada com sucesso.",
"Content": {
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiration": "2026-05-27T13:29:00Z"
}
}
Utilizando o Token#
Após obter o token, inclua-o no cabeçalho Authorization de todas as suas requisições subsequentes, utilizando o esquema Bearer:Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Padrão de Resposta#
Todas as respostas da API seguem um padrão consistente, facilitando o tratamento dos dados retornados. O formato padrão de resposta é o seguinte:{
"Version": "1.0.0.0",
"StatusCode": 200,
"Message": "Requisição efetuada com sucesso.",
"Content": {
}
}
Campos da Resposta#
| Campo | Tipo | Descrição |
|---|
| Version | string | Versão da API |
| StatusCode | integer | Código de status HTTP da resposta |
| Message | string | Mensagem descritiva sobre o resultado da requisição |
| Content | object | Conteúdo específico da resposta, variando conforme o endpoint |
Exemplo de Resposta#
{
"Version": "1.0.0.0",
"StatusCode": 200,
"Message": "Requisição efetuada com sucesso.",
"Content": {
"resposta": 20.0,
"formula": "2 * 5 + 10"
}
}
Content contém os dados específicos retornados pelo endpoint, incluindo o resultado de um cálculo e a fórmula utilizada.Glossário de Termos#
Para facilitar o entendimento da API, é importante conhecer o mapeamento entre os termos utilizados na API e os termos correspondentes na plataforma Groner:| Termo na API | Termo na Plataforma | Descrição |
|---|
| Card / Negócio / Deal | Projetos | Representa um projeto comercial dentro da plataforma |
| Contato | Leads | Representa um potencial cliente ou contato comercial |
| PreProposta | Proposta | Representa uma proposta comercial enviada a um cliente |
Ao utilizar a API, lembre-se de que os endpoints e parâmetros utilizam os termos da coluna "Termo na API", enquanto a interface da plataforma utiliza os termos da coluna "Termo na Plataforma".Tratamento de Erros#
Quando ocorre um erro na API, a resposta segue o mesmo padrão, mas com um código de status HTTP diferente de 200 e uma mensagem de erro no campo Message.Exemplo de Resposta de Erro#
{
"Version": "1.0.0.0",
"StatusCode": 400,
"Message": "Parâmetros inválidos na requisição.",
"Content": {
"erros": [
"O campo 'email' é obrigatório.",
"O campo 'senha' deve ter pelo menos 6 caracteres."
]
}
}
Códigos de Status Comuns#
| Código | Descrição |
|---|
| 200 | Sucesso - A requisição foi processada com sucesso |
| 400 | Bad Request - A requisição contém parâmetros inválidos ou está mal formatada |
| 401 | Unauthorized - Autenticação necessária ou token inválido |
| 403 | Forbidden - O usuário não tem permissão para acessar o recurso |
| 404 | Not Found - O recurso solicitado não foi encontrado |
| 500 | Internal Server Error - Erro interno no servidor |
Dicas para Tratamento de Erros#
Sempre verifique o código de status HTTP da resposta
Leia a mensagem de erro no campo Message para entender o problema
Verifique o campo Content para detalhes adicionais sobre o erro
Implemente retry com backoff exponencial para erros temporários (códigos 5xx)
Registre os erros em logs para facilitar a depuração
Boas Práticas#
Para garantir o melhor desempenho e confiabilidade ao utilizar a API da Groner, recomendamos seguir estas boas práticas:Autenticação#
Armazene o token de acesso de forma segura e não o compartilhe. Lembre-se de que o token tem validade de 1 ano, mas é uma boa prática implementar um mecanismo para renovação automática antes da expiração.Paginação#
Utilize os parâmetros de paginação (PageNumber e PageSize) em endpoints que retornam listas para evitar sobrecarga no servidor e melhorar o desempenho da sua aplicação.Cache#
Implemente cache do lado do cliente para dados que não mudam com frequência, como listas de referência, configurações, etc. Isso reduz o número de requisições à API e melhora o tempo de resposta da sua aplicação.Tratamento de Erros#
Implemente um tratamento robusto de erros na sua aplicação, considerando os diferentes códigos de status e mensagens retornados pela API. Isso melhora a experiência do usuário e facilita a depuração de problemas.Rate Limiting#
A API da Groner implementa limitação de taxa (rate limiting) para evitar sobrecarga do servidor. Respeite esses limites e implemente mecanismos para lidar com respostas 429 (Too Many Requests), como retry com backoff exponencial.Monitoramento#
Monitore o desempenho e a disponibilidade da API na sua aplicação, registrando métricas como tempo de resposta, taxa de erros, etc. Isso ajuda a identificar problemas e otimizar a integração.
Documentação da API da Plataforma de Gestão Comercial da Groner - Versão v1.2040© 2025 Groner CRM - O Maior do Mercado de Energia SolarModificado em 2025-05-28 20:30:22
