Vai al contenuto

API Prestazioni — Specifica Tecnica

Panoramica

API REST per la sincronizzazione delle prestazioni (servizi non a magazzino) tra Areagate e sistemi host esterni. La tabella sorgente e' ARPMESER, gemella di ARPMERCI ma per le prestazioni. Include anche la gestione delle associazioni a raggruppamenti sconti vendita.

Endpoint disponibili

Metodo Path Descrizione
GET /v1/prestazione Lettura prestazioni (filtri: gruppo, sottogruppo, codice, descrizione, unita_misura, paginazione)
GET /v1/prestazione/up Lettura prestazioni aggiornate a partire da un sync id
POST /v1/prestazione Inserimento/aggiornamento/cancellazione batch prestazioni
POST /v1/prestazione/raggr_sconti Associazione di prestazioni a un raggruppamento sconti

Schema output — GET

PrestazioneOutput

Campo Tipo Campo DB Note
gruppo string rmers_gru Gruppo codice prestazione
sottogruppo string rmers_sot Sottogruppo codice prestazione
codice integer rmers_cod Codice prestazione
descrizione string trim(rmers_des) Descrizione
sync integer rmers_id_sincro ID di sincronizzazione
cancellato boolean rmers_stato = 'C' true se la prestazione e' cancellata logicamente
codice_host string trim(rmers_cma) Codice prestazione nel sistema host esterno
unita_misura string trim(rmers_um) Unita' di misura (max 2 char, puo' essere vuoto)

Query string — GET /

Parametro Tipo Obbligatorio Note
limit integer NO Max risultati (default/max: 1000)
page integer NO Pagina (paginazione offset-based)
gruppo string NO Filtro su rmers_gru (match esatto)
sottogruppo string NO Filtro su rmers_sot (match esatto)
codice integer NO Filtro su rmers_cod (match esatto)
descrizione string NO Filtro su rmers_des (case-insensitive ILIKE %x%)

Il GET / esclude le prestazioni cancellate (rmers_stato <> 'C').

Query string — GET /up

Parametro Tipo Obbligatorio Note
sync integer SI ID sincronizzazione di partenza

Il GET /up ordina per rmers_id_sincro crescente. Esclude anche qui i record cancellati (rmers_stato <> 'C'): non ci sono notifiche di cancellazione differenziale.

Schema input — POST /v1/prestazione

Body: array di oggetti PrestazioneInput (max 1000).

PrestazioneInput

Campo Tipo Obbligatorio Note
codice_host string SI Codice prestazione nel sistema host esterno (1-30 char) — chiave
descrizione string NO Descrizione (max 40 char, default "")
cancellato boolean NO Cancellazione logica (default false)

Nota: unita_misura non e' esposta in input. In inserimento il campo rmers_um viene valorizzato a stringa vuota; in modifica non viene toccato. Per gestirla via API serve estendere PrestazioneInput.

Logica POST

  • Deduplicazione payload: codice_host non puo' essere duplicato nello stesso array (checkDuplicati)
  • Categorie di operazioni:
    • Inserimento: record non esistente e payload non flaggato cancellato=true. Genera nuovo rmers_cm (chiave merce 9 char) tramite multiCodeGenerator partendo da lastCodMerci. Insert in ARPMESER con rmers_um = "", rmers_cod_iva = "", rmers_serv = "", rmers_famig = "", rmers_sgr = 0, ecc.
    • Cancellazione: record esistente non cancellato + payload cancellato=true. Update rmers_stato = 'C'
    • Modifica: record esistente con descrizione cambiata. Solo il campo descrizione viene aggiornato; rmers_stato rimesso a '' (riattivazione)
    • Skip: record esistente cancellato + payload cancellato=true; record non esistente + payload cancellato=true
  • id_sincro: assegnato progressivamente da getNextIdSincro(sql, id_azi, "ARPMESER", n)

POST /v1/prestazione/raggr_sconti

Associa prestazioni a un raggruppamento sconti vendita.

Body

Array di oggetti:

Campo Tipo Obbligatorio Note
codice_host string SI Codice prestazione (host)
codice_raggr string SI Codice raggruppamento sconti (puo' essere stringa vuota)

Logica

  1. Deduplicazione payload via checkDuplicati su codice_host
  2. Recupero della classe raggruppamento da arpconfig (rcfg_pack='C', rcfg_prog='listvend', rcfg_param_key='classe-raggr-sconti')
  3. Risoluzione raccordi: getRaccordiPrestazioni, getRaccordiRaggruppamento
  4. Per ogni elemento del payload con codice_raggr non vuoto:
    • Validazione che codice_host esista nei raccordi prestazioni -> altrimenti 400 body/{i}/codice_host (...) mancante
    • Se codice_raggr non esiste in arpanrag, lo accoda in arpanragDaInserire
    • Costruisce record per arpmerrag con la chiave merce risolta
  5. Insert in arpanrag per i nuovi raggruppamenti (a_arag_des = "Sconto")
  6. Upsert in arpmerrag (ON CONFLICT (a_mrag_azienda, a_mrag_merce, a_mrag_classe) DO UPDATE SET a_mrag_id, a_mrag_fl_canc='')

Tabelle sorgente

ARPMESER — anagrafica prestazioni

PK: (rmers_azi, rmers_gru, rmers_sot, rmers_cod). Stessa struttura di ARPMERCI ma per le prestazioni.

Campo Tipo Note
rmers_azi char(6) Codice azienda
rmers_gru char(2) Gruppo
rmers_sot char(2) Sottogruppo
rmers_cod num(5) Codice
rmers_cm char(9) Chiave merce concatenata gru+sot+cod
rmers_cma char(30) Codice host esterno
rmers_des char(40) Descrizione
rmers_um char(2) Unita' di misura
rmers_stato char(1) 'C' se cancellato logicamente
rmers_id_sincro num(15) ID sincronizzazione

ARPMERRAG / ARPANRAG — raggruppamenti sconti

Usate dal POST /raggr_sconti. ARPMERRAG lega merce -> id raggruppamento (a_mrag_id) per una classe (a_mrag_classe); ARPANRAG contiene i raggruppamenti definiti per la classe.

Limiti

Vincolo Valore
Max prestazioni per risposta GET 1000
Max prestazioni per body POST 1000
Max size codice_host 30 char
Max size descrizione 40 char
Max size unita_misura 2 char

Note implementative

  • Tutte le operazioni POST sono eseguite in una singola transazione (db.begin)
  • L'unita' di misura e' esposta in lettura ma non gestita in scrittura dall'API: l'inserimento di nuove prestazioni la valorizza a "", e l'update non la tocca. Per gestirla sara' necessario estendere lo schema input e la logica POST
  • La generazione del codice interno (rmers_cm) usa multiCodeGenerator con segmenti [2, 2, 5] partendo dal max corrente in arpmerci/arpmeser via lastCodMerci