Documentazione API e Cosa Chiedere al Gruppo

sistema Laravel: Espone degli endpoint API REST per ricevere i dati.

Noi abbiamo già definito gli endpoint API principali per l'importazione e i relativi payload JSON attesi. 


Endpoint URL e Metodi HTTP:

POST /api/v1/import/condominio
POST /api/v1/import/fornitore
POST /api/v1/import/anagrafica (Definiti in routes/api.php e gestiti da ImportController)
Formato Dati Richiesto (Payload JSON Esempi): Li abbiamo definiti nella nostra precedente conversazione. Ad esempio, per /api/v1/import/condominio:

json
{
    "id_stabile": 123,
    "denominazione": "Condominio Primavera",
    "indirizzo": "Via dei Girasoli 10",
    "cap": "00100",
    "citta": "Roma",
    "pr": "RM",
    "codice_fisc": "9876543210987654",
    "cf_amministratore": "RSSMRA80A01H501X",
    "note1": "Note aggiuntive"
}

Devi fornire esempi simili per fornitore e anagrafica basati sulle validazioni e sulla logica in ImportController.

Campi Obbligatori e Opzionali: Questi sono definiti nelle regole di validazione dentro ImportController (es. 'id_stabile' => ['required', 'integer']).

Risposta Attesa: I metodi in ImportController restituiscono risposte JSON come:

Successo: {'message': 'Condominio importato...', 'data': { ... }} (status 200 o 201)
Errore di validazione: Struttura JSON di Laravel con gli errori (status 422)
Non trovato/Non autorizzato: {'message': '...'} (status 404, 403)
Autenticazione: Tramite Bearer Token (Authorization: Bearer <TOKEN>). 
Il token viene generato dall'amministratore nella dashboard del sistema Laravel.

Conferma di Comprensione degli Endpoint Esistenti:

"Avete ricevuto e compreso la documentazione degli endpoint API /api/v1/import/condominio, /api/v1/import/fornitore e /api/v1/import/anagrafica, inclusi URL, metodo POST, payload JSON attesi e meccanismo di autenticazione con Bearer Token?"
Mappatura Dati dal Vecchio GESCON:

"La struttura delle tabelle del vecchio GESCON (che avete elencato e che è nel file GESCON schermate\tabelle per importazioni dati da GESCON.txt) è la base da cui estrarrete i dati. Avete bisogno di chiarimenti su come mappare i campi specifici di quelle tabelle ai campi dei payload JSON che i nostri endpoint si aspettano?"
Ad esempio, per condomin.nom_cond come deve essere mappato a anagrafiche.ragione_sociale o nome/cognome? (Attualmente il nostro ImportController per anagrafica usa nom_cond per ragione_sociale).
Gestione delle Dipendenze nell'Importazione:

"Quale sarà l'ordine di importazione dei dati? Ad esempio, è necessario importare prima un Condominio (da stabili) prima di poter importare un'Anagrafica (da condomin) e associarla a un'unità immobiliare di quel condominio (usando condomin.id_stabile per trovare il condominio_id nuovo)?"
Questo è cruciale perché l'endpoint importAnagrafica cerca un Condominio esistente tramite old_id (che corrisponde a stabili.id_stabile).
Necessità di Endpoint per Altre Entità:

"Le tabelle del vecchio GESCON includono anche rate, incassi, singolo_anno_assemblee. Avete bisogno di endpoint API specifici per importare anche questi dati? Se sì, per ognuna:
Quali campi sono essenziali?
Come si relazionano alle entità già importate (condomini, anagrafiche)?" (Se servono, dovremo creare nuovi metodi in ImportController e nuove rotte API).
Dettagli sulla Tabella parti_comuni_amministratore:

