Documentazione API esterna

L'integrazione basata su 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 sui dati
8. Comportamento del filtraggio
9. Modello dei permessi
10. Gestione degli errori
11. Pattern di integrazione
12. Stabilità e versionamento

1. Autenticazione

Tutte le richieste devono includere una chiave API nell'header 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 è associata a permessi specifici delle 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 pianificati come riunioni, chiamate e installazioni. Sola lettura.

Endpoint

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

Permesso richiesto: 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 nidificati

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

Permesso richiesto: 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 è ancora stato calcolato. latitude/longitude sono null se non è impostata alcuna posizione.

Oggetti nidificati

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

Permessi richiesti: 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 delle coordinate

• latitude e longitude devono essere sempre fornite insieme.
• Fornire solo una delle due coordinate genera un errore di convalida.
• 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/

Permesso richiesto: components_write

Tipi di componente

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

Modulo 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 modulo fotovoltaico vengono convalidati prima della creazione.

7. Convenzioni sui 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 vengono 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 del filtraggio

Regole generali

• Tutti i filtri sono facoltativi salvo diversa indicazione.
• Più filtri sono 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 convalida a seconda del tipo di campo.

Filtri per intervallo di date

Disponibili su 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 dei permessi

I permessi della chiave API sono configurati in modo indipendente per ciascuna risorsa:

10. Gestione degli errori

Formato dell'errore

Errore generale:

{
  "detail": "Messaggio di errore"
}

Errore di convalida a livello di campo:

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

Riferimento errori

Checklist di integrazione

Se riscontri errori, verifica:

1. La chiave API dispone dei permessi corretti sulla 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 l'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 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 con grandi volumi, preferisci filtri basati su ID invece delle ricerche testuali.
• Combina più filtri per ridurre la dimensione del set di risultati.
• Evita ricerche testuali troppo ampie su dataset di grandi dimensioni.

12. Stabilità e versionamento

Garanzie di stabilità

I seguenti elementi non cambieranno senza una migrazione versionata:

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

Soggetto a modifiche (non breaking)

• Filtri facoltativi (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 breaking introdurranno un nuovo namespace di endpoint:

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

Le modifiche additive sono considerate non breaking e possono essere distribuite senza un incremento di versione.

Fine della documentazione