netgescon-master/netgescon-laravel/docs/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

Authorization: Bearer YOUR_API_TOKEN

Ottenere un Token

POST /api/auth/login
Content-Type: application/json

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

📚 Endpoints Principali

🏢 Stabili

# Lista stabili
GET /api/stabili

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

# Crea stabile
POST /api/stabili

👥 Soggetti/Condomini

# Lista soggetti
GET /api/soggetti

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

# Crea soggetto
POST /api/soggetti

🏪 Fornitori

# Lista fornitori
GET /api/fornitori

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

# Crea fornitore
POST /api/fornitori

💰 Contabilità

# Movimenti contabili
GET /api/movimenti

# Bilanci
GET /api/bilanci/{stabile_id}

# Ripartizioni
GET /api/ripartizioni

📝 Formato Richieste

Headers Richiesti

Accept: application/json
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

Esempio Creazione Stabile

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)

{
    "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)

{
    "status": "error",
    "message": "Errore di validazione",
    "errors": {
        "nome": ["Il campo nome è obbligatorio"],
        "codice_fiscale": ["Il codice fiscale non è valido"]
    }
}

Lista con Paginazione

{
    "status": "success",
    "data": [...],
    "pagination": {
        "current_page": 1,
        "last_page": 10,
        "per_page": 20,
        "total": 200
    }
}

🔍 Filtri e Ricerca

Query Parameters

# 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

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

Payload Webhook

{
    "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

{
    "test_stabile_id": 999,
    "test_user_id": 888,
    "test_movimento_id": 777
}

📋 SDKs e Librerie

JavaScript/TypeScript

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

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

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')}