"La tabella parti_comuni_amministratore del vecchio GESCON sembra contenere i dettagli dello studio di amministrazione. Questi dati nel nuovo sistema sono gestiti nella tabella amministratori (collegata a users). L'importazione di questi dati avviene implicitamente quando un utente con ruolo amministratore si registra o viene creato, o c'è necessità di un import massivo anche per questi?"
Nota: Attualmente non abbiamo un endpoint API per importare amministratori perché la logica è che un Amministratore (utente) usa le API per importare i suoi dati condominiali.
Chiarimenti sui Campi Specifici (se necessario):

Ad esempio, in condomin, ci sono E_mail_condomino e E_mail_inquilino. L'attuale importAnagrafica usa solo E_mail_condomino. Se E_mail_inquilino deve generare un'anagrafica separata di tipo 'inquilino' per la stessa unità, il payload e la logica dell'API andranno adattati.


Assicurati che il tuo gruppo comprenda che gli old_id (es. id_stabile, id_fornitore, id_cond) che inviano nei payload JSON sono gli ID primari delle rispettive tabelle nel vecchio database GESCON. 
Il sistema Laravel li userà per updateOrCreate e per mantenere un riferimento all'origine del dato.


****************************
Ecco come puoi organizzare le informazioni da fornire al gruppo che prepara **maschere** e **archivi** per l’importazione dati via API REST.

---

## 1. **Struttura delle tabelle principali e relazioni**

### **Tabelle principali (esempio):**
- **condomin**: anagrafica condomini
- **stabili**: dettagli stabili/edifici
- **fornitori**: anagrafica fornitori
- **rate**: rate condominiali
- **incassi**: pagamenti ricevuti
- **parti_comuni_amministratore**: amministratori
- **singolo_anno_assemblee**: assemblee annuali

### **Esempio di struttura e relazioni**

| Tabella     | Campo              | Tipo         | Descrizione                        | Relazione                |
|-------------|--------------------|--------------|------------------------------------|--------------------------|
| condomin    | id                 | int          | PK Condominio                      |                          |
| condomin    | denominazione      | varchar      | Nome condominio                    |                          |
| condomin    | indirizzo          | varchar      | Indirizzo                          |                          |
| condomin    | amministratore_id  | int          | FK amministratore                  | parti_comuni_amministratore.id |
| stabili     | id                 | int          | PK Stabile                         |                          |
| stabili     | condominio_id      | int          | FK condominio                      | condomin.id              |
| fornitori   | id                 | int          | PK Fornitore                       |                          |
| fornitori   | nome               | varchar      | Nome fornitore                     |                          |
| rate        | id                 | int          | PK Rata                            |                          |
| rate        | condominio_id      | int          | FK condominio                      | condomin.id              |
| incassi     | id                 | int          | PK Incasso                         |                          |
| incassi     | rata_id            | int          | FK rata                            | rate.id                  |
| parti_comuni_amministratore | id | int         | PK Amministratore                  |                          |
| singolo_anno_assemblee | id      | int          | PK Assemblea                       |                          |
| singolo_anno_assemblee | condominio_id | int    | FK condominio                      | condomin.id              |

> **Nota:**  
> Le relazioni FK (foreign key) sono solo indicative: verifica i nomi reali dei campi nel tuo database!

---

## 2. **Cosa fornire al gruppo che prepara le maschere/archivi**

- **Per ogni tabella**:
    - Nome tabella
    - Elenco campi (nome, tipo, descrizione)
    - Chiavi primarie e chiavi esterne (relazioni)
    - Esempio dati (opzionale, aiuta molto)

- **Schema delle relazioni** (come sopra, tabella con FK)

- **Eventuali vincoli** (es: un condominio può avere più stabili, una rata appartiene a un condominio, ecc.)

---

## 3. **Cosa chiedere al gruppo che prepara le API REST**

Chiedi di fornirti per ogni endpoint:

- **Endpoint URL** (es: `/api/v1/import/condominio`)
- **Metodo HTTP** (POST, PUT, ecc.)
- **Formato dati richiesto** (JSON, con esempio payload)
- **Campi obbligatori e opzionali**
- **Risposta attesa** (esempio di risposta JSON)
- **Gestione errori** (come vengono restituiti gli errori)
- **Eventuali vincoli di autenticazione** (token, Bearer, ecc.)

