Documentación de la API externa

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

Tabla de contenidos

1. Autenticación
2. Paginación
3. API de calendario
4. API de proyectos
5. API de clientes
6. API de componentes
7. Convenciones de datos
8. Comportamiento de los filtros
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 se limita a permisos de recursos específicos. - 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, Clientes) utilizan 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 de calendario

Representa eventos programados como reuniones, llamadas e instalaciones. 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": "Initial Site Visit",
  "description": "Discuss installation requirements and roof inspection.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Main Street 10, Warsaw",
    "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 vinculados a 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": "Solar Installation - Warsaw Office",
  "address": "Aleje Jerozolimskie 120, Warsaw",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Main Street 10, Warsaw",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "In Progress",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Polish Złoty"
  },
  "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 establecido una ubicación.

Objetos anidados

Objeto estado:

Objeto 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": "Commercial customer interested in a rooftop PV installation.",
  "address": "Main Street 10, Warsaw",
  "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": "Client Name",
  "description": "Commercial customer",
  "address": "Address",
  "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 deseas actualizar:

{
  "address": "New Address 15, Warsaw",
  "phone": "+48987654321"
}

Reglas de coordenadas

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

Filtros

6. API de componentes

Crea componentes para utilizarlos en proyectos. Solo escritura.

Endpoint

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

Permiso requerido: components_write

Tipos de componentes

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

Panel fotovoltaico

{
  "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": "Mounting System",
  "unit": "pcs",
  "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 por empresa.
• Todos los campos específicos del panel se validan antes de crear.

7. Convenciones de datos

Identificadores

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 los filtros

Reglas generales

• Todos los filtros son opcionales, salvo que se indique lo contrario.
• Varios filtros se combinan con lógica AND.
• Los valores de filtros 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 distinguir mayúsculas y minúsculas en name y phone:

?name=solar

Coincide con: "Solar Corp", "My Solar Project", 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": "Error message"
}

Error de validación a nivel de campo:

{
  "field_name": ["Error message"]
}

Referencia de errores

Lista de comprobació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 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.

Manejo 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 modificados desde tu última sincronización:

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

Mejores 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 de estabilidad

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

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

Sujeto a cambios (sin ruptura de compatibilidad)

• 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 ninguna 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 incrementar la versión.

Fin de la documentación