Documentación de la API externa

La integración basada en clave de API te da acceso al calendario, a los proyectos, a los clientes y a los componentes. Esto te da flexibilidad para integrar tus sistemas y automatizar procesos.

Índice

1. Autenticación
2. Paginación
3. API del calendario
4. API de proyectos
5. API de clientes
6. API de componentes
7. Convenciones de datos
8. Comportamiento de filtrado
9. Modelo de permisos
10. Gestión de errores
11. Patrones de integración
12. Estabilidad y versionado

1. Autenticación

Todas las solicitudes deben incluir una clave de API en el encabezado de la solicitud.

Authorization: Api-Key <raw_api_key>

Notas: - Las claves de API son creadas y administradas por los propietarios y administradores de la empresa. - Cada clave tiene un ámbito limitado a permisos específicos de recursos. - Todas las solicitudes se limitan automáticamente a la empresa asociada a la clave de API.

Errores de autenticación

2. Paginación

Los endpoints de listado (calendario, proyectos y clientes) usan paginación limit/offset.

Parámetros

Estructura de respuesta

{
  "count": 123,
  "next": null,
  "previous": null,
  "results": []
}

Cuando next es null, has llegado a la última página.

3. API del calendario

Representa eventos programados como reuniones, llamadas y citas de instalación. Solo lectura.

Endpoints

GET https://api-production.easysolar-app.com/integrations/calendar/
GET https://api-production.easysolar-app.com/integrations/calendar/{id}/

Permiso requerido: calendar_read

Ejemplo de respuesta

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Visita inicial al emplazamiento",
  "description": "Discutir los requisitos de instalación e inspeccionar la cubierta.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Calle Principal 10, Varsovia",
    "phone": "+48123456789",
    "is_open": true
  },
  "participants": [
    {
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com"
    }
  ],
  "start_at": "2026-06-15T09:00:00Z",
  "end_at": "2026-06-15T10:00:00Z",
  "full_day": false,
  "created_at": "2026-06-01T12:30:45Z"
}

Referencia de campos

Valores de categoría

Objetos anidados

Objeto cliente:

Objeto participante:

Filtros

Ejemplo:

GET https://api-production.easysolar-app.com/integrations/calendar/?start_at_after=2026-01-01T00:00:00Z&category=meeting&category=call
Authorization: Api-Key <key>

4. API de proyectos

Representa registros de proyectos relacionados con clientes (p. ej., instalaciones fotovoltaicas). Solo lectura.

Endpoints

GET https://api-production.easysolar-app.com/integrations/projects/
GET https://api-production.easysolar-app.com/integrations/projects/{id}/

Permiso requerido: projects_read

Ejemplo de respuesta

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Instalación fotovoltaica - Oficina de Varsovia",
  "address": "Aleje Jerozolimskie 120, Varsovia",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Calle Principal 10, Varsovia",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "En curso",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Złoty polaco"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Referencia de campos

total_price se devuelve como una cadena decimal para preservar la precisión. payback_period es null si aún no se ha calculado. latitude/longitude son null si no se ha definido ninguna ubicación.

Objetos anidados

Objeto de estado:

Objeto de moneda:

Filtros

Ejemplo:

GET https://api-production.easysolar-app.com/integrations/projects/?client=<id>&name=solar
Authorization: Api-Key <key>

5. API de clientes

Representa entidades de clientes. Admite operaciones de lectura y escritura.

Endpoints

GET    https://api-production.easysolar-app.com/integrations/clients/
POST   https://api-production.easysolar-app.com/integrations/clients/
GET    https://api-production.easysolar-app.com/integrations/clients/{id}/
PATCH  https://api-production.easysolar-app.com/integrations/clients/{id}/

Permisos requeridos: clients_read (lectura), clients_write (escritura)

Ejemplo de respuesta

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Cliente comercial interesado en una instalación fotovoltaica en cubierta.",
  "address": "Calle Principal 10, Varsovia",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Referencia de campos

Crear cliente

POST https://api-production.easysolar-app.com/integrations/clients/

