# Integrazione Company OpenAPI

## Panoramica

Questa integrazione permette di cercare e archiviare dati dettagliati sulle aziende italiane tramite l'API di Company OpenAPI. Il sistema può raccogliere informazioni complete inclusi dati anagrafici, bilanci, soci e molto altro.

## Configurazione

### Variabili d'Ambiente

Aggiungi le seguenti variabili al file `.env`:

```env
OPENAPI_BASE_URL=https://company.openapi.com
OPENAPI_API_KEY=your_api_key_here
```

### Database

Esegui le migration per creare le tabelle necessarie:

```bash
npm run migrate
```

Questo creerà tre tabelle:
- `companies` - Dati principali delle aziende
- `company_balance_sheets` - Bilanci annuali
- `company_share_holders` - Soci delle aziende

## Struttura Dati

### Tabella Companies

Memorizza i dati principali dell'azienda:
- **Identificativi**: Codice Fiscale, Partita IVA, Ragione Sociale
- **Indirizzo**: Sede legale completa con coordinate GPS
- **Codici ATECO**: 2007 e 2022
- **Forma Giuridica**: Codice e descrizione
- **Contatti**: PEC, Codice SDI
- **Status**: Attività, REA, CCIAA

### Tabella Company Balance Sheets

Memorizza i bilanci annuali con:
- Anno di riferimento
- Numero dipendenti
- Fatturato
- Patrimonio netto
- Capitale sociale
- Costo del personale
- Totale attivo
- Stipendio lordo medio

### Tabella Company Share Holders

Memorizza i soci con:
- Ragione sociale (se azienda)
- Nome e cognome (se persona fisica)
- Codice fiscale/Partita IVA
- Percentuale di partecipazione

## API Endpoints

### 1. Cerca Aziende (Preview)

Ricerca aziende senza salvare nel database:

```http
GET /api/companies/search-openapi
```

**Query Parameters:**
- `atecoCode` - Codice ATECO (es: "4619")
- `legalFormCode` - Forma giuridica (es: "SR" per SRL)
- `minEmployees` - Numero minimo dipendenti
- `maxEmployees` - Numero massimo dipendenti
- `activityStatus` - Status attività (default: "ATTIVA")
- `province` - Provincia (es: "MI", "RM")
- `region` - Regione (es: "LOMBARDIA")
- `limit` - Numero risultati (default: 50, max: 100)
- `offset` - Offset per paginazione

**Esempio:**
```bash
curl -X GET "http://localhost:3003/api/companies/search-openapi?atecoCode=4619&minEmployees=5&province=LT&limit=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Risposta:**
```json
{
  "success": true,
  "data": [
    {
      "taxCode": "02776720597",
      "vatCode": "02776720597",
      "companyName": "OSANNA ADVISORS SRL",
      "address": {...},
      "balanceSheets": {...},
      "shareHolders": [...]
    }
  ],
  "total": 10,
  "params": {...}
}
```

### 2. Cerca e Salva Aziende

Ricerca aziende e le salva nel database:

```http
POST /api/companies/search-and-save
```

**Body (JSON):**
```json
{
  "atecoCode": "4619",
  "legalFormCode": "SR",
  "minEmployees": 5,
  "activityStatus": "ATTIVA",
  "province": "LT",
  "limit": 50
}
```

**Esempio:**
```bash
curl -X POST "http://localhost:3003/api/companies/search-and-save" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "atecoCode": "4619",
    "minEmployees": 5,
    "province": "MI",
    "limit": 50
  }'
```

**Risposta:**
```json
{
  "success": true,
  "total": 50,
  "savedCount": 48,
  "errorCount": 2,
  "companies": [...],
  "message": "48 aziende salvate con successo, 2 errori"
}
```

### 3. Lista Aziende Salvate

Ottieni tutte le aziende dal database:

```http
GET /api/companies
```

**Query Parameters:**
- `page` - Numero pagina (default: 1)
- `limit` - Risultati per pagina (default: 50)
- `province` - Filtra per provincia
- `atecoCode` - Filtra per codice ATECO
- `activityStatus` - Filtra per status
- `search` - Cerca per nome, CF o P.IVA

**Esempio:**
```bash
curl -X GET "http://localhost:3003/api/companies?province=MI&page=1&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 4. Dettaglio Azienda

Ottieni tutti i dettagli di un'azienda:

```http
GET /api/companies/:id
```

**Esempio:**
```bash
curl -X GET "http://localhost:3003/api/companies/123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 5. Azienda per Codice Fiscale

```http
GET /api/companies/tax-code/:taxCode
```

**Esempio:**
```bash
curl -X GET "http://localhost:3003/api/companies/tax-code/02776720597" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 6. Statistiche Aziende

