API Clienti

Endpoint disponibili

Metodo	Path	Descrizione
GET	/v1/cliente	Lettura lista clienti (filtri: codice_interno, rag_soc, paginazione)
GET	/v1/cliente/up	Lettura clienti aggiornati a partire da un sync id
POST	/v1/cliente	Inserimento/aggiornamento batch clienti
POST	/v1/cliente/gruppo_sconto	Inserimento gruppi sconto per cliente

---

Schema output — GET

ClienteOutput

Campo	Tipo	Note
codice_interno	string	Codice interno anagrafica AREA
codice_padre	string	Codice interno del cliente padre
rag_soc	string	Ragione sociale
indirizzo	string	Indirizzo
localita	string	Localita'
provincia	string	Provincia (2 char)
cap	string	CAP
email	string	Email
tel	string	Telefono
nazione	string	Codice nazione (3 char)
fax	string	Fax
cofi	string	Codice fiscale
piva	string	Partita IVA
rating	string	Rating cliente
grpStat1	string	Gruppo statistico 1
grpStat2	string	Gruppo statistico 2
grpStat3	string	Gruppo statistico 3
fido	number	Fido concesso
sync	integer	ID di sincronizzazione
cancellato	boolean	true se cancellato logicamente (rana_val = 'C')
codice_host	string	Codice host del cliente
codice_host_padre	string	Codice host del cliente padre
codice_host_agenzia	string	Codice host dell'agenzia
codice_host_pagamento	string	Codice host del pagamento
codice_host_azienda_gruppo	string	Codice host del gruppo aziende
codice_host_zona	string	Codice host della zona
codice_host_agente	string	Codice host dell'agente
codice_host_tipo_cliente	string	Codice host del tipo cliente
tip_pag	string	Tipo pagamento
cod_pag	string	Codice pagamento
conto_anagrafico	string	Conto anagrafico
area_tecnica	string	Area tecnica

Query string — GET /

Parametro	Tipo	Obbligatorio	Note
limit	integer	NO	Max risultati (default/max: 500)
page	integer	NO	Pagina (paginazione offset-based)
codice_interno	string	NO	Filtro per codice interno (match esatto)
rag_soc	string	NO	Filtro per ragione sociale (ILIKE %...%)

Il GET / esclude i clienti cancellati (rana_val <> 'C').

Query string — GET /up

Parametro	Tipo	Obbligatorio	Note
sync	integer	SI	ID sincronizzazione di partenza

Il GET /up restituisce anche i clienti cancellati (per consentire la sincronizzazione della cancellazione).

---

Schema input — POST /v1/cliente

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

ClienteInput

Campo	Tipo	Obbligatorio	Note
codice_host	string	SI	Chiave univoca nel sistema host (max 16 char)
rag_soc	string	NO	Ragione sociale (max 80 char)
indirizzo	string	NO	Indirizzo (max 50 char)
localita	string	NO	Localita' (max 50 char)
provincia	string	NO	Provincia (max 2 char)
cap	string	NO	CAP (max 10 char)
email	string	NO	Email (max 80 char)
tel	string	NO	Telefono (max 20 char)
nazione	string	NO	Codice nazione (max 3 char)
fax	string	NO	Fax (max 20 char)
cofi	string	NO	Codice fiscale (max 16 char)
piva	string	NO	Partita IVA (max 11 char)
rating	string	NO	Rating (max 20 char)
grpStat1	string	NO	Gruppo statistico 1 (max 20 char)
grpStat2	string	NO	Gruppo statistico 2 (max 20 char)
grpStat3	string	NO	Gruppo statistico 3 (max 20 char)
fido	number	NO	Fido (default 0)
cancellato	boolean	NO	Cancellazione logica (default false)
codice_host_padre	string	NO	Codice host del cliente padre (max 16 char)
codice_host_agenzia	string	NO	Codice host dell'agenzia (max 10 char)
codice_host_pagamento	string	NO	Codice host del pagamento (max 10 char)
codice_host_azienda_gruppo	string	NO	Codice host del gruppo aziende (max 20 char)
codice_host_zona	string	NO	Codice host della zona (max 20 char)
codice_host_agente	string	NO	Codice host dell'agente (max 20 char)
codice_host_tipo_cliente	string	NO	Codice host del tipo cliente (max 30 char)
tip_pag	string	NO	Tipo pagamento (max 1 char)
cod_pag	string	NO	Codice pagamento (max 2 char)
codice_host_old	string	NO	Codice host precedente per migrazione BMS (max 20 char)

