Usar la API REST de Reonic

Reonic ofrece una API REST pública que cubre proyectos residenciales, proyectos comerciales, contactos, tareas, equipos, ficheros, citas, componentes, actividades, estado y pipeline, etiquetas, notas, paquetes de planificación, plantillas de planificación, plantillas de oferta, plantillas de lista de control, fuentes de leads, tableros y columnas kanban, contenido del wiki, fotogrametría y control horario.

Si el sistema que quieres conectar ya tiene una integración con nombre propio (HubSpot, Pipedrive, Lexoffice, Bexio, Hero, K2, Microsoft, Google, AroundHome, DAA, Wattfox, Bees & Bears, EOS, Photovate y más), usa esa: está preparada y con soporte. La API es para todo lo demás: sistemas propios, herramientas de BI, CRM de nicho, cuadros de mandos a medida y puentes con herramientas que no tienen integración propia. Para automatizaciones sin código y envíos de eventos salientes, consulta las guías de Zapier y de Webhooks.

Para quién es este artículo

Admins del instalador y admins de workspace que construyen integraciones a medida o exportan datos de Reonic. Tus clientes finales (propietarios de vivienda, compradores comerciales) nunca ven la superficie de la API.

Antes de empezar

• Necesitas permisos de admin en tu workspace de Reonic.
• La API está disponible en todos los workspaces. Si el panel de claves API no aparece en tus ajustes, ponte en contacto con el soporte de Reonic.
• Reonic mantiene en paralelo una versión actual de la API y la anterior durante un periodo de transición. Si tu workspace tiene claves en la versión antigua, la página Ajustes > API / Desarrolladores > API muestra una pestaña para cada una. Construye todas las integraciones nuevas contra la versión actual.
• Un host para scripts, una herramienta de BI o cualquier sistema que pueda enviar peticiones HTTPS.

Encontrar la página de ajustes de la API

La configuración de la API y de los webhooks vive en una página de ajustes distinta de la lista de integraciones con nombre propio.

1. Abre Ajustes > API / Desarrolladores. Es distinta de Ajustes > Configuración de la empresa > Integraciones (la página de integraciones con nombre propio).
2. La categoría API / Desarrolladores contiene dos páginas: API (crear y gestionar claves) y Webhooks (configurar los webhooks salientes y los hooks de Zapier).
3. Si tu workspace tiene claves en la versión anterior de la API, la página API muestra una pestaña para la versión actual (preseleccionada) y otra para la anterior. Los workspaces con claves solo en la versión actual ven una única página.
4. Si no ves la sección de claves API por ningún lado, ponte en contacto con el soporte de Reonic.

Crear una clave API

Las claves API permiten que tus scripts y sistemas externos se autentiquen en Reonic.

1. En la página API, haz clic en Crear nuevo para generar una clave API.
2. Ponle a la clave un nombre descriptivo que te diga para qué es, por ejemplo una clave de solo lectura para el almacén o una clave de producción para Zapier. El nombre aparece en el registro de actividad, así que podrás distinguir unas claves de otras.
3. Elige el alcance. Hay tres: Solo lectura (leer en todos los recursos), Lectura y escritura (lectura y escritura completas en todos los recursos) y Solo creación de leads (un alcance restringido que puede crear leads, proyectos residenciales, contactos y notas, y nada más). Para una integración normal, elige Solo lectura o Lectura y escritura. Solo creación de leads es para las claves de brókeres de leads entrantes, que solo deben añadir leads.
4. Reonic genera la clave y te la muestra al crearla.
5. Cópiala enseguida a tu gestor de secretos y después guarda. Si ya no tienes la clave, crea una nueva y elimina la antigua.

Dónde encontrar el ID de cliente

Tu ID de cliente es el identificador de tu workspace. Para la mayoría de las integraciones no lo necesitas por separado. Unas pocas integraciones de socios, como algunas configuraciones de brókeres de leads entrantes, lo piden como campo aparte. Pide al soporte de Reonic que te confirme el tuyo.

