SolarMarket

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 de 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 miniapp 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/signin enviando a chave no corpo:
• A API responde com um access_token, que passa a ser enviado como Authorization: Bearer {access_token} em todas as chamadas seguintes.
• O miniapp cacheia esse token por cerca de 5 horas (guarda o horário da última autenticação e só chama /auth/signin de novo quando esse período expira), evitando gerar um token novo a cada ação.

Na prática, para quem só vai usar o miniapp instalado, o único passo manual é copiar a Chave API do painel e colar no campo de configuração do miniapp 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 miniapp renova automaticamente ao completar ~5h de cache.
• Fora o 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 miniapp faz

O miniapp 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).

4. Dicas e observações

• Criar Projeto aceita duas formas de uso: se um clientId for informado, o projeto é vinculado a esse cliente já existente; se nenhum clientId for informado, o miniapp envia os dados do cliente junto no mesmo request e o SolarMarket cria cliente e projeto de uma vez.
• Antes de criar/editar um Projeto vinculado a uma etapa específica, use Obter Etapas de um funil para resolver o nome da etapa desejada em um stageId vá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, stageId e clientId devem 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).