API Giacenze¶

Il modulo giacenze espone due gruppi di endpoint su path distinti, ciascuno con propria tabella di riferimento e chiave di aggregazione:

/v1/giacenze-cap -- giacenze per capoarea (tabella ARPSLMAG, chiave: agenzia)
/v1/giacenze -- giacenze per magazzino (tabella ARPARMAG, chiave: magazzino)

Entrambi i gruppi condividono la stessa struttura operativa: lettura, lettura incrementale e aggiornamento batch.

1. Giacenze Capoarea (`/v1/giacenze-cap`)¶

Tabella principale: ARPSLMAG JOIN: ARPAGENZ (agenzie), ARPMERCI (merci)

1.1 Endpoint disponibili¶

Metodo	Path	Descrizione
GET	`/v1/giacenze-cap`	Lettura giacenze (filtri: `codice_host_merce`, `codice_host_agenzia`, paginazione)
GET	`/v1/giacenze-cap/up`	Lettura giacenze aggiornate da un `sync` id
POST	`/v1/giacenze-cap`	Aggiornamento batch giacenze

1.2 Schema output -- GET¶

Campo	Tipo	Note
`gruppo`	string	Gruppo merce interno (`rpmsalc_gru`)
`sottogruppo`	string	Sottogruppo merce interno (`rpmsalc_sot`)
`codice`	integer	Codice merce interno (`rpmsalc_cod`)
`codice_interno_agenzia`	string	Codice interno agenzia (`rpmsalc_age`)
`giacenza`	number	Quantita' in giacenza
`impegnato`	number	Quantita' impegnata
`ordinato`	number	Quantita' ordinata
`prenotato`	number	Quantita' prenotata
`disponibile`	number	Quantita' disponibile
`codice_host_merce`	string	Codice merce nel sistema host (`rmer_cma`)
`codice_host_agenzia`	string	Codice agenzia nel sistema host (`rmag_codice_host`)
`sync`	integer	ID di sincronizzazione

1.3 Query string -- GET `/v1/giacenze-cap`¶

Parametro	Tipo	Obbligatorio	Note
`codice_host_merce`	string	NO	Filtra per codice merce host
`codice_host_agenzia`	string	NO	Filtra per codice agenzia host
`limit`	integer	NO	Max risultati (default/max: 2000)
`page`	integer	NO	Pagina (paginazione offset-based)

1.4 Query string -- GET `/v1/giacenze-cap/up`¶

Parametro	Tipo	Obbligatorio	Note
`sync`	integer	SI	Restituisce record con `sync` maggiore di questo valore

1.5 Schema input -- POST¶

Il body e' un array di oggetti (max 2000 elementi).

Campo	Tipo	Obbligatorio	Note
`codice_host_merce`	string	SI	Codice merce nel sistema host (max 30 char)
`codice_host_agenzia`	string	SI	Codice agenzia nel sistema host (max 10 char)
`giacenza`	number	NO	Quantita' in giacenza (default 0)
`impegnato`	number	NO	Quantita' impegnata (default 0)
`ordinato`	number	NO	Quantita' ordinata (default 0)
`prenotato`	number	NO	Quantita' prenotata (default 0)
`disponibile`	number	NO	Quantita' disponibile (default 0)

1.6 Logica POST¶

Raccordi: traduce codice_host_merce -> codice interno (getRaccordiMerci), codice_host_agenzia -> codice interno (getRaccordiAgenzie)
Confronto con esistenti: query su ARPSLMAG per i record con le stesse chiavi (gru, sot, cod, age)
Classificazione:
- Nuovi: record non esistente con almeno un valore diverso da 0 -> INSERT su ARPSLMAG
- Modificati: record esistente con valori diversi -> UPDATE su ARPSLMAG
- Record esistenti con valori invariati -> ignorati
- Record non esistenti con tutti i valori a 0 -> ignorati
Sincronizzazione: ogni INSERT/UPDATE riceve un id_sincro progressivo da getNextIdSincro

1.7 Endpoint interni (non documentati)¶

DELETE /v1/giacenze-cap -- Azzera tutte le giacenze non nulle (rpmsalc_giacenza, rpmsalc_impegnato, ecc.) aggiornando l'id_sincro. Richiede authProcPermission
POST /v1/giacenze-cap/sum_stock -- Calcola le giacenze aggregate per merce su ARPARMAG sommando da ARPSLMAG. Usa INSERT ... ON CONFLICT DO UPDATE. Richiede authProcPermission

2. Giacenze per Magazzino (`/v1/giacenze`)¶

Tabella principale: ARPARMAG JOIN: APCOGMAGAZ (magazzini), ARPMERCI (merci)

2.1 Endpoint disponibili¶

Metodo	Path	Descrizione
GET	`/v1/giacenze`	Lettura giacenze (filtri: `codice_host_merce`, `codice_host_magazzino`, paginazione)
GET	`/v1/giacenze/up`	Lettura giacenze aggiornate da un `sync` id
POST	`/v1/giacenze`	Aggiornamento batch giacenze

