netgescon-master/docs/02-architettura-laravel/guide/api-guide.md

# 🔌 NetGesCon - API Guide

## 📋 Panoramica API

NetGesCon fornisce API RESTful per l'integrazione con sistemi esterni e lo sviluppo di moduli aggiuntivi.

## 🔐 Autenticazione

### API Token
```http
Authorization: Bearer YOUR_API_TOKEN
```

### Ottenere un Token
```http
POST /api/auth/login
Content-Type: application/json

{
    "email": "user@example.com", 
    "password": "password",
    "device_name": "mobile_app"
}
```

## 📚 Endpoints Principali

### 🏢 Stabili
```http
# Lista stabili
GET /api/stabili

# Dettaglio stabile
GET /api/stabili/{id}

# Crea stabile
POST /api/stabili
```

### 👥 Soggetti/Condomini
```http
# Lista soggetti
GET /api/soggetti

# Dettaglio soggetto
GET /api/soggetti/{id}

# Crea soggetto
POST /api/soggetti
```

### 🏪 Fornitori
```http
# Lista fornitori
GET /api/fornitori

# Dettaglio fornitore
GET /api/fornitori/{id}

# Crea fornitore
POST /api/fornitori
```

### 💰 Contabilità
```http
# Movimenti contabili
GET /api/movimenti

# Bilanci
GET /api/bilanci/{stabile_id}

# Ripartizioni
GET /api/ripartizioni
```

## 📝 Formato Richieste

### Headers Richiesti
```http
Accept: application/json
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN
```

### Esempio Creazione Stabile
```http
POST /api/stabili
Content-Type: application/json

{
    "nome": "Condominio Rossi",
    "indirizzo": "Via Roma 123",
    "citta": "Milano",
    "cap": "20100",
    "codice_fiscale": "12345678901",
    "amministratore_id": 1
}
```

## 📤 Formato Risposte

### Successo (200/201)
```json
{
    "status": "success",
    "data": {
        "id": 1,
        "nome": "Condominio Rossi",
        "indirizzo": "Via Roma 123",
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
    },
    "message": "Stabile creato con successo"
}
```

### Errore (400/422/500)
```json
{
    "status": "error",
    "message": "Errore di validazione",
    "errors": {
        "nome": ["Il campo nome è obbligatorio"],
        "codice_fiscale": ["Il codice fiscale non è valido"]
    }
}
```

### Lista con Paginazione
```json
{
    "status": "success",
    "data": [...],
    "pagination": {
        "current_page": 1,
        "last_page": 10,
        "per_page": 20,
        "total": 200
    }
}
```

## 🔍 Filtri e Ricerca

### Query Parameters
```http
# Paginazione
GET /api/stabili?page=2&per_page=50

# Filtri
GET /api/stabili?citta=Milano&attivo=1

# Ricerca
GET /api/soggetti?search=Rossi

# Ordinamento
GET /api/fornitori?sort=nome&order=asc
```

## 📊 Webhook Events

### Eventi Disponibili
- `stabile.created`
- `stabile.updated`
- `soggetto.created`
- `movimento.created`
- `pagamento.completed`

### Configurazione Webhook
```http
POST /api/webhooks
{
    "url": "https://your-app.com/webhook",
    "events": ["stabile.created", "pagamento.completed"],
    "secret": "your_webhook_secret"
}
```

### Payload Webhook
```json
{
    "event": "stabile.created",
    "data": {
        "id": 1,
        "nome": "Condominio Rossi",
        ...
    },
    "timestamp": "2024-01-01T00:00:00Z",
    "signature": "sha256=..."
}
```

## 🔒 Permessi e Rate Limiting

### Livelli di Accesso
- **Guest**: Solo lettura dati pubblici
- **User**: Accesso ai propri dati
- **Admin**: Accesso completo
- **Super Admin**: Accesso sistema + API management

### Rate Limiting
- **Guest**: 60 richieste/minuto
- **User**: 100 richieste/minuto  
- **Admin**: 200 richieste/minuto
- **Super Admin**: Unlimited

## 🧪 Testing

### Ambiente di Test
```
Base URL: https://api-test.netgescon.com
Token di Test: test_token_12345
```

### Dati di Test
```json
{
    "test_stabile_id": 999,
    "test_user_id": 888,
    "test_movimento_id": 777
}
```

## 📋 SDKs e Librerie

### JavaScript/TypeScript
```javascript
npm install @netgescon/api-client

import { NetGesConAPI } from '@netgescon/api-client';

const api = new NetGesConAPI({
    baseURL: 'https://api.netgescon.com',
    token: 'your_token'
});

const stabili = await api.stabili.list();
```

### PHP
```php
composer require netgescon/api-client

use NetGesCon\ApiClient;

$api = new ApiClient([
    'base_uri' => 'https://api.netgescon.com',
    'token' => 'your_token'
]);

$stabili = $api->stabili()->list();
```

## 🐛 Gestione Errori

### Codici di Stato
- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `422` - Validation Error
- `429` - Rate Limit Exceeded
- `500` - Internal Server Error

### Retry Logic
```javascript
const retryRequest = async (requestFn, maxRetries = 3) => {
    for (let i = 0; i < maxRetries; i++) {
        try {
            return await requestFn();
        } catch (error) {
            if (error.status !== 429 && i === maxRetries - 1) {
                throw error;
            }
            await delay(Math.pow(2, i) * 1000); // Exponential backoff
        }
    }
};
```

## 📞 Supporto API

- **Documentazione Interattiva**: `/api/docs` (Swagger/OpenAPI)
- **Status Page**: `/api/status`
- **Changelog**: `/api/changelog`
- **Support**: api-support@netgescon.com

---
*Ultimo aggiornamento: ${new Date().toLocaleDateString('it-IT')}*