{
  "name": "Nombre del cliente",
  "description": "Cliente comercial",
  "address": "Dirección",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Actualizar cliente

PATCH https://api-production.easysolar-app.com/integrations/clients/{id}/

Incluye solo los campos que quieras actualizar:

{
  "address": "Nueva dirección 15, Varsovia",
  "phone": "+48987654321"
}

Reglas de coordenadas

• latitude y longitude deben proporcionarse siempre juntas.
• Proporcionar solo una coordenada provoca un error de validación.
• Si no se ha definido ninguna ubicación, ambos campos se devuelven como null.

Filtros

6. API de componentes

Crea componentes para usar en proyectos. Solo escritura.

Endpoint

POST https://api-production.easysolar-app.com/integrations/components/

Permiso requerido: components_write

Tipos de componente

Se admiten tres tipos de componente: panel, inverter y other.

Panel

{
  "type": "panel",
  "manufacturer_name": "Longi",
  "name": "LR5-54HPH",
  "net_unit_price": "120.00",
  "nominal_power": "430.000",
  "length": "1.7220",
  "width": "1.1340",
  "weight": "21.500",
  "efficiency": "0.2100000",
  "short_circuit_current": "13.52000",
  "open_circuit_voltage": "37.85000",
  "current_temperature_coefficient": "0.045000",
  "voltage_temperature_coefficient": "-0.280000",
  "power_temperature_coefficient": "-0.350000"
}

Inversor

{
  "type": "inverter",
  "manufacturer_name": "SMA",
  "name": "Sunny Tripower 5.0",
  "net_unit_price": "900.00",
  "nominal_power": "5000.000",
  "number_of_dc_inputs": 2
}

Otro

{
  "type": "other",
  "name": "Estructura de montaje",
  "unit": "uds.",
  "net_unit_price": "50.00"
}

Respuesta

{
  "id": "uuid",
  "type": "panel | inverter | other",
  "name": "string"
}

Notas

• Los fabricantes se crean automáticamente si no existen.
• La unicidad del fabricante se aplica al ámbito de cada empresa.
• Todos los campos específicos del panel se validan antes de su creación.

7. Convenciones de datos

IDs

Todos los identificadores de recursos son cadenas UUID, estables y globalmente únicas dentro de una empresa:

"id": "550e8400-e29b-41d4-a716-446655440000"

Marcas temporales

Todos los campos de fecha y hora se devuelven en formato ISO 8601, siempre en UTC:

"created": "2026-06-09T12:34:56Z"

Geolocalización

Las coordenadas se aplican a clientes y proyectos. Se almacenan como un punto geográfico y se devuelven como campos separados:

"latitude": 52.2297,
"longitude": 21.0122

Gestión de valores nulos

Los campos que no están establecidos se devuelven como null — nunca se omiten de la respuesta.

8. Comportamiento de filtrado

Reglas generales

• Todos los filtros son opcionales salvo que se indique lo contrario.
• Varios filtros se combinan con lógica AND.
• Los valores de filtro de selección múltiple (p. ej., category) usan lógica OR internamente.
• Los valores de filtro no válidos devuelven resultados vacíos o un error de validación según el tipo de campo.

Filtros de rango de fechas

Disponibles en todos los endpoints:

Filtros de búsqueda de texto

Coincidencia parcial sin distinción entre mayúsculas y minúsculas en name y phone:

?name=solar

Coincide con: "Solar Corp", "Mi proyecto solar", etc.

9. Modelo de permisos

Los permisos de la clave de API se configuran de forma independiente para cada recurso:

10. Gestión de errores

Formato del error

Error general:

{
  "detail": "Mensaje de error"
}

Error de validación a nivel de campo:

{
  "field_name": ["Mensaje de error"]
}

Referencia de errores

Lista de verificación de integración

Si encuentras errores, verifica:

1. Que la clave de API tenga los permisos correctos para el recurso.
2. Que la cuenta de la empresa esté activa.
3. Que todos los valores de filtro (IDs, etc.) pertenezcan al mismo ámbito de la empresa.

11. Patrones de integración

Estrategia de sincronización

El enfoque recomendado para sincronizar datos:

1. Obtén el endpoint de listado (paginado).
2. Guarda el id como referencia externa.
3. Usa el campo updated para sincronizaciones incrementales.

Gestión de la paginación

Recorre las páginas incrementando el offset hasta que next sea null:

GET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=0
GET https://api-production.easysolar-app.com/integrations/clients/?limit=100&offset=100

Sincronización incremental

Usa filtros de fecha para obtener solo los registros que hayan cambiado desde tu última sincronización:

GET https://api-production.easysolar-app.com/integrations/projects/?updated_after=2026-01-01T00:00:00Z

Buenas prácticas de filtrado

• Prefiere filtros basados en ID (client, status) frente a búsquedas de texto para sincronizaciones de gran volumen.
• Combina varios filtros para reducir el tamaño del conjunto de resultados.
• Evita búsquedas de texto amplias en conjuntos de datos grandes.

12. Estabilidad y versionado

Garantías estables

Lo siguiente no cambiará sin una migración versionada:

• URLs de los endpoints
• Nombres de los campos
• Formato UUID
• Estructura de paginación
• Esquema de autenticación

Sujeto a cambios (sin ruptura)

• Filtros opcionales (se podrán añadir nuevos filtros)
• Enriquecimiento de la respuesta (se podrán añadir nuevos campos)

Política de versionado

Actualmente no se expone una versión explícita en la URL. Los cambios incompatibles introducirán un nuevo espacio de nombres de endpoints:

https://api-production.easysolar-app.com/integrations/v2/...

Los cambios aditivos se consideran no disruptivos y pueden desplegarse sin aumentar la versión.

Fin de la documentación