Clave API frente a ID de cliente

La clave API es el secreto, como una contraseña: autentica cada petición. El ID de cliente es el identificador de tu workspace, como un nombre de usuario. Mantén la clave API en privado; el ID de cliente es tu referencia de workspace para los sistemas de tus socios.

Autenticar las llamadas a la API

Reonic usa una cabecera de autenticación propia en lugar de la cabecera estándar Authorization. La referencia de endpoints indica el nombre exacto de la cabecera y muestra cómo ponerla.

1. En tu cliente HTTP, pon en la cabecera de autenticación de Reonic el valor de tu clave API.
2. Envía la petición al endpoint correspondiente.
3. Si la petición se rechaza por falta de autenticación, comprueba que has puesto la cabecera de autenticación de Reonic (no la cabecera estándar Authorization) y que has copiado la clave entera.

Encontrar la referencia de endpoints

La referencia de endpoints es una página de documentación generada. Es la lista autorizada de todos los endpoints, su ruta exacta, los campos de petición y respuesta y la cabecera de autenticación. Sus endpoints se agrupan en diez áreas generales:

• Personas — usuarios, equipos.
• Proyectos — proyectos residenciales (la superficie residencial de fotovoltaica, bomba de calor y wallbox) y proyectos comerciales (el pipeline comercial).
• Trabajar en un proyecto — actividades, estado, etiquetas, notas, ficheros, tableros y columnas kanban.
• Calendario — citas, feeds de calendario.
• Catálogo — componentes, fabricantes, paquetes de planificación, plantillas de planificación, plantillas de oferta.
• Configuración del workspace — fuentes de leads, plantillas de lista de control, integraciones.
• Wiki — contenido del wiki.
• Servicios — citas de servicio.
• Utilidades de la API — endpoints auxiliares.
• Guías — páginas de guía de migración incrustadas.

Hacer tu primera llamada a la API

Prueba la conexión antes de construir nada sobre ella.

1. Elige un endpoint de lectura de bajo riesgo. Una lista de proyectos residenciales o de contactos es un buen comienzo. La referencia de endpoints te da la ruta exacta.
2. Lanza la llamada con tu clave API en la cabecera de autenticación de Reonic.
3. Reonic responde con un payload JSON. Los endpoints de lista devuelven un array de datos más un bloque de paginación.
4. Confirma que la llamada ha llegado en Ajustes > Configuración de la empresa > Integraciones, con estado correcto.

Migrar a la versión actual de la API

Las dos versiones de la API conviven durante la transición, y la anterior se mantiene estable. Planifica tu migración con antelación para que tus integraciones estén en la versión actual bastante antes de que se retire la anterior. Pide al soporte de Reonic la fecha prevista de retirada para poder planificarte.

El grupo de migración de la referencia de endpoints recorre los pasos. En resumen:

1. Crea una clave nueva en la versión actual. Los endpoints actuales esperan una clave de la versión actual.
2. Gestiona las listas paginadas. Cada respuesta de lista envuelve un array de datos más un bloque de paginación. Actualiza cualquier parser que diera por hecho un array pelado.
3. Usa las superficies de proyectos residenciales y proyectos comerciales. Sustituyen a la antigua superficie de solicitudes y ofertas: proyectos residenciales para la línea de fotovoltaica, bomba de calor y wallbox, y proyectos comerciales para la línea comercial.
4. Adáptate a los nombres de campo actuales. Algunos nombres de campo cambian respecto a la versión anterior, entre ellos los de correo, dirección y variantes. La referencia de endpoints lista los nombres actuales.
5. Adopta los límites y el comportamiento de caché actuales. La referencia de endpoints describe cómo pedir una lectura fresca en cada llamada y cómo reaccionar cuando se te pide que reduzcas el ritmo (ver Gestionar los límites de peticiones y la caché).