---

## 4. **Esempio di documentazione da inviare**

### **Tabella: condomin**
| Campo            | Tipo      | Descrizione         | Relazione/FK                |
|------------------|-----------|---------------------|-----------------------------|
| id               | int       | PK                  |                             |
| denominazione    | varchar   | Nome condominio     |                             |
| indirizzo        | varchar   | Indirizzo           |                             |
| amministratore_id| int       | FK amministratore   | parti_comuni_amministratore |

### **Endpoint API**
- **URL:** `/api/v1/import/condominio`
- **Metodo:** POST
- **Payload esempio:**
    ```json
    {
      "id": 1,
      "denominazione": "Condominio Alfa",
      "indirizzo": "Via Roma 1",
      "amministratore_id": 2
    }
    ```
- **Risposta attesa:**
    ```json
    { "ok": true, "id": 1 }
    ```

---

## 5. **Checklist per il gruppo API**

Chiedi di fornirti:
- Elenco endpoint disponibili
- Per ogni endpoint: payload richiesto, risposta attesa, campi obbligatori
- Specifica delle relazioni tra i dati (es: come collegare rate e incassi)
- Specifica autenticazione (token, Bearer, ecc.)

---

**Se vuoi, puoi incollare qui la struttura di una tabella (output di DESCRIBE) e ti aiuto a scrivere la documentazione dettagliata per il gruppo!**


*******************************************************

Chiamate API REST per l'Importazione
L'autenticazione avviene tramite un token API che l'amministratore (utente con ruolo amministratore) genera dalla sua dashboard.

Header Comuni per tutte le richieste API:

Authorization: Bearer <IL_TUO_TOKEN_API>
Accept: application/json
Content-Type: application/json (per le richieste POST con payload JSON)
Endpoint e Payload Esempio:

Importa Condominio (Stabile)

Endpoint: POST /api/v1/import/condominio
Controller: App\Http\Controllers\Api\ImportController@importCondominio
Payload JSON Esempio (basato su stabili e validazione controller):
json
{
    "id_stabile": 123, // old_id da stabili.id_stabile
    "cod_stabile": "STAB001", // opzionale, per stabili.cod_stabile
    "denominazione": "Condominio Primavera", // per stabili.denominazione
    "indirizzo": "Via dei Girasoli 10", // per stabili.indirizzo
    "cap": "00100", // per stabili.cap
    "citta": "Roma", // per stabili.citta
    "pr": "RM", // per stabili.pr
    "codice_fisc": "9876543210987654", // per stabili.codice_fisc
    "cf_amministratore": "RSSMRA80A01H501X", // per stabili.cf_amministratore
    "note1": "Note aggiuntive sul condominio" // per stabili.note1
}
Importa Fornitore

Endpoint: POST /api/v1/import/fornitore
Controller: App\Http\Controllers\Api\ImportController@importFornitore
Payload JSON Esempio (basato su fornitori e validazione controller):
json
{
    "id_fornitore": 45, // old_id da fornitori.id_fornitore
    "cognome": "Rossi", // per fornitori.cognome (o parte della ragione sociale)
    "nome": "Mario", // per fornitori.nome (o parte della ragione sociale)
    "indirizzo": "Via Garibaldi 50", // per fornitori.indirizzo
    "cap": "20100", // per fornitori.cap
    "citta": "Milano", // per fornitori.citta
    "pr": "MI", // per fornitori.pr
    "p_iva": "01234567890", // per fornitori.p_iva
    "cod_fisc": "RSSMRA75B01F205Z", // per fornitori.cod_fisc
    "Indir_Email": "mario.rossi@example.com", // per fornitori.Indir_Email
    "Cellulare": "3331234567", // per fornitori.Cellulare
    "PEC_Fornitore": "mario.rossi@pec.example.com" // per fornitori.PEC_Fornitore
}
Nota: Nel controller importFornitore, ragione_sociale è costruita concatenando cognome e nome. Se hai una ragione_sociale completa nel vecchio DB, potresti volerla passare direttamente e adattare il controller.
Importa Anagrafica (e associazione a Unità)

