# API_ENDPOINTS.md - NetGesCon Laravel
**Creato**: 8 Luglio 2025  
**Ultimo aggiornamento**: 8 Luglio 2025  
**Versione**: 1.0

## 🎯 **SCOPO DEL DOCUMENTO**
Documentazione completa degli endpoint API REST, struttura request/response, autenticazione e permessi per facilitare lo sviluppo frontend e integrazioni esterne.

---

## 🔐 **AUTENTICAZIONE E SICUREZZA**

### **Sistema Autenticazione**:
- **Laravel Sanctum**: Token-based authentication
- **Multi-Database**: Route automatiche per database amministratore
- **Permissions**: Controllo granulare basato su ruoli

### **Headers Richiesti**:
```http
Authorization: Bearer {sanctum_token}
Content-Type: application/json
Accept: application/json
X-Database-Context: {codice_amministratore}  # Per multi-database
```

### **Struttura Response Standard**:
```json
{
    "success": true,
    "data": { /* payload */ },
    "message": "Operazione completata con successo",
    "errors": {},
    "meta": {
        "current_page": 1,
        "total": 100,
        "per_page": 15
    }
}
```

---

## 🏢 **GESTIONE AMMINISTRATORI**

### **GET /api/amministratori** - Lista amministratori
```http
GET /api/amministratori?page=1&per_page=15&search=rossi&active=true

Response 200:
{
    "success": true,
    "data": [
        {
            "id": 1,
            "codice_amministratore": "ADM8K3L9",
            "nome_completo": "Mario Rossi",
            "nome_amministratore": "Mario",
            "cognome_amministratore": "Rossi",
            "codice_fiscale": "RSSMRA80A01H501Z",
            "email": "mario.rossi@example.com",
            "telefono": "+39 339 1234567",
            "database_attivo": "netgescon_ADM8K3L9",
            "stato_sincronizzazione": "distribuito",
            "stabili_count": 5,
            "created_at": "2025-01-15T10:30:00Z",
            "updated_at": "2025-07-08T14:20:00Z"
        }
    ],
    "meta": { /* pagination */ }
}
```

### **POST /api/amministratori** - Crea amministratore
```http
POST /api/amministratori

Request:
{
    "nome_amministratore": "Mario",
    "cognome_amministratore": "Rossi",
    "codice_fiscale": "RSSMRA80A01H501Z",
    "partita_iva": "12345678901",
    "email": "mario.rossi@example.com",
    "telefono": "+39 339 1234567",
    "indirizzo": "Via Roma 123, 00100 Roma RM"
}

Response 201:
{
    "success": true,
    "data": {
        "id": 1,
        "codice_amministratore": "ADM8K3L9",  # Auto-generato
        "database_attivo": "netgescon_ADM8K3L9",  # Auto-creato
        /* altri campi */
    },
    "message": "Amministratore creato con successo"
}
```

### **GET /api/amministratori/{id}** - Dettaglio amministratore
### **PUT /api/amministratori/{id}** - Aggiorna amministratore
### **DELETE /api/amministratori/{id}** - Elimina amministratore (soft delete)

---

## 🏠 **GESTIONE STABILI**

### **GET /api/stabili** - Lista stabili
```http
GET /api/stabili?amministratore_id=1&citta=Roma&con_ascensore=true

Response 200:
{
    "success": true,
    "data": [
        {
            "id": 1,
            "codice_stabile": "STB5H7K1",
            "denominazione": "Condominio Villa Verde",
            "indirizzo_completo": "Via dei Pini 45, 00100 Roma (RM)",
            "indirizzo": "Via dei Pini 45",
            "cap": "00100",
            "citta": "Roma",
            "provincia": "RM",
            "codice_fiscale_stabile": "CVVERD123456789",
            "amministratore": {
                "id": 1,
                "nome_completo": "Mario Rossi",
                "codice_amministratore": "ADM8K3L9"
            },
            "configurazione": {
                "numero_rate_anno": 4,
                "mese_inizio_esercizio": 1,
                "ascensore": true,
                "posti_auto_totali": 15,
                "codice_destinatario_sdi": "XYZ1234",
                "pec_stabile": "villa.verde@pec.it"
            },
            "statistiche": {
                "unita_totali": 20,
                "unita_occupate": 18,
                "unita_libere": 2,
                "unita_in_affitto": 5
            },
            "created_at": "2025-01-15T10:30:00Z"
        }
    ]
}
```

