Documentazione delle API esterne

L'integrazione basata sulla chiave API ti dà accesso a Calendario, Progetti, Clienti e Componenti. Questo ti offre la flessibilità di integrare i tuoi sistemi e automatizzare i processi.

Indice

1. Autenticazione
2. Paginazione
3. API del calendario
4. API dei progetti
5. API dei clienti
6. API dei componenti
7. Convenzioni dei dati
8. Comportamento dei filtri
9. Modello di autorizzazione
10. Gestione degli errori
11. Pattern di integrazione
12. Stabilità e versionamento

1. Autenticazione

Tutte le richieste devono includere una chiave API nell'intestazione della richiesta.

Authorization: Api-Key <raw_api_key>

Note: - Le chiavi API vengono create e gestite dai proprietari e dagli amministratori dell'azienda. - Ogni chiave è limitata a specifiche autorizzazioni sulle risorse. - Tutte le richieste sono automaticamente limitate all'azienda associata alla chiave API.

Errori di autenticazione

2. Paginazione

Gli endpoint di elenco (Calendario, Progetti, Clienti) usano la paginazione limit/offset.

Parametri

Struttura della risposta

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

Quando next è null, hai raggiunto l'ultima pagina.

3. API del calendario

Rappresenta eventi programmati come riunioni, telefonate e installazioni. Sola lettura.

Endpoint

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

Autorizzazione richiesta: calendar_read

Esempio di risposta

{
  "id": "7d0f4d55-3b66-4c71-a86d-2b0ef2fca6d5",
  "category": "meeting",
  "subject": "Sopralluogo iniziale",
  "description": "Discutere i requisiti di installazione e l'ispezione del tetto.",
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Via Principale 10, Varsavia",
    "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"
}

Riferimento dei campi

Valori della categoria

Oggetti annidati

Oggetto cliente:

Oggetto partecipante:

Filtri

Esempio:

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 dei progetti

Rappresenta i record di progetto relativi ai clienti (ad es. impianti fotovoltaici). Sola lettura.

Endpoint

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

Autorizzazione richiesta: projects_read

Esempio di risposta

{
  "id": "d8e22cb9-1d88-4a3d-a3fd-f954d1f23d59",
  "name": "Impianto fotovoltaico - ufficio di Varsavia",
  "address": "Aleje Jerozolimskie 120, Varsavia",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "client": {
    "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
    "name": "Solar Corp",
    "address": "Via Principale 10, Varsavia",
    "phone": "+48123456789",
    "is_open": true
  },
  "status": {
    "name": "In corso",
    "order": 2
  },
  "currency": {
    "code": "PLN",
    "name": "Złoty polacco"
  },
  "total_price": "42500.00",
  "payback_period": 8,
  "created": "2026-05-01T09:00:00Z",
  "updated": "2026-06-01T15:30:00Z"
}

Riferimento dei campi

total_price viene restituito come stringa decimale per preservare la precisione. payback_period è null se non è stato ancora calcolato. latitude/longitude sono null se non è impostata alcuna posizione.

Oggetti annidati

Oggetto stato:

Oggetto valuta:

Filtri

Esempio:

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

5. API dei clienti

Rappresenta le entità cliente. Supporta operazioni di lettura e scrittura.

Endpoint

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}/

Autorizzazioni richieste: clients_read (lettura), clients_write (scrittura)

Esempio di risposta

{
  "id": "4ab8e7cb-0a27-48f1-a0f6-6d6ecf5d8c6a",
  "name": "Solar Corp",
  "description": "Cliente commerciale interessato a un impianto fotovoltaico su tetto.",
  "address": "Via Principale 10, Varsavia",
  "latitude": 52.2297,
  "longitude": 21.0122,
  "phone": "+48123456789",
  "is_open": true,
  "created": "2026-05-01T10:15:00Z",
  "updated": "2026-06-01T08:45:30Z"
}

Riferimento dei campi

Crea cliente

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

{
  "name": "Nome cliente",
  "description": "Cliente commerciale",
  "address": "Indirizzo",
  "phone": "+48123456789",
  "latitude": 52.2297,
  "longitude": 21.0122
}

Aggiorna cliente

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

Includi solo i campi che vuoi aggiornare:

{
  "address": "Nuovo indirizzo 15, Varsavia",
  "phone": "+48987654321"
}

