# DPass API V2.1 — Opzioni abbonamento per parcometri

## Scopo

L'endpoint consente a un parcometro autorizzato di inviare una targa e ricevere i piani acquistabili per:

- prima attivazione di un titolo già approvato dall'ufficio;
- rinnovo di un titolo già attivato almeno una volta.

Gli abbonamenti a libera vendita sono sempre esclusi. La chiamata è read-only: non crea periodi e non registra pagamenti.

## Endpoint

```text
POST /api/v2/parking-meters/subscription-options
```

Autenticazione:

```http
Authorization: Bearer <TOKEN>
Accept: application/json
Content-Type: application/json
```

## Richiesta

```json
{
  "plate": "AB123CD",
  "municipality_code": "anacapri",
  "terminal_code": "PM001"
}
```

`municipality_code` può essere omesso quando la credenziale è associata a un solo Comune. `terminal_code` è facoltativo e viene registrato nel payload del log API.

## Risposta

```json
{
  "success": true,
  "request_id": "c1ef195a-3410-48f9-a335-b05081126a3c",
  "ok": true,
  "api_version": "2.1",
  "result_code": "OPTIONS_AVAILABLE",
  "message": "Piani di abbonamento disponibili.",
  "eligible": true,
  "plate": "AB123CD",
  "municipality": {
    "code": "anacapri",
    "name": "Anacapri"
  },
  "terminal_code": "PM001",
  "timezone": "Europe/Rome",
  "generated_at": "2026-09-17T16:25:00+02:00",
  "operation": "renewal",
  "subscriptions_count": 1,
  "options_count": 2,
  "entitlements_count": 2,
  "tariffe": [
    {
      "codice_tariffa": "101",
      "importo_eurocent": 2000,
      "scadenza": "16:25 04/11/2026",
      "descrizione": "RESIDENTE MENSILE",
      "jolly_info": ""
    },
    {
      "codice_tariffa": "102",
      "importo_eurocent": 5000,
      "scadenza": "16:25 04/01/2027",
      "descrizione": "RESIDENTE TRIMEST",
      "jolly_info": ""
    }
  ]
}
```

La `scadenza` è la scadenza futura prevista dopo il pagamento del singolo piano:

- titolo attivo: la **data** deriva dalla scadenza corrente + durata del piano, mentre l'**ora** è quella della consultazione;
- titolo scaduto o mai attivato: data e ora derivano dalla consultazione + durata del piano.

L'istante della consultazione viene acquisito una sola volta: `generated_at` e tutte le `scadenza` della stessa risposta usano quindi la stessa ora e lo stesso minuto. L'orario storico dell'ultimo periodo non viene riutilizzato.

Il valore definitivo sarà ricalcolato, nella successiva API di acquisizione del pagamento, usando la data e ora effettiva dell'incasso trasmessa dal Parking Collector.

## Dati tariffa

| Campo | Regola |
|---|---|
| `codice_tariffa` | stringa di 3 cifre; `000` riservato; univoca nel Comune |
| `importo_eurocent` | intero da 1 a 999999 |
| `scadenza` | esattamente `HH:MM GG/MM/YYYY` |
| `descrizione` | massimo 20 caratteri, maiuscole/numeri/spazi |
| `jolly_info` | stringa vuota in questa versione |

## Esiti funzionali

La mancanza di un abbonamento acquistabile non è un errore tecnico e restituisce HTTP 200 con `eligible: false` e `tariffe: []`.

Possibili `result_code`:

- `OPTIONS_AVAILABLE`
- `SUBSCRIPTION_NOT_FOUND`
- `DIRECT_PURCHASE_NOT_SUPPORTED`
- `PLATE_NOT_ACTIVE`
- `AUTHORIZATION_NOT_STARTED`
- `SUBSCRIPTION_SUSPENDED`
- `SUBSCRIPTION_REVOKED`
- `AUTHORIZATION_EXPIRED`
- `APPLICATION_NOT_APPROVED`
- `FUTURE_RENEWAL_ALREADY_PRESENT`
- `RENEWAL_NOT_ALLOWED`
- `NO_PARKING_METER_PLANS`
- `MULTIPLE_SUBSCRIPTIONS_FOUND`

## Sicurezza

La credenziale API è vincolata al tenant e ai Comuni autorizzati. Sono applicati eventuali limiti IP, rate limit e registrazione completa di richiesta, risposta, durata ed esito. La risposta non contiene dati personali dell'intestatario.