Para recrear objetos que antes construías con los antiguos ayudantes de duplicado, usa el endpoint estándar de creación. La versión actual resuelve la duplicación con el flujo normal de creación.

Paginar, filtrar y extraer deltas

Los endpoints de lista usan paginación por número de página.

• Pasa un número de página y un tamaño de página para recorrer los resultados.
• La respuesta incluye enlaces a la página siguiente y a la anterior. Síguelos para recorrer el conjunto completo.
• Unos pocos endpoints paginan de otra forma. La referencia de endpoints señala esos casos, incluido un tamaño de página fijo en control horario, endpoints de respuesta única como equipos y etiquetas, y una ventana temporal deslizante en los eventos de calendario.

Para las extracciones de deltas (solo los registros cambiados desde tu última ejecución), los proyectos residenciales exponen una marca de tiempo de última edición que puedes usar como marca de agua. En otros endpoints, guarda la marca de tiempo de cambio más alta de la respuesta anterior y vuelve a leer desde ahí. El soporte de filtros para consultas "cambiado desde" varía según el endpoint. Si tu script necesita deltas, pregunta al soporte de Reonic qué endpoints de lista exponen ese filtro.

Gestionar los límites de peticiones y la caché

La API aplica un límite de peticiones por workspace para que ninguna integración sature tus datos. Si envías peticiones más rápido que el límite, Reonic responde pidiéndote que reduzcas el ritmo.

1. Cuando se te pida reducir el ritmo, espera antes de reintentar. Un retroceso exponencial (2, 4, 8, 16 segundos) es un patrón seguro.
2. Si el servicio informa de que no está disponible temporalmente, espera y reintenta.
3. Para extracciones grandes, dosifica las llamadas y añade una pausa breve entre páginas para no pasarte del límite.
4. Las lecturas repetidas se sirven desde una caché de corta duración. Cuando necesites los datos más recientes en una llamada concreta, la referencia de endpoints muestra cómo pedir una lectura fresca.

Gestionar los errores

Reonic devuelve errores HTTP estructurados que se corresponden con la semántica estándar 4xx y 5xx.

• Sin autenticar — clave ausente o no válida. Comprueba que has puesto la cabecera de autenticación de Reonic (no la cabecera estándar Authorization) y que has copiado la clave entera.
• Permiso denegado — el alcance de la clave no incluye la operación, o el recurso queda fuera de lo que la clave permite. Trata las respuestas 4xx como definitivas; no reintentes.
• No encontrado — comprueba el ID.
• Se te pide reducir el ritmo — estás enviando peticiones demasiado rápido. Espera y reintenta.
• Error del servidor (5xx) — comunícalo al soporte con la marca de tiempo. Trata los 5xx como transitorios y reintenta con retroceso.
• No disponible temporalmente — espera y reintenta.

Tareas habituales con la API

Estos son los patrones más preguntados. Tómalos como puntos de partida. La referencia de endpoints en vivo lista todos los endpoints y la forma exacta de sus campos; tu gestor de cuentas puede ayudarte si te atascas.

Crear una solicitud

Usa el endpoint de creación de proyectos residenciales para los leads de fotovoltaica, bomba de calor y wallbox, y el de proyectos comerciales para el pipeline comercial. El endpoint devuelve el ID del nuevo proyecto.

Para que el lead aparezca en el mapa, Reonic necesita una ubicación. Facilita una dirección para que Reonic la resuelva, o unas coordenadas que ya hayas resuelto tú. Incluye siempre el código postal y verifica las coordenadas devueltas si necesitas precisión exacta.

Fija el estado del proyecto al crearlo si quieres un estado inicial concreto. Si no, la solicitud aterriza en el estado inicial del workspace.

Este es además el endpoint para importar leads desde un sistema sin integración propia, por ejemplo un formulario de contacto de WordPress que publica en tu endpoint de proyectos residenciales o de contactos. La vía con menos código es un puente de Zapier desde el formulario de WordPress.

Editar una solicitud después de crearla