Regole sulle coordinate

• latitude e longitude devono sempre essere forniti insieme.
• Fornire solo una coordinata comporta un errore di validazione.
• Se non è impostata alcuna posizione, entrambi i campi vengono restituiti come null.

Filtri

6. API dei componenti

Crea componenti da utilizzare nei progetti. Sola scrittura.

Endpoint

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

Autorizzazione richiesta: components_write

Tipi di componente

Sono supportati tre tipi di componente: panel, inverter e other.

Pannello 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"
}

Inverter

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

Altro

{
  "type": "other",
  "name": "Sistema di montaggio",
  "unit": "pz",
  "net_unit_price": "50.00"
}

Risposta

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

Note

• I produttori vengono creati automaticamente se non esistono.
• L'unicità del produttore è limitata alla singola azienda.
• Tutti i campi specifici del pannello fotovoltaico vengono validati prima della creazione.

7. Convenzioni dei dati

ID

Tutti gli identificativi delle risorse sono stringhe UUID, stabili e globalmente univoche all'interno di un'azienda:

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

Timestamp

Tutti i campi datetime sono restituiti in formato ISO 8601, sempre in UTC:

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

Geolocalizzazione

Le coordinate si applicano a Clienti e Progetti. Sono memorizzate come un punto geografico e restituite come campi separati:

"latitude": 52.2297,
"longitude": 21.0122

Gestione dei valori null

I campi non impostati vengono restituiti come null — non vengono mai omessi dalla risposta.

8. Comportamento dei filtri

Regole generali

• Tutti i filtri sono opzionali salvo diversa indicazione.
• I filtri multipli vengono combinati con logica AND.
• I valori dei filtri multi-selezione (ad es. category) usano internamente la logica OR.
• I valori di filtro non validi restituiscono risultati vuoti o un errore di validazione a seconda del tipo di campo.

Filtri per intervallo di date

Disponibili in tutti gli endpoint:

Filtri di ricerca testuale

Corrispondenza parziale senza distinzione tra maiuscole e minuscole su name e phone:

?name=solar

Corrisponde a: "Solar Corp", "Il mio progetto fotovoltaico", ecc.

9. Modello di autorizzazione

Le autorizzazioni della chiave API sono configurate separatamente per ciascuna risorsa:

10. Gestione degli errori

Formato degli errori

Errore generale:

{
  "detail": "Messaggio di errore"
}

Errore di validazione a livello di campo:

{
  "field_name": ["Messaggio di errore"]
}

Riferimento agli errori

Elenco di controllo per l'integrazione

Se riscontri errori, verifica:

1. La chiave API dispone delle autorizzazioni corrette per la risorsa.
2. L'account dell'azienda è attivo.
3. Tutti i valori dei filtri (ID, ecc.) appartengono allo stesso ambito aziendale.

11. Pattern di integrazione

Strategia di sincronizzazione

L'approccio consigliato per sincronizzare i dati:

1. Recupera l'endpoint di elenco (paginato).
2. Memorizza id come riferimento esterno.
3. Usa il campo updated per le sincronizzazioni incrementali.

Gestione della paginazione

Scorri le pagine incrementando l'offset finché next non è 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

Sincronizzazione incrementale

Usa i filtri per data per recuperare solo i record modificati dall'ultima sincronizzazione:

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

Best practice di filtraggio

• Per sincronizzazioni ad alto volume, preferisci i filtri basati su ID (client, status) alle ricerche testuali.
• Combina più filtri per ridurre la dimensione del set di risultati.
• Evita ricerche testuali troppo generiche su dataset di grandi dimensioni.

12. Stabilità e versionamento

Garanzie stabili

Quanto segue non cambierà senza una migrazione versionata:

• URL degli endpoint
• Nomi dei campi
• Formato UUID
• Struttura della paginazione
• Schema di autenticazione

Soggetto a modifiche (retrocompatibili)

• Filtri opzionali (possono essere aggiunti nuovi filtri)
• Arricchimento della risposta (possono essere aggiunti nuovi campi)

Politica di versionamento

Al momento nell'URL non è esposta alcuna versione esplicita. Le modifiche incompatibili introdurranno un nuovo namespace degli endpoint:

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

Le modifiche additive sono considerate retrocompatibili e possono essere distribuite senza incrementare la versione.

Fine della documentazione