### **POST /api/stabili** - Crea stabile
```http
POST /api/stabili

Request:
{
    "amministratore_id": 1,
    "denominazione": "Condominio Villa Verde",
    "indirizzo": "Via dei Pini 45",
    "cap": "00100",
    "citta": "Roma",
    "provincia": "RM",
    "codice_fiscale_stabile": "CVVERD123456789",
    "configurazione": {
        "ascensore": true,
        "numero_rate_anno": 4,
        "posti_auto_coperti": 10,
        "posti_auto_scoperti": 5,
        "codice_destinatario_sdi": "XYZ1234",
        "pec_stabile": "villa.verde@pec.it"
    }
}

Response 201:
{
    "success": true,
    "data": {
        "id": 1,
        "codice_stabile": "STB5H7K1",  # Auto-generato
        /* campi completi */
    },
    "message": "Stabile creato con successo"
}
```

---

## 🏘️ **GESTIONE UNITÀ IMMOBILIARI**

### **GET /api/unita-immobiliari** - Lista unità
```http
GET /api/unita-immobiliari?stabile_id=1&tipo_utilizzo=abitazione&stato=libera

Response 200:
{
    "success": true,
    "data": [
        {
            "id": 1,
            "denominazione_completa": "Interno 1 - Piano 1°",
            "denominazione": "Interno 1",
            "piano": "1°",
            "stabile": {
                "id": 1,
                "denominazione": "Condominio Villa Verde",
                "codice_stabile": "STB5H7K1"
            },
            "catasto": {
                "numero_vani": 4.5,
                "superficie_catastale": 85.50,
                "categoria_catastale": "A/2",
                "classe_catastale": "3",
                "rendita_catastale": 450.00
            },
            "millesimi": {
                "proprieta": 45.5,
                "scale": 50.0,
                "ascensore": 45.5,
                "riscaldamento": 48.0,
                "totale": 189.0
            },
            "tipo_utilizzo": {
                "id": 1,
                "denominazione": "Abitazione",
                "codice": "ABIT"
            },
            "stato_occupazione": "occupata",
            "proprietari": [
                {
                    "id": 1,
                    "nome_completo": "Giovanni Bianchi",
                    "codice_anagrafica": "ANAP4UQ2",
                    "percentuale_proprieta": 100.00,
                    "tipo_diritto": "proprieta"
                }
            ],
            "contratto_attivo": null,
            "created_at": "2025-01-15T10:30:00Z"
        }
    ]
}
```

### **POST /api/unita-immobiliari** - Crea unità
```http
POST /api/unita-immobiliari

Request:
{
    "stabile_id": 1,
    "denominazione": "Interno 1",
    "piano": "1°",
    "tipo_utilizzo_id": 1,
    "catasto": {
        "numero_vani": 4.5,
        "superficie_catastale": 85.50,
        "categoria_catastale": "A/2",
        "classe_catastale": "3",
        "rendita_catastale": 450.00
    },
    "millesimi": {
        "proprieta": 45.5,
        "scale": 50.0,
        "ascensore": 45.5,
        "riscaldamento": 48.0,
        "acqua_calda": 45.5,
        "pulizie": 50.0
    },
    "stato_occupazione": "libera"
}

Response 201:
{
    "success": true,
    "data": { /* unità creata con tutti i campi */ },
    "message": "Unità immobiliare creata con successo"
}
```

---

## 👥 **GESTIONE ANAGRAFICA**

