SolarMarket
O SolarMarket é um CRM para empresas de energia solar (funis de vendas, clientes e projetos). Este NicoApp integra o NicoChat com a API v2 do SolarMarket (https://business.solarmarket.com.br).
1. Como obter as credenciais
O acesso à API não é feito diretamente com a chave copiada do painel — ela precisa primeiro ser trocada por um access token. O fluxo completo tem duas partes:
1.1. Obter a Chave API no painel do SolarMarket
Acesse https://business.solarmarket.com.br/perfil e vá em API.
Copie a Chave API. Ela vem no formato id:secret, por exemplo 204:OllF5qWhVH7HGMasvkNaNxIYqDU9XakPVJ9zKdoC.
1.2. Trocar a chave por um access token
O NicoApp guarda a chave copiada acima em uma variável e, antes de qualquer ação (Criar Cliente, Criar Projeto, etc.), passa por um sub-fluxo interno de Autenticação que:
- Faz
POST https://business.solarmarket.com.br/api/v2/auth/signinenviando a chave no corpo: - A API responde com um
access_token, que passa a ser enviado comoAuthorization: Bearer {access_token}em todas as chamadas seguintes. - O NicoApp mantém esse token em cache por cerca de 5 horas (guarda o horário da última autenticação e só chama
/auth/signinde novo quando esse período expira), evitando gerar um token novo a cada ação.
Na prática, para quem só vai usar o NicoApp instalado, o único passo manual é copiar a Chave API do painel e colá-la no campo de configuração do NicoApp no NicoChat — a troca por token e o cache acontecem automaticamente em cada ação.
2. Limitações
- Rate limit: segundo a documentação oficial da API SolarMarket (solarmarket.readme.io), para prevenir abusos e ataques, as requisições são limitadas a 60 requisições por minuto e 1.800 requisições por hora por credencial.
- Validade do token: o access token expira em 360 minutos (6h); o NicoApp renova automaticamente ao completar ~5h de cache.
- Além do rate limit acima, a documentação pública do SolarMarket não lista outras restrições de uso (quotas diárias, limite de registros por chamada etc.).
3. O que o NicoApp faz
O NicoApp expõe 9 ações de uso direto em fluxos de conversa. Duas peças adicionais existem só como suporte interno e não aparecem como ação selecionável: Autenticação (troca de chave por token, descrita acima) e Obter Etapa por Nome (utilitário chamado por "Obter Etapas de um funil" para resolver o nome de uma etapa para o seu ID).
GET /api/v2/funnelsPOST /api/v2/clientsPATCH /api/v2/clients/{id}GET /api/v2/clients?id={id}GET /api/v2/clients?email={email}DELETE /api/v2/clients/{id}POST /api/v2/projectsPATCH /api/v2/projects/{id}DELETE /api/v2/projects/{id}4. Dicas e observações
- Criar Projeto aceita duas formas de uso: se um
clientIdfor informado, o projeto é vinculado a esse cliente já existente; se nenhumclientIdfor informado, o NicoApp envia os dados do cliente junto na mesma requisição e o SolarMarket cria cliente e projeto de uma vez. - Antes de criar ou editar um Projeto vinculado a uma etapa específica, use Obter Etapas de um funil para resolver o nome da etapa desejada em um
stageIdválido. - Para evitar duplicidade de clientes, use Obter Cliente pelo Email antes de Criar Cliente — se já existir, prefira Editar Cliente.
- Todas as ações fazem a troca de token automaticamente; não é necessário (nem possível) chamar a Autenticação manualmente a partir do fluxo.
- Campos numéricos como
responsibleId,representativeId,stageIdeclientIddevem ser os IDs numéricos retornados pela própria API (ex.: do responsável/representante do cliente, ou do ID retornado ao criar o cliente).