1 1. Como obter as credenciais
- 1.1 1.1. Obter a Chave de API no painel do SolarMarket
- 1.2 1.2. Trocar a chave por um access token
2 2. Limitações
3 3. O que o miniapp faz
4 4. Dicas e observações

O SolarMarket é um CRM para empresas de energia solar (funis de vendas, clientes e projetos). Este miniapp integra o NicoChat com a API v2 do SolarMarket (https://business.solarmarket.com.br/api/v2), permitindo criar, consultar, editar e excluir clientes e projetos, além de consultar as etapas de um funil, diretamente a partir de um fluxo de conversa.

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.

Essa chave não é usada diretamente nas chamadas de Cliente/Projeto/Funil. Ela serve apenas para obter um token de acesso temporário, conforme o passo abaixo.

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:
{ "token": "204:OllF5qWhVH7HGMasvkNaNxIYqDU9XakPVJ9zKdoC" }
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.

A documentação oficial do SolarMarket informa que o token JWT gerado tem validade de 360 minutos (6 horas). O miniapp usa uma janela de cache um pouco mais curta (~5h) como margem de segurança antes da expiração real.

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

Ação	Método / Endpoint	O que faz	Principais campos

Ação	Método / Endpoint	O que faz	Principais campos
Obter Etapas de um funil	`GET /api/v2/funnels`	Busca o funil pelo ID e retorna suas etapas (stages); se for informado o nome de uma etapa, resolve para o ID correspondente (ou aceita o ID numérico diretamente)	ID do funil, Nome/ID da etapa
Criar Cliente	`POST /api/v2/clients`	Cria um novo cliente no CRM	name, company, cnpjCpf, email, primaryPhone, secondaryPhone, zipCode, address, number, complement, neighborhood, city, state, responsibleId, representativeId
Editar Cliente	`PATCH /api/v2/clients/{id}`	Atualiza campos de um cliente existente	Mesmos campos de Criar Cliente (envia só os preenchidos)
Obter Cliente pelo ID	`GET /api/v2/clients?id={id}`	Consulta um cliente pelo ID	id
Obter Cliente pelo Email	`GET /api/v2/clients?email={email}`	Consulta um cliente pelo e-mail cadastrado	email
Deletar Cliente	`DELETE /api/v2/clients/{id}`	Remove um cliente	id
Criar Projeto	`POST /api/v2/projects`	Cria um novo projeto, vinculado a um cliente existente ou criando o cliente junto	name, description, stageId, responsibleId, representativeId, clientId (ou dados completos do cliente, se ainda não existir)
Editar Projeto	`PATCH /api/v2/projects/{id}`	Atualiza campos de um projeto existente	name, description, stageId, responsibleId, representativeId
Deletar Projeto	`DELETE /api/v2/projects/{id}`	Remove um projeto	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).