```http
GET /api/companies/stats
```

**Risposta:**
```json
{
  "success": true,
  "data": {
    "totalCompanies": 1250,
    "activeCompanies": 1180,
    "inactiveCompanies": 70,
    "topProvinces": [
      {"province": "MI", "count": 350},
      {"province": "RM", "count": 280}
    ],
    "topAtecoCategories": [...]
  }
}
```

### 7. Aggiorna Azienda

```http
PUT /api/companies/:id
```

**Body:**
```json
{
  "companyName": "Nuovo Nome SRL",
  "phone": "+39 02 1234567"
}
```

### 8. Elimina Azienda

```http
DELETE /api/companies/:id
```

## Casi d'Uso

### 1. Ricerca Aziende per Settore e Dimensione

Trova tutte le SRL nel settore commercio all'ingrosso con almeno 5 dipendenti:

```javascript
const params = {
  atecoCode: "4619",
  legalFormCode: "SR",
  minEmployees: 5,
  activityStatus: "ATTIVA",
  limit: 100
};

// Preview
const preview = await fetch('/api/companies/search-openapi?' + new URLSearchParams(params));

// Salva se i risultati sono buoni
const result = await fetch('/api/companies/search-and-save', {
  method: 'POST',
  body: JSON.stringify(params)
});
```

### 2. Ricerca Geografica

Trova aziende in una specifica provincia:

```javascript
const params = {
  province: "MI",
  activityStatus: "ATTIVA",
  minEmployees: 10,
  limit: 50
};
```

### 3. Analisi Bilanci

Ottieni aziende e analizza i loro bilanci:

```javascript
const companies = await fetch('/api/companies?province=MI&limit=100');

companies.data.forEach(company => {
  const lastBalance = company.balanceSheets[0];
  if (lastBalance && lastBalance.turnover > 1000000) {
    console.log(`${company.companyName}: €${lastBalance.turnover}`);
  }
});
```

### 4. Ricerca Prospect per Campagne DEM

Integrazione con il sistema DEM esistente:

```javascript
// 1. Cerca aziende target
const companies = await searchAndSaveCompanies({
  atecoCode: "4619",
  minEmployees: 5,
  province: "MI"
});

// 2. Crea contatti dalle aziende (se hanno PEC)
companies.forEach(async (company) => {
  if (company.pec) {
    await createContact({
      email: company.pec,
      company: company.companyName,
      source: 'openapi',
      customFields: {
        taxCode: company.taxCode,
        vatCode: company.vatCode,
        province: company.province
      }
    });
  }
});
```

## Codici ATECO Comuni

Alcuni codici ATECO utili:
- `4619` - Intermediari del commercio
- `6201` - Programmazione informatica
- `6202` - Consulenza informatica
- `4778` - Commercio al dettaglio
- `7022` - Consulenza aziendale

## Forme Giuridiche

Codici comuni:
- `SR` - Società a Responsabilità Limitata (SRL)
- `SP` - Società per Azioni (SPA)
- `NC` - Società in Nome Collettivo
- `SS` - Società Semplice
- `II` - Impresa Individuale

## Limiti e Best Practices

1. **Rate Limiting**: Rispetta i limiti dell'API OpenAPI
2. **Paginazione**: Usa `limit` e `offset` per grandi dataset
3. **Cache**: I dati salvati nel DB evitano chiamate ripetute
4. **Aggiornamenti**: Implementa job periodici per aggiornare i dati
5. **Filtri**: Usa filtri specifici per ridurre il numero di risultati

## Troubleshooting

### Errore: "OPENAPI_API_KEY non configurato"

Verifica che la variabile d'ambiente sia impostata correttamente nel file `.env`.

### Errore: "Errore chiamata OpenAPI"

Verifica:
- La connettività internet
- La validità dell'API key
- Il formato dei parametri di ricerca

### Tabelle non esistono

Esegui le migration:
```bash
npm run migrate
```

## Log

I log delle operazioni sono salvati in:
- `logs/app.log` - Log generale dell'applicazione
- Logger integrato Winston per tracciare tutte le operazioni

## Future Implementazioni

- [ ] Job automatico per aggiornamento dati aziende
- [ ] Export aziende in CSV/Excel
- [ ] Integrazione con sistema di scoring lead
- [ ] Dashboard analytics per dati aziende
- [ ] Notifiche per nuove aziende corrispondenti ai criteri
- [ ] Sincronizzazione automatica PEC -> Contatti DEM