Endpoint: POST /api/v1/import/anagrafica
Controller: App\Http\Controllers\Api\ImportController@importAnagrafica
Payload JSON Esempio (basato su condomin e validazione controller):
json
{
    "id_cond": 789, // old_id da condomin.id_cond
    "nom_cond": "Bianchi Luigi (Prop.)", // per condomin.nom_cond
    "ind": "Via Roma 1, Apt 3", // per condomin.ind (indirizzo dell'anagrafica, se diverso da quello dell'unità)
    "cap": "00150", // per condomin.cap
    "citta": "Roma", // per condomin.citta
    "pr": "RM", // per condomin.pr
    "E_mail_condomino": "luigi.bianchi@example.com", // per condomin.E_mail_condomino
    // "E_mail_inquilino": "paolo.verdi@example.com", // Se hai un campo separato e vuoi creare un'altra anagrafica
    "id_stabile": 123, // ID del vecchio stabile (stabili.id_stabile) a cui questa anagrafica/unità appartiene
    "scala": "A", // per condomin.scala (per identificare/creare l'UnitaImmobiliare)
    "int": "3", // per condomin.int (per identificare/creare l'UnitaImmobiliare)
    "tipo_pr": "PR" // per condomin.tipo_pr (es. PR, IN, US per mappare a proprietario, inquilino, usufruttuario)
    // Aggiungere altri campi se necessari e validati:
    // "cod_fisc": "BNCLGU...",
    // "telefono": "06112233"
}


***************************************************************************************************
 php artisan tinker
Psy Shell v0.12.8 (PHP 8.3.6 — cli) by Justin Hileman
> $user = App\Models\User::where('email', 'michele@nethome.it')->first();
= App\Models\User {#6339
    id: 2,
    name: "michele barone",
    email: "michele@nethome.it",
    email_verified_at: null,
    #password: "$2y$12$ndylLy53XFHexUNGNtA4xe5kKgO9DOxTm6n7YFia9sdvshKU4bVDq",
    role: "admin",
    #remember_token: null,
    created_at: "2025-06-16 00:00:59",
    updated_at: "2025-06-16 00:01:39",
  }


> echo $user->createToken('import-token')->plainTextToken;
1|yBuaEHKsPtKRcVrQlsfnTWjKTES3Z2e9mwmfVeX0524f371d⏎
>

curl -X POST http://127.0.0.1:8000/api/v1/import/condominio \
-H "Authorization: yBuaEHKsPtKRcVrQlsfnTWjKTES3Z2e9mwmfVeX0524f371d" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "id_stabile": 148,
    "denominazione": "SUPERCONDOMINIO MILIZIE 3",
    "indirizzo": "VIALE DELLE MILIZIE 3",
    "cap": "00192",
    "citta": "Roma",
    "pr": "RM",
    "codice_fisc": "97487690584",
    "cf_amministratore": "TRDCCL74T52H501R"
}'


curl -X POST http://127.0.0.1:8000/api/v1/import/fornitore \
-H "Authorization: yBuaEHKsPtKRcVrQlsfnTWjKTES3Z2e9mwmfVeX0524f371d" \
-H "Content-Type: application/json" \
-d '{
    "id_fornitore": 1,
    "cognome": "Idraulica Rossi",
    "nome": "SNC",
    "p_iva": "01234567890"
}'


sto  cercando di inserire un valore nella colonna `cod_fisc_amministratore` nella tabella `condomini`,  
ma questa colonna **non esiste** nella tabella.

 Token API creato con successo! Copia il token: 3|yVt3r764wovEAyrenzwDSqGnbNmFuPgG7Q1pmIfz915f1605 