---

Logica POST — Inserimento/Aggiornamento

Identificazione cliente

Il codice_host e' la chiave primaria esterna. Se non trovato, viene tentata una ricerca tramite codice_host_old con i prefissi OCMI-, IRTE-, MARA-, SCOV- (migrazione BMS/Ocmis). In caso di match, il codice host viene aggiornato.

Flusso

1. Deduplicazione: checkDuplicati sul payload
2. Ricerca esistenti: query su ARPANAGR per codice_host e codice_host_old
3. Validazione raccordi: agenzia, pagamento, gruppo aziende, agente, zona, tipo cliente — ognuno viene cercato nelle rispettive tabelle di raccordo
4. Classificazione:
   • Nuovo: cliente non esistente → INSERT su ARPANAGR + INSERT su APCRMANAGR (CRM)
   • Modificato: confronto campo per campo → UPDATE su ARPANAGR. Se cambiati i campi CRM → UPDATE anche su APCRMANAGR
   • Cancellato: cancellato = true su un cliente esistente → UPDATE con rana_val = 'C' + a_cra_fl_canc = 'C'
5. Codice interno: generato automaticamente con multiCodeGenerator (formato: 1 lettera + 5 numeri, es. A00001)

Tabelle coinvolte

Tabella	Operazione	Note
ARPANAGR	INSERT / UPDATE	Anagrafica principale clienti
APCRMANAGR	INSERT / UPDATE	Anagrafica CRM (subset campi, nominativo)

Raccordi utilizzati

Campo input	Funzione raccordo	Tabella di lookup
codice_host_agenzia	getRaccordiAgenzie	ARPAGENZ
codice_host_pagamento	getRaccordiPagamenti	ARPTABELLE (CP)
codice_host_azienda_gruppo	getRaccordiGruppoAziende	APGRPAZIEN
codice_host_zona	getRaccordiZone	ARPZONEC
codice_host_agente	getRaccordiAgenti	ARPAGENT
codice_host_tipo_cliente	getRaccordiTipiCliente	ARPTABELLE (84)
codice_host_padre	getRaccordiClienti	ARPANAGR

---

POST /v1/cliente/gruppo_sconto

Schema input

Array di oggetti:

Campo	Tipo	Obbligatorio	Note
codice_host	string	SI	Codice host del cliente
codice_gruppo_sconto	string[]	SI	Lista dei codici gruppo sconto da associare

Logica

1. Il cliente viene cercato tramite getRaccordiClienti
2. I gruppi sconto non ancora esistenti vengono creati in ARPGRUPPISCONTO
3. Le associazioni esistenti non piu' presenti nel payload vengono cancellate logicamente (a_ags_val = 'C')
4. Le nuove associazioni vengono inserite in ARPANAGRGS (con upsert: se gia' esistente e cancellata, viene riattivata)

---

Campi auto-assegnati (POST clienti)

Campo DB	Valore
rana_codana	Generato con multiCodeGenerator (1 lettera + 5 numeri)
rana_id_sincro	Progressivo da getNextIdSincro
rana_data_agg	Data odierna
rana_agg_app	"" (stringa vuota, flag per sync)
rana_timbro	"" (vuoto)
rana_val	"C" se cancellato, "" altrimenti

---

Risposta

200 OK

{
  "message": "OK"
}

400 Bad Request

Errore di validazione (schema TypeBox o raccordo mancante).

---

Note implementative

• Il POST gestisce sia inserimento che aggiornamento in una singola transazione
• La ricerca tramite codice_host_old (migrazione BMS) cerca con prefissi OCMI-, IRTE-, MARA-, SCOV-
• Quando un cliente viene trovato tramite codice_host_old, il codice host viene aggiornato sia su ARPANAGR che su APCRMANAGR
• La tabella CRM (APCRMANAGR) riceve un subset dei campi (nome troncato a 40 char, indirizzo a 40, localita' a 40)
• Il campo rana_nominativo_crm su ARPANAGR viene aggiornato con il codice CRM generato dopo l'INSERT su APCRMANAGR
• I campi conto_anagrafico e area_tecnica sono presenti solo in output (GET), non in input (POST)