Actualiza la mayoría de los campos después de crearla, incluida la dirección, con el endpoint de actualización de proyectos residenciales o comerciales y el ID del proyecto.

Crear una oferta a partir de un proyecto

Una oferta (Angebot) en la API es el presupuesto con precios y variantes que cuelga de un proyecto. Agrupa una o varias variantes (cada una con su lista de componentes, su selección de paquetes, sus precios y su descuento o financiación opcionales) más los metadatos de la oferta (estado, estado de firma, notas y ficheros adjuntos). Es la misma construcción que ves en el Portal en la pestaña Ofertas de un proyecto.

El flujo recomendado:

1. Crea el proyecto por la API.
2. Toma el ID del proyecto de la respuesta.
3. Llama al endpoint de creación de ofertas con ese ID de proyecto y la definición de tu variante.
4. La respuesta contiene el ID de la nueva oferta, que usarás para actualizaciones posteriores.

Deja sin fijar el estado de la oferta al crearla si quieres que aterrice como borrador. Para convertir una solicitud en oferta, llama al endpoint de creación de ofertas con el ID del proyecto y Reonic enlaza la nueva oferta con el proyecto de origen.

Fijar o actualizar el precio de una oferta con la API

El endpoint de actualización de ofertas acepta un precio a nivel de variante, lo que resulta útil cuando tu sistema de precios externo necesita meter un precio final en Reonic. La forma exacta del campo depende de la variante. Consulta la referencia de endpoints o pregunta al soporte de Reonic.

Añadir notas o ficheros a una oferta

Hay endpoints específicos para añadir una nota y para subir un fichero. Los ficheros subidos (PDF, imágenes) se adjuntan a la oferta, el proyecto o el contacto al que apuntes.

Crear un contacto

Usa el endpoint de creación de contactos. Las coordenadas no son necesarias al crear contactos; solo los proyectos que aparecen en el mapa necesitan una ubicación.

Para las importaciones masivas (migrar a Reonic una lista de contactos existente desde un CSV, un CRM antiguo o una hoja de cálculo), recorre tus registros y crea un contacto por llamada, dosificando las llamadas para no pasarte del límite. Para migraciones puntuales más grandes, ejecuta el bucle desde tu propia infraestructura contra el mismo endpoint. Todos los endpoints de creación devuelven el ID del nuevo recurso, así que guárdalo en el momento de crearlo.

Filtrar actividades por tipo de elemento padre

El endpoint de actividades admite un filtro por tipo de elemento padre que acota las actividades a un tipo concreto de registro padre, por ejemplo un proyecto residencial, un proyecto comercial, un paquete, un componente, un contacto, un trabajo de fotogrametría o un usuario. Consulta la referencia de endpoints para conocer los valores exactos que acepta.

Exportar datos

La vía más limpia para una exportación masiva es listar el endpoint correspondiente con paginación y guardar la respuesta. Objetivos habituales:

• Ofertas ganadas — extrae todas las ofertas y filtra por estado, o extrae la lista del estado "ganada".
• Contactos — extrae los contactos con paginación y guárdalos en local.
• Proyectos comerciales — extrae los proyectos comerciales.
• Citas — extrae las citas de la superficie de calendario de Reonic. Los calendarios externos de Microsoft o Google se extraen directamente de esos servicios.
• Versiones de componentes — extrae los componentes y agrúpalos por componente padre donde existan versiones.
• Estado kanban — extrae los tableros y columnas kanban para tener instantáneas de los tableros de proyecto.
• Fuentes de leads — extrae las fuentes de leads para conocer la taxonomía de canales de lead configurada en el workspace.

Para producir un fichero de Excel con tus solicitudes, ofertas, estadísticas o datos en bruto, extrae el endpoint de lista correspondiente y carga la respuesta JSON en Excel, Google Sheets o tu herramienta de BI.

Usa la versión actual de la API para las integraciones externas

