• Descrizione
• Caratteristiche
• Architettura
• Prerequisiti
• Installazione
• Configurazione
• API Endpoints
• Esempi
• Testing
• Deployment
• Contribuire
• Licenza

Cotral Server API è un servizio backend TypeScript che funge da layer intermedio per le API ufficiali di Cotral (http://travel.mob.cotralspa.it:7777/beApp). Il servizio trasforma le risposte XML native in JSON strutturato e aggiunge funzionalità come la gestione delle fermate preferite tramite database SQLite.

• Ricerca fermate per località
• Ricerca paline per codice fermata, posizione GPS o percorso
• Monitoraggio transiti in tempo reale
• Tracking veicoli con posizioni GPS
• Gestione preferiti con persistenza su database SQLite
• Trasformazione XML→JSON automatica
• API RESTful con risposte JSON standardizzate
• Documentazione OpenAPI completa

• Ricerca paline nel raggio GPS personalizzabile
• Ricerca percorsi tra località di partenza e destinazione
• Sistema di fermate preferite multi-utente
• Informazioni dettagliate sui veicoli in servizio
• Calcolo ritardi e tempi di attesa

cotral-server-api/ ├── src/ │ ├── controllers/ # Controller per gestione richieste │ ├── services/ # Logica di business e integrazione API Cotral │ ├── routes/ # Definizione delle route Fastify │ ├── interfaces/ # TypeScript interfaces │ ├── utils/ # Funzioni di utilità │ ├── database.ts # Gestione connessione SQLite │ └── app.ts # Entry point dell'applicazione ├── database.sqlite # Database SQLite (generato automaticamente) ├── OpenAPI.yaml # Documentazione API Swagger/OpenAPI ├── package.json # Dipendenze e script └── README.md # Questo file 

• Node.js >= 14.x
• npm >= 6.x o yarn >= 1.x
• Git per clonare il repository

git clone https://github.com/ChromuSx/cotral-server-api.git cd cotral-server-api

npm install # oppure yarn install

npm run build

# Modalità sviluppo con hot-reload npm run dev # Modalità produzione npm start

Il server sarà disponibile su http://localhost:3000

Crea un file .env nella root del progetto (opzionale):

# Server PORT=3000 HOST=127.0.0.1 # Database DB_PATH=./database.sqlite # API Cotral (opzionale, usa i default se non specificato) COTRAL_BASE_URL=http://travel.mob.cotralspa.it:7777/beApp COTRAL_USER_ID=1BB73DCDAFA007572FC51E7407AB497C

curl -X GET "http://localhost:3000/stops/Roma"

Risposta:

[ { "codiceStop": "70101", "nomeStop": "ROMA - ANAGNINA", "localita": "ROMA", "coordX": 41.839722, "coordY": 12.601944 } ]

curl -X GET "http://localhost:3000/poles/position?latitude=41.8397&longitude=12.6019&range=0.01"

curl -X GET "http://localhost:3000/transits/70101A"

Risposta:

{ "pole": { "codicePalina": "70101A", "nomePalina": "ANAGNINA - Capolinea", "localita": "ROMA", "coordX": 41.839722, "coordY": 12.601944 }, "transits": [ { "idCorsa": "123456", "percorso": "ROMA - FRASCATI", "orarioPartenzaCorsa": "2024-01-15T14:30:00", "tempoTransito": "2024-01-15T14:35:00", "ritardo": "00:02:00", "automezzo": { "codice": "BUS001", "isAlive": true } } ] }

curl -X POST "http://localhost:3000/poles/favorites" \ -H "Content-Type: application/json" \ -d '{  "userId": 1,  "poleCode": "70101A",  "stopCode": 70101  }'

# Test endpoint base curl http://localhost:3000/ # Test con parametri query curl "http://localhost:3000/poles/70101?userId=1"

Importa il file OpenAPI.yaml in Postman per avere una collezione completa di tutti gli endpoint con esempi di richieste e risposte.

# Esegui i test (se configurati) npm test

1. Fork questo repository
2. Crea un nuovo Web Service su Render
3. Connetti il tuo repository GitHub
4. Configura:
   • Build Command: npm install
   • Start Command: npm start
5. Deploy

FROM node:16-alpine WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . EXPOSE 3000 CMD ["npm", "start"]

Build e run:

docker build -t cotral-api . docker run -p 3000:3000 cotral-api

Il progetto è compatibile con:

• Heroku
• Railway
• Fly.io
• DigitalOcean App Platform
• AWS Elastic Beanstalk

Contribuzioni, issues e feature requests sono benvenute.

1. Fork il progetto
2. Crea il tuo feature branch (git checkout -b feature/NuovaFunzionalita)
3. Commit delle modifiche (git commit -m 'Aggiunta nuova funzionalità')
4. Push al branch (git push origin feature/NuovaFunzionalita)
5. Apri una Pull Request

• Mantieni il codice TypeScript type-safe
• Aggiungi test per nuove funzionalità
• Aggiorna la documentazione OpenAPI quando aggiungi nuovi endpoint
• Segui le convenzioni di naming esistenti
• Commenta il codice solo dove necessario per chiarire logiche complesse

Questo progetto è completamente gratuito e open source. Se lo trovi utile e vuoi supportare il suo sviluppo continuo e gli aggiornamenti futuri, considera di fare una donazione. Il tuo supporto aiuta a mantenere vivo il progetto e mi motiva ad aggiungere nuove funzionalità e miglioramenti!

Ogni contributo, non importa quanto piccolo, è molto apprezzato! ❤️

Distribuito sotto licenza MIT. Vedi il file LICENSE per maggiori informazioni.

Giovanni Guarino
📧 Email: giovanni.guarino1999@gmail.com
🔗 GitHub: @ChromuSx