2.2 Schema output -- GET¶

Campo	Tipo	Note
`codice_interno_magazzino`	string	Codice interno magazzino (`a_armag_mag`)
`codice_host_magazzino`	string	Codice magazzino nel sistema host (`a_magz_codice_host`)
`codice_host_merce`	string	Codice merce nel sistema host (`rmer_cma`)
`codice_interno_merce`	string	Codice merce interno (`a_armag_merce`)
`giacenza`	number	Quantita' in giacenza
`impegnato`	number	Quantita' impegnata
`ordinato`	number	Quantita' ordinata
`prenotato`	number	Quantita' prenotata
`id_sincro`	integer	ID di sincronizzazione
`sn`	string[]	Lista numeri seriali associati effettivamente in giacenza nell'ubicazione (`arpsnmag` con `a_snm_fl_canc = ' '` AND `a_snm_stato <> 'U'`)

Visibilita' magazzini

Il GET restituisce solo magazzini con codice_host valorizzato (trim(a_magz_codice_host) <> ''). Magazzini senza codice host non compaiono nei risultati.

2.3 Query string -- GET `/v1/giacenze`¶

Parametro	Tipo	Obbligatorio	Note
`codice_host_merce`	string	NO	Filtra per codice merce host
`codice_host_magazzino`	string	NO	Filtra per codice magazzino host
`limit`	integer	NO	Max risultati (default/max: 2000)
`page`	integer	NO	Pagina (paginazione offset-based)

2.4 Query string -- GET `/v1/giacenze/up`¶

Parametro	Tipo	Obbligatorio	Note
`sync`	integer	SI	Restituisce record con `id_sincro` maggiore di questo valore

2.5 Schema input -- POST¶

Il body e' un array di oggetti (max 2000 elementi).

Campo	Tipo	Obbligatorio	Note
`codice_host_merce`	string	SI	Codice merce nel sistema host (max 30 char)
`codice_host_magazzino`	string	SI	Codice magazzino nel sistema host (max 16 char)
`giacenza`	number	NO	Quantita' in giacenza (default 0)
`sn`	string	NO	Numero seriale (max 30 char, default "")
`cancellato`	boolean	NO	Cancellazione logica (default false)

2.6 Logica POST¶

Il POST gestisce due flussi separati in base alla presenza del numero seriale.

Flusso senza seriale (`sn` vuoto)¶

Raccordi: traduce codice_host_merce -> codice interno (getRaccordiMerci), codice_host_magazzino -> codice interno (getRaccordiMagazzini)
Controllo duplicati: checkDuplicati verifica che non ci siano coppie (magazzino, merce) duplicate nel payload
Confronto con esistenti: query su ARPARMAG
Classificazione:
- Nuovi: record non esistente -> INSERT su ARPARMAG
- Modificati: record esistente con giacenza diversa -> UPDATE su ARPARMAG
- Cancellati: record esistente con cancellato = true -> UPDATE con giacenza = 0

Flusso con seriale (`sn` valorizzato)¶

Vincolo: giacenza deve essere 0 o 1
Confronto con esistenti: query su ARPSNMAG per chiave (merce, sn)
Casistiche:
- SN non esistente + giacenza 1 -> INSERT su ARPSNMAG, incremento giacenza su ARPARMAG
- SN esistente + cancellato -> UPDATE flag cancellazione su ARPSNMAG, decremento giacenza su ARPARMAG
- SN esistente + cambio magazzino -> UPDATE magazzino su ARPSNMAG, aggiornamento giacenze su ARPARMAG (decremento vecchio, incremento nuovo)
- SN non esistente + giacenza 0 o cancellato -> ignorato
Aggiornamento ARPARMAG: le variazioni di giacenza vengono accumulate in un contatore per coppia (magazzino, merce) e applicate in batch (INSERT per nuovi record, UPDATE per esistenti)

2.7 Tabelle coinvolte¶

Tabella	Ruolo
`ARPARMAG`	Giacenze aggregate per magazzino/merce
`ARPSNMAG`	Numeri seriali per merce/magazzino
`APCOGMAGAZ`	Anagrafica magazzini (raccordo codice host)
`ARPMERCI`	Anagrafica merci (raccordo codice host)

3. Note implementative¶

Tutte le operazioni POST sono eseguite in transazione (db.begin). In caso di errore, nessun dato viene scritto
Ogni INSERT/UPDATE aggiorna l'id_sincro progressivo, usato dagli endpoint /up per la sincronizzazione incrementale
Le UPDATE batch usano la sintassi FROM (VALUES ...) as updated_data (...) con TO_NUMBER per la conversione dei tipi
I raccordi (merci, magazzini, agenzie) vengono caricati una sola volta all'inizio della transazione
Il limite massimo per ogni chiamata e' 2000 elementi (GIACENZE_LIMIT)

4. Risposta¶

200 OK¶

{
  "message": "OK"
}

400 Bad Request¶

Errore di validazione (codice merce o magazzino/agenzia non trovato, duplicati nel payload).