Construye siempre las integraciones externas contra la versión pública actual de la API, incluidas las subidas de ficheros. Es el contrato estable y con soporte para leer y escribir tus datos desde fuera del Portal.

Puentes con herramientas sin integración propia

Para los sistemas que no están en el catálogo de integraciones con nombre propio (Datev, Monday.com, Craftnote, sincronización de contactos de Office 365, Zoho CRM, envíos masivos de correo), construye contra la API para enviar datos de forma programada, o conéctalos con Zapier.

• Datev — saca las facturas de Reonic por la API e impórtalas en Datev del lado contable, o usa Lexoffice o Sevdesk como puente (ambos tienen exportación nativa a Datev). La vía de Lexoffice o Sevdesk es también la forma de conectar con una asesoría fiscal (Steuerbüro), que normalmente ya tiene acceso a una de esas herramientas.
• Sincronización de contactos de Office 365 — la integración de Microsoft se ocupa de los calendarios; los contactos se sincronizan con un Zap a medida o una integración por API contra tu endpoint de contactos.
• Envíos masivos de correo — Reonic no es una herramienta de email marketing. Exporta tus contactos por la API y envía la campaña desde una plataforma dedicada (Mailchimp, Brevo, HubSpot Marketing).
• Zoho CRM — puentéalo con un flujo de Zapier (un disparador Zoho CRM new-lead que publique en tu endpoint de proyectos residenciales o de contactos), o programa una sincronización periódica de Zoho a Reonic en tu propia infraestructura. Las dos vías necesitan los campos de dirección descritos en Crear una solicitud.
• Calendario de Microsoft 365 / Google Workspace — tienen integraciones específicas en Ajustes > Configuración de la empresa > Integraciones, no van por la API. Configúralas ahí y después extrae los calendarios externos de Outlook o de Google directamente de esos servicios. La API expone las citas de Reonic.
• Brókeres de leads (AroundHome, DAA, Wattfox y otros) — tienen integraciones específicas con nombre propio en Ajustes > Configuración de la empresa > Integraciones, así que usa esas en lugar de la API genérica. En AroundHome, el ID de cliente es el identificador propio de la integración; consulta el panel de administración de AroundHome para saber el formato exacto. Recurre a la API o a Zapier solo para las fuentes de leads que estén fuera del catálogo.

Si quieres una integración con nombre propio para una fuente de gran volumen, coméntaselo a tu gestor de cuentas.

Dónde viven las integraciones con nombre propio

Todas las integraciones con nombre propio viven en Ajustes > Configuración de la empresa > Integraciones (no en API / Desarrolladores), cada una con su propia página de configuración y sus credenciales por workspace. Para la financiación de Bees & Bears no necesitas una clave API: configura la integración directamente en Ajustes > Configuración de la empresa > Integraciones y Reonic se encarga de las credenciales.

• HubSpot, Photovate, Hero, Sevdesk — consulta sus páginas de configuración en Ajustes > Configuración de la empresa > Integraciones.
• Exportación de ofertas a Photovate / K2 y vinculación de componentes de Photovate — botones de exportación específicos en la oferta firmada. Para las ofertas que necesiten datos de K2 después de la firma, haz clic en el botón de exportación de la fila de la firma.
• Financiación (Bees & Bears, EOS) — Bees & Bears cubre DE, AT, FR y BE; EOS cubre Brasil. Cuando un cliente firma una oferta con una opción de financiación, usa el botón de exportación a financiación de la oferta firmada. Reonic envía al socio financiero los datos de la oferta, los datos del cliente y el PDF firmado. Si no aparece la opción de exportación, comprueba con tu gestor de cuentas que tu workspace tiene habilitada la integración de financiación y que el usuario tiene el derecho Proveedor de financiación.
• Sevdesk tras un enlace caducado — para transferir una oferta firmada a Sevdesk cuando el enlace de firma original ha caducado, emite una nueva solicitud de firma sobre la misma variante, sube el PDF firmado a la nueva fila de firma y haz clic en el botón de exportación a Sevdesk de esa fila.
• SMTP — Reonic envía los correos dirigidos a clientes, como los enlaces de firma y los avisos de factura. Para enviarlos desde tu propio dominio, configura un servidor SMTP saliente personalizado en Ajustes > Configuración de la empresa > Integraciones > Servidor de correo SMTP.
• Campos del formulario de contacto y UTM — el formulario de contacto admite un conjunto limitado de campos adicionales y etiquetas de fuente de lead. El paso de parámetros UTM en los formularios incrustados lo gestiona el código de inserción; habla con tu gestor de cuentas sobre el seguimiento de UTM en el formulario de contacto.

