Integraciones/NicoApps (MiniApps) Nativos/Sistemas de Negocios Locales/SolarMarket

SolarMarket

SolarMarket es un CRM para empresas de energía solar (embudos de ventas, clientes y proyectos). Este NicoApp integra NicoChat con la API v2 de SolarMarket (https://business.solarmarket.com.br).

2026-08-12

1. Cómo obtener las credenciales

El acceso a la API no se hace directamente con la clave copiada del panel: primero debe canjearse por un access token. El proceso completo tiene dos partes:

1.1. Obtener el Token API en el panel de SolarMarket

Accede a https://business.solarmarket.com.br/perfil y ve a API.

Copia el Token API. Viene en el formato id:secret, por ejemplo 204:OllF5qWhVH7HGMasvkNaNxIYqDU9XakPVJ9zKdoC.

Atención

Esta clave no se usa directamente en las llamadas de Cliente/Proyecto/Embudo. Solo sirve para obtener un token de acceso temporal, según el paso siguiente.

1.2. Canjear la clave por un access token

El NicoApp guarda la clave copiada arriba en una variable y, antes de cualquier acción (Crear Cliente, Crear Proyecto, etc.), pasa por un flujo secundario interno de Autenticación que:

Hace POST https://business.solarmarket.com.br/api/v2/auth/signin enviando la clave en el cuerpo:
La API responde con un access_token, que pasa a enviarse como Authorization: Bearer {access_token} en todas las llamadas siguientes.
El NicoApp mantiene ese token en caché durante unas 5 horas (guarda la hora de la última autenticación y solo vuelve a llamar a /auth/signin cuando ese período expira), evitando generar un token nuevo en cada acción.

Nota

La documentación oficial de SolarMarket informa que el token JWT generado tiene una validez de 360 minutos (6 horas). El NicoApp usa una ventana de caché un poco más corta (~5 h) como margen de seguridad antes de la expiración real.

En la práctica, para quien solo va a usar el NicoApp instalado, el único paso manual es copiar el Token API del panel y pegarlo en el campo de configuración del NicoApp en NicoChat: el canje por token y el caché ocurren automáticamente en cada acción.

2. Limitaciones

Rate limit: según la documentación oficial de la API de SolarMarket (solarmarket.readme.io), para prevenir abusos y ataques, las solicitudes están limitadas a 60 solicitudes por minuto y 1.800 solicitudes por hora por credencial.
Validez del token: el access token expira en 360 minutos (6 h); el NicoApp lo renueva automáticamente al cumplir ~5 h de caché.
Además del rate limit anterior, la documentación pública de SolarMarket no lista otras restricciones de uso (cuotas diarias, límite de registros por llamada, etc.).

3. Qué hace el NicoApp

El NicoApp expone 9 acciones de uso directo en flujos de conversación. Dos piezas adicionales existen solo como soporte interno y no aparecen como acción seleccionable: Autenticación (canje de la clave por token, descrito arriba) y Obtener Etapa por Nombre (utilidad llamada por "Obtener Etapas de un embudo" para resolver el nombre de una etapa a su ID).

Acción

Método / Punto final

Qué hace

Campos principales

Obtener Etapas de un embudo

GET /api/v2/funnels

Busca el embudo por el ID y devuelve sus etapas (stages); si se informa el nombre de una etapa, la resuelve al ID correspondiente (o acepta el ID numérico directamente)

ID del embudo, Nombre/ID de la etapa

Crear Cliente

POST /api/v2/clients

Crea un nuevo cliente en el CRM

name, company, cnpjCpf, email, primaryPhone, secondaryPhone, zipCode, address, number, complement, neighborhood, city, state, responsibleId, representativeId

Editar Cliente

PATCH /api/v2/clients/{id}

Actualiza campos de un cliente existente

Los mismos campos de Crear Cliente (envía solo los completados)

Obtener Cliente por ID

GET /api/v2/clients?id={id}

Consulta un cliente por el ID

Obtener Cliente por Email

GET /api/v2/clients?email={email}

Consulta un cliente por el correo electrónico registrado

Eliminar Cliente

DELETE /api/v2/clients/{id}

Elimina un cliente

Crear Proyecto

POST /api/v2/projects

Crea un nuevo proyecto, vinculándolo a un cliente existente o creando el cliente junto con él

name, description, stageId, responsibleId, representativeId, clientId (o los datos completos del cliente, si aún no existe)

Editar Proyecto

PATCH /api/v2/projects/{id}

Actualiza campos de un proyecto existente

name, description, stageId, responsibleId, representativeId

Eliminar Proyecto

DELETE /api/v2/projects/{id}

Elimina un proyecto

4. Consejos y observaciones

Crear Proyecto acepta dos formas de uso: si se informa un clientId, el proyecto se vincula a ese cliente ya existente; si no se informa ningún clientId, el NicoApp envía los datos del cliente en la misma solicitud y SolarMarket crea cliente y proyecto de una vez.
Antes de crear o editar un Proyecto vinculado a una etapa específica, usa Obtener Etapas de un embudo para resolver el nombre de la etapa deseada en un stageId válido.
Para evitar duplicidad de clientes, usa Obtener Cliente por Email antes de Crear Cliente: si ya existe, prefiere Editar Cliente.
Todas las acciones hacen el canje de token automáticamente; no es necesario (ni posible) llamar a la Autenticación manualmente desde el flujo.
Los campos numéricos como responsibleId, representativeId, stageId y clientId deben ser los IDs numéricos devueltos por la propia API (p. ej.: del responsable/representante del cliente, o del ID devuelto al crear el cliente).