API Matricole

Versioni

L'endpoint matricole esiste in due versioni:

Versione	Path	Differenze principali
v1	/v1/matricola	Chiave POST = serialNumber (a_amtr_sn). Nessuna gestione merce in POST. Cliente obbligatorio.
v2	/v2/matricola	Chiave POST = codiceHost (a_amtr_codice_host). Gestisce merce (a_amtr_merce). Cliente opzionale.

Entrambe le versioni condividono lo stesso schema output per i GET.

Endpoint disponibili

Metodo	Path (v1/v2)	Descrizione
GET	/matricola	Lettura lista matricole (filtri: id, serialNumber, cliente, paginazione)
GET	/matricola/up	Lettura matricole aggiornate a partire da un sync id
POST	/matricola	Inserimento/aggiornamento batch matricole

v2 aggiunge il filtro codiceHost nel GET /.

---

Schema output — GET

MatricolaOutput

Campo	Tipo	Campo DB / Join	Note
id	integer	a_amtr_id	ID interno matricola
serialNumber	string	a_amtr_sn	Numero seriale
codice_host_modello	string	join ARPMODEL	Codice host modello
codice_modello	string	a_amtr_modello	Codice interno modello (sempre presente, indipendente dalla raccordatura in ARPMODEL)
codice_host_merce	string	join ARPMERCI	Codice host merce
codice_marca	string	a_amtr_marca	Marca della matricola
descrizione	string	a_amtr_des	Descrizione
codice_tipo	string	a_amtr_tip	Codice tipo matricola
tip	string	join ARPMTRTP	Descrizione tipo matricola
cliente	string	a_amtr_ana	Codice cliente interno (area)
cliente_host	string	join ARPANAGR (rana_codice_host)	Codice cliente nel sistema host esterno
inizio_garanzia	integer	a_amtr_gar_ini	Data inizio garanzia (epoch ms)
fine_garanzia	integer	a_amtr_gar_fin	Data fine garanzia (epoch ms)
anno_costr	integer	a_amtr_anno_costr	Anno di costruzione
utilizzatore	string	join APCRMANAGR	Codice host utilizzatore
fl_prototipo	string	a_amtr_fl_prototipo	Flag prototipo (1 char)
cod_azi_gruppo	string	join APGRPAZIEN	Codice host gruppo aziende
id_sincro	integer	a_amtr_id_sincro	ID di sincronizzazione
codice_host	string	a_amtr_codice_host	Codice host matricola
utilizzatore_nome	string	join APCRMANAGR	Nome utilizzatore
utilizzatore_localita	string	join APCRMANAGR	Localita' utilizzatore
utilizzatore_cap	string	join APCRMANAGR	CAP utilizzatore
utilizzatore_indirizzo	string	join APCRMANAGR	Indirizzo utilizzatore
utilizzatore_provincia	string	join APCRMANAGR	Provincia utilizzatore
utilizzatore_paese	string	join APCRMANAGR	Codice nazione utilizzatore

Le date garanzia vengono convertite da formato DB (YYYY-MM-DD) a epoch ms nel mapping di risposta.

Query string — GET /

Parametro	Tipo	Obbligatorio	Note
limit	integer	NO	Max risultati (default/max: 200)
page	integer	NO	Pagina (paginazione offset-based)
id	integer	NO	Filtro per ID matricola
serialNumber	string	NO	Filtro per serial number (match esatto)
codiceHost	string	NO	Filtro per codice host (solo v2)
cliente	string	NO	Filtro per codice cliente interno (a_amtr_ana)

Il GET / esclude le matricole cancellate (a_amtr_fl_canc <> 'C').

Query string — GET /up

Parametro	Tipo	Obbligatorio	Note
sync	integer	SI	ID sincronizzazione di partenza

Il GET /up filtra per a_amtr_agg_app = 'A' e esclude le matricole cancellate.

---

Schema input — POST

MatricolaInput (v1)

Campo	Tipo	Obbligatorio	Note
serialNumber	string	SI	Numero seriale (max 30 char) — chiave
codice_host_modello	string	NO	Codice host modello (max 30 char)
codice_host_cliente	string	SI	Codice host cliente (max 16 char)
descrizione	string	NO	Descrizione (max 1000 char)
anno_costr	integer	SI	Anno di costruzione
inizio_garanzia	integer	SI	Data inizio garanzia (epoch ms)
fine_garanzia	integer	SI	Data fine garanzia (epoch ms)
utilizzatore	string	NO	Codice host utilizzatore (max 16 char)
fl_prototipo	string	NO	Flag prototipo (max 1 char)
cod_azi_gruppo	string	NO	Codice host gruppo aziende (max 20 char)
cancellato	boolean	NO	Cancellazione logica (default false)

MatricolaInput (v2) — campi aggiuntivi

Campo	Tipo	Obbligatorio	Note
codiceHost	string	SI	Codice host matricola (max 30 char) — chiave
codice_host_merce	string	NO	Codice host merce (max 30 char)

In v2, codice_host_cliente e' opzionale (default stringa vuota).

---

Logica POST — Inserimento/Aggiornamento

Identificazione matricola

• v1: la chiave di deduplicazione e' serialNumber (a_amtr_sn)
• v2: la chiave di deduplicazione e' codiceHost (a_amtr_codice_host)

Flusso

1. Ricerca esistente: query su APASNMATRI per la chiave appropriata alla versione
2. Classificazione:
   • Nuovo: matricola non esistente → INSERT su APASNMATRI
   • Modificato: confronto dati → UPDATE su APASNMATRI
   • Cancellato: cancellato = true su una matricola esistente → UPDATE con a_amtr_fl_canc = 'C'
3. ID matricola: generato automaticamente con numericCodeGenerator

Tabella sorgente

La tabella principale e' APASNMATRI (PK: a_amtr_azienda, a_amtr_id_dispositivo, a_amtr_idd_prog, a_amtr_id).

Join (GET)

Tabella	Condizione	Tipo	Scopo
ARPANAGR	rana_azi = a_amtr_azienda AND rana_codana = a_amtr_ana	LEFT	Codice host cliente
APCRMANAGR	a_cra_azienda = a_amtr_azienda AND a_cra_id_dispositivo = 0 AND a_cra_idd_prog = 0 AND a_cra_cod = a_amtr_nom_uti	LEFT	Dati utilizzatore
ARPMTRTP	a_mtp_azi = a_amtr_azienda AND a_mtp_tip = a_amtr_tip	LEFT	Descrizione tipo
ARPMODEL	a_mod_azi = a_amtr_azienda AND a_mod_cod = a_amtr_modello	LEFT	Codice host modello
APGRPAZIEN	a_ao_azi_azi = a_amtr_azienda AND a_ao_azi_cod = a_amtr_grp_az_cod	LEFT	Codice host gruppo aziende
ARPMERCI	rmer_azi = a_amtr_azienda AND rmer_cm = a_amtr_merce	LEFT	Codice host merce

---

Risposta

200 OK

{
  "message": "OK"
}

400 Bad Request

Errore di validazione (schema TypeBox).

---

Note implementative

• L'ID matricola (a_amtr_id) e' generato automaticamente in inserimento tramite numericCodeGenerator
• Le date garanzia nel payload sono in formato epoch ms, convertite internamente a DATE PostgreSQL
• Il POST gestisce inserimento, aggiornamento e cancellazione logica in una singola transazione
• Limite max per risposta: 200 record