Transferir ofertas entre workspaces de Reonic

Para mover una oferta de un workspace de Reonic a otro:

1. Exporta el PDF de la oferta desde el workspace de origen.
2. Vuelve a crear el proyecto y la oferta en el workspace de destino, por la API o a mano en el Portal.
3. Adjunta el PDF exportado como fichero en la oferta de destino.

Si esto se convierte en algo recurrente, por ejemplo un grupo de franquicias que mueve ofertas entre workspaces, habla con tu gestor de cuentas sobre un patrón mejor.

Conviene saber

• La API está disponible en todos los workspaces. Las claves aparecen en la página Ajustes > API / Desarrolladores > API.
• Las dos versiones de la API conviven durante la transición. Construye las integraciones nuevas contra la versión actual y migra antes de que se retire la anterior; pide al soporte de Reonic la fecha prevista.
• Reonic usa una cabecera de autenticación propia, no la cabecera estándar Authorization. Muchos clientes HTTP usan Authorization por defecto; añade en su lugar la cabecera de autenticación de Reonic como cabecera personalizada. La referencia de endpoints indica su nombre.
• La referencia de endpoints es el contrato autorizado. Lista todos los endpoints, su ruta exacta, los campos de petición y respuesta y la cabecera de autenticación. Cuando un campo o una ruta cambia respecto a la versión anterior, la referencia muestra el nombre actual.
• Los errores de permisos llegan como errores HTTP estructurados. Trata los 4xx como definitivos (no reintentes) y los 5xx como transitorios (reintenta con retroceso).
• Copia cada clave a tu gestor de secretos al crearla. Si ya no tienes una clave, crea una nueva y elimina la antigua.
• El alcance de una clave API tiene tres niveles — Solo lectura, Lectura y escritura y Solo creación de leads (un alcance restringido que solo puede crear proyectos residenciales, contactos y notas, pensado para claves de brókeres de leads entrantes). Crea claves separadas con nombres descriptivos para tener claridad de auditoría.
• Los límites de peticiones se aplican por workspace. Si envías peticiones demasiado rápido, Reonic te pide que reduzcas el ritmo; espera y reintenta. Todas las claves de un workspace comparten un único presupuesto.
• Las lecturas repetidas se sirven desde una caché de corta duración. Cuando necesites los datos más recientes en una llamada concreta, la referencia de endpoints muestra cómo pedir una lectura fresca.
• Eliminar una clave hace que deje de funcionar. Desactivar, rotar o borrar una clave la deja fuera de servicio.
• Todas las llamadas a la API quedan en el registro de actividad de la integración con tu ID de cliente, el método, el estado y una marca de tiempo, visible en Ajustes > Configuración de la empresa > Integraciones.
• Las actividades se filtran por tipo de elemento padre. Acota las actividades a un proyecto residencial, un proyecto comercial, un paquete, un componente, un contacto, un trabajo de fotogrametría o un usuario; consulta la referencia de endpoints para conocer los valores exactos.
• Los calendarios externos no pasan por la API. La API expone las citas de Reonic; extrae Outlook o Google directamente de esos servicios.
• Prueba contra tu workspace con una solicitud de prueba claramente identificada, y bórrala después.

Última actualización el 12 de octubre de 2026