### **GET /api/anagrafica** - Lista anagrafica
```http
GET /api/anagrafica?search=rossi&tipo=persona_fisica&amministratore_id=1&ruolo=proprietario

Response 200:
{
    "success": true,
    "data": [
        {
            "id": 1,
            "codice_anagrafica": "ANAP4UQ2",
            "tipo_soggetto": "persona_fisica",
            "nome_completo": "Giovanni Bianchi",
            "nome": "Giovanni",
            "cognome": "Bianchi",
            "codice_fiscale": "BNCGNN75C15H501K",
            "indirizzo_completo": "Via Verdi 10, 20100 Milano (MI)",
            "contatti": [
                {
                    "tipo_contatto": "email",
                    "valore": "giovanni.bianchi@email.com",
                    "principale": true,
                    "usa_per_comunicazioni": true
                },
                {
                    "tipo_contatto": "cellulare",
                    "valore": "+39 348 1234567",
                    "etichetta": "Mobile",
                    "usa_per_emergenze": true
                }
            ],
            "ruoli": {
                "proprietario": true,
                "inquilino": false,
                "fornitore": false
            },
            "statistiche": {
                "unita_possedute": 2,
                "percentuale_totale_proprieta": 150.00,
                "contratti_locazione_attivi": 0
            },
            "attivo": true,
            "created_at": "2025-01-15T10:30:00Z"
        }
    ]
}
```

### **POST /api/anagrafica** - Crea anagrafica
```http
POST /api/anagrafica

Request:
{
    "amministratore_id": 1,
    "tipo_soggetto": "persona_fisica",
    "nome": "Giovanni",
    "cognome": "Bianchi",
    "codice_fiscale": "BNCGNN75C15H501K",
    "data_nascita": "1975-03-15",
    "luogo_nascita": "Milano",
    "sesso": "M",
    "indirizzo_residenza": "Via Verdi 10",
    "cap_residenza": "20100",
    "citta_residenza": "Milano",
    "provincia_residenza": "MI",
    "contatti": [
        {
            "tipo_contatto": "email",
            "valore": "giovanni.bianchi@email.com",
            "principale": true,
            "usa_per_comunicazioni": true
        },
        {
            "tipo_contatto": "cellulare",
            "valore": "+39 348 1234567",
            "etichetta": "Mobile",
            "usa_per_emergenze": true
        }
    ],
    "privacy_consenso": true
}

Response 201:
{
    "success": true,
    "data": {
        "id": 1,
        "codice_anagrafica": "ANAP4UQ2",  # Auto-generato
        /* dati completi anagrafica + contatti */
    },
    "message": "Anagrafica creata con successo"
}
```

---

## 🏠 **GESTIONE DIRITTI REALI**

### **GET /api/diritti-reali** - Lista diritti
```http
GET /api/diritti-reali?unita_id=1&anagrafica_id=1&tipo_diritto=proprieta&attivi=true

Response 200:
{
    "success": true,
    "data": [
        {
            "id": 1,
            "unita_immobiliare": {
                "id": 1,
                "denominazione_completa": "Interno 1 - Piano 1°",
                "stabile": {
                    "denominazione": "Condominio Villa Verde"
                }
            },
            "anagrafica": {
                "id": 1,
                "nome_completo": "Giovanni Bianchi",
                "codice_anagrafica": "ANAP4UQ2"
            },
            "tipo_diritto": "proprieta",
            "quota_formattata": "1000/1000",
            "percentuale_formattata": "100.00%",
            "quota_numeratore": 1000,
            "quota_denominatore": 1000,
            "percentuale_proprieta": 100.00,
            "dati_legali": {
                "data_acquisizione": "2020-05-15",
                "atto_notarile": "Dott. Mario Verdi - Rep. 1234/2020",
                "data_trascrizione": "2020-05-20",
                "numero_trascrizione": "12345/2020"
            },
            "validita": {
                "data_inizio": "2020-05-15",
                "data_fine": null,
                "attivo": true
            },
            "created_at": "2020-05-15T10:30:00Z"
        }
    ]
}
```

### **POST /api/diritti-reali** - Crea diritto
```http
POST /api/diritti-reali

Request:
{
    "unita_immobiliare_id": 1,
    "anagrafica_id": 1,
    "tipo_diritto": "proprieta",
    "percentuale_proprieta": 100.00,  # Auto-calcola quota
    "data_acquisizione": "2020-05-15",
    "atto_notarile": "Dott. Mario Verdi - Rep. 1234/2020",
    "data_trascrizione": "2020-05-20",
    "numero_trascrizione": "12345/2020",
    "data_inizio_validita": "2020-05-15"
}

Response 201:
{
    "success": true,
    "data": { /* diritto creato completo */ },
    "message": "Diritto reale registrato con successo"
}
```

---

## 📄 **GESTIONE CONTRATTI LOCAZIONE**

### **GET /api/contratti-locazione** - Lista contratti
```http
GET /api/contratti-locazione?unita_id=1&stato=attivo&in_scadenza=60

Response 200:
{
    "success": true,
    "data": [
        {
            "id": 1,
            "numero_contratto": "LOC/2024/001",
            "unita_immobiliare": {
                "id": 1,
                "denominazione_completa": "Interno 1 - Piano 1°"
            },
            "locatore": {
                "id": 1,
                "nome_completo": "Giovanni Bianchi",
                "codice_anagrafica": "ANAP4UQ2"
            },
            "conduttore": {
                "id": 2,
                "nome_completo": "Maria Verdi",
                "codice_anagrafica": "ANAMV123"
            },
            "durata": {
                "data_stipula": "2024-01-15",
                "data_inizio": "2024-02-01",
                "data_fine": "2028-01-31",
                "durata_formattata": "48 mesi",
                "stato_scadenza": "attivo"
            },
            "economici": {
                "canone_mensile": 850.00,
                "spese_condominiali": 120.00,
                "canone_totale": 970.00,
                "deposito_cauzionale": 1700.00
            },
            "tipo_contratto": "libero",
            "stato_contratto": "attivo",
            "ripartizione_spese": {
                "spese_a_carico_inquilino": true,
                "riscaldamento_a_carico": true,
                "acqua_a_carico": true
            },
            "created_at": "2024-01-15T10:30:00Z"
        }
    ]
}
```

### **POST /api/contratti-locazione** - Crea contratto
```http
POST /api/contratti-locazione

Request:
{
    "unita_immobiliare_id": 1,
    "locatore_id": 1,
    "conduttore_id": 2,
    "numero_contratto": "LOC/2024/001",
    "data_stipula": "2024-01-15",
    "data_inizio": "2024-02-01",
    "data_fine": "2028-01-31",
    "tipo_contratto": "libero",
    "canone_mensile": 850.00,
    "deposito_cauzionale": 1700.00,
    "spese_condominiali": 120.00,
    "configurazione_spese": {
        "spese_a_carico_inquilino": true,
        "riscaldamento_a_carico": true,
        "acqua_a_carico": true
    }
}

Response 201:
{
    "success": true,
    "data": { /* contratto creato completo */ },
    "message": "Contratto di locazione registrato con successo"
}
```

---

## 💰 **GESTIONE CONTABILE**

### **GET /api/movimenti-contabili** - Lista movimenti
```http
GET /api/movimenti-contabili?stabile_id=1&tipo=entrata&dal=2024-01-01&al=2024-12-31&stato=registrato

Response 200:
{
    "success": true,
    "data": [
        {
            "id": 1,
            "codice_movimento": "MOV7K3L9",
            "data_movimento": "2024-03-15",
            "tipo_movimento": "entrata",
            "causale": "Versamento rate condominiali - Marzo 2024",
            "importo": 2450.00,
            "importo_formattato": "€ 2.450,00",
            "stabile": {
                "id": 1,
                "denominazione": "Condominio Villa Verde"
            },
            "fornitore_cliente": {
                "id": 1,
                "nome_completo": "Giovanni Bianchi",
                "codice_anagrafica": "ANAP4UQ2"
            },
            "categoria": {
                "id": 1,
                "denominazione": "Rate condominiali",
                "codice": "RATE"
            },
            "stato": {
                "stato_movimento": "registrato",
                "prima_nota": false,
                "data_conferma": "2024-03-16",
                "utente_conferma": "Mario Rossi"
            },
            "pagamento": {
                "metodo_pagamento": "bonifico",
                "numero_conto": "IT60X0542811101000000123456",
                "numero_documento": "BONIF/2024/0234"
            },
            "allegati_count": 1,
            "created_at": "2024-03-15T10:30:00Z"
        }
    ],
    "summary": {
        "totale_entrate": 45600.00,
        "totale_uscite": 23400.00,
        "saldo": 22200.00
    }
}
```

### **POST /api/movimenti-contabili** - Crea movimento
```http
POST /api/movimenti-contabili

Request:
{
    "stabile_id": 1,
    "data_movimento": "2024-03-15",
    "tipo_movimento": "entrata",
    "causale": "Versamento rate condominiali - Marzo 2024",
    "importo": 2450.00,
    "categoria_id": 1,
    "fornitore_cliente_id": 1,
    "metodo_pagamento": "bonifico",
    "numero_documento": "BONIF/2024/0234",
    "numero_conto": "IT60X0542811101000000123456",
    "prima_nota": true
}

Response 201:
{
    "success": true,
    "data": {
        "id": 1,
        "codice_movimento": "MOV7K3L9",  # Auto-generato
        /* movimento completo */
    },
    "message": "Movimento contabile registrato con successo"
}
```

---

## 📊 **ENDPOINT STATISTICHE E REPORT**

### **GET /api/dashboard/statistiche** - Dashboard generale
```http
GET /api/dashboard/statistiche?amministratore_id=1&anno=2024

Response 200:
{
    "success": true,
    "data": {
        "amministratore": {
            "stabili_totali": 5,
            "unita_totali": 120,
            "proprietari_totali": 85,
            "inquilini_totali": 35
        },
        "contabile": {
            "entrate_anno": 145600.00,
            "uscite_anno": 98400.00,
            "saldo_anno": 47200.00,
            "prima_nota_da_confermare": 12
        },
        "locazioni": {
            "contratti_attivi": 35,
            "contratti_in_scadenza_60gg": 3,
            "canoni_totali_mensili": 28500.00
        },
        "trend_mensili": [
            {
                "mese": "2024-01",
                "entrate": 12400.00,
                "uscite": 8200.00,
                "saldo": 4200.00
            }
            /* altri mesi */
        ]
    }
}
```

### **GET /api/report/primo-nota** - Report prima nota
### **GET /api/report/situazione-patrimoniale** - Situazione patrimoniale
### **GET /api/report/scadenze-contratti** - Contratti in scadenza

---

## 🛡️ **GESTIONE ERRORI**

### **Errori Standard**:
```json
// 400 - Bad Request
{
    "success": false,
    "message": "Dati di input non validi",
    "errors": {
        "codice_fiscale": ["Il codice fiscale non è valido"],
        "email": ["Il campo email è obbligatorio"]
    }
}

// 401 - Unauthorized
{
    "success": false,
    "message": "Token di autenticazione non valido o scaduto"
}

// 403 - Forbidden
{
    "success": false,
    "message": "Non hai i permessi per accedere a questa risorsa"
}

// 404 - Not Found
{
    "success": false,
    "message": "Risorsa non trovata"
}

// 422 - Unprocessable Entity
{
    "success": false,
    "message": "Errore di validazione",
    "errors": {
        "percentuale_proprieta": ["La somma delle percentuali non può superare 100%"]
    }
}

// 500 - Internal Server Error
{
    "success": false,
    "message": "Errore interno del server",
    "debug": "Database connection failed" // Solo in development
}
```

---

## 🎯 **RIFERIMENTI INCROCIATI**

- **DATABASE_SCHEMA.md**: ↗️ Schema tabelle e relazioni per struttura response
- **DATA_ARCHITECTURE.md**: ↗️ Modelli Eloquent e relazioni per payload
- **PROGRESS_LOG.md**: ↗️ Stato implementazione endpoint e test eseguiti
- **UI_COMPONENTS.md**: *(DA CREARE)* ↗️ Binding API con componenti frontend
- **DEVELOPMENT_IDEAS.md**: *(DA CREARE)* ↗️ Endpoint avanzati e ottimizzazioni future

---

*Documento creato: 8 Luglio 2025 - Guida completa API REST NetGesCon*