Vai al contenuto

API Documenti — Specifica Tecnica

Panoramica

API REST per l'inserimento e la consultazione di documenti su Areagate da parte di sistemi esterni (gestionali host). Supporta diverse classi di documento con gestione automatica della deduplicazione.

Endpoint disponibili

Metodo Path Descrizione
POST /v1/documenti Inserimento batch di documenti generici
GET /v1/documenti Lettura lista documenti (filtri: id, cliente, paginazione)
GET /v1/documenti/up Lettura documenti aggiornati a partire da un sync id

Schema input — POST /v1/documenti

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

Testata (DocumentoInput)

Campo Tipo Obbligatorio Note
key_doc_host string SI Chiave univoca del documento nel sistema host (max 30 char) — usata per deduplicazione
classe_documento string SI Classe documento (max 4 char). Valori ammessi: vedi Classi supportate
ana_area string NO* Codice interno anagrafica AREA (max 30 char). Alternativo a ana_host
ana_host string NO* Codice anagrafica nel sistema host esterno (max 30 char). Alternativo a ana_area
data_doc integer NO Data documento in formato YYYYMMDD (es. 20260504 = 4 maggio 2026). Default: data odierna se 0 o omesso
doc_interlocutore string NO** Riferimento documento dell'interlocutore (max 15 char). Ammesso solo per classe DMEF
data_doc_interlocutore integer NO** Data del documento dell'interlocutore in YYYYMMDD. Ammessa solo per classe DMEF
mag_host string NO Codice magazzino nel sistema host esterno (max 16 char)
note string NO Note libere sulla testata (max 2000 char)
padri array NO Array di PadreDocumentoInput — raccordi padre a livello testata
righe array SI Array di RigaDocumentoInput (minimo 1 elemento)

* ana_area e ana_host sono mutuamente esclusivi: esattamente uno dei due deve essere presente (non e' possibile specificarli entrambi). La regola specifica dipende dalla classe documento (vedi Validazione anagrafica).

** doc_interlocutore e data_doc_interlocutore sono ammessi solo per la classe DMEF: per altre classi vengono rifiutati con 400 body/{i}: doc_interlocutore e data_doc_interlocutore sono ammessi solo per la classe DMEF. Mappano sui campi DB a_dotes_doc_interlocutore e a_dotes_data_doc_interlocutore.

Riga (RigaDocumentoInput)

Campo Tipo Obbligatorio Note
riga_doc integer SI Progressivo riga nel sistema host (>= 1)
segno_mov string SI Segno movimentazione: U = uscita/vendita, E = entrata
merce string SI Codice merce nel sistema host esterno (max 30 char)
qta number SI Quantita' (max +/-9.999.999,999)
prezzo_lordo number NO Prezzo unitario lordo (default 0)
sconto_1 number NO Primo sconto percentuale (default 0)
sconto_2 number NO Secondo sconto percentuale (default 0)
sconto_3 number NO Terzo sconto percentuale (default 0)
prezzo_netto number NO Prezzo netto dopo sconti (default 0)
importo number NO Importo totale della riga (default 0)
note string NO Note di riga (max 2000 char). Non ammessa se serial_numbers e' valorizzato
serial_numbers array NO Elenco serial number movimentati in uscita. Solo BDPC. Vedi sezione dedicata
padre object NO PadreRigaDocumentoInput — raccordo padre riga

Raccordo testata (PadreDocumentoInput)

Campo Tipo Obbligatorio Note
classe_padre string SI Classe del documento padre (solo ORC ammesso)
key_doc_host_padre string NO* Codice host del documento padre (max 30 char)
key_doc_area_padre string NO* Codice area del documento padre (max 30 char)

* key_doc_host_padre e key_doc_area_padre sono mutuamente esclusivi: esattamente uno dei due deve essere presente.

Raccordo riga (PadreRigaDocumentoInput)

Campo Tipo Obbligatorio Note
classe_padre string SI Classe del documento padre (solo ORC ammesso)
key_doc_host_padre string NO* Codice host del documento padre (max 30 char)
key_doc_area_padre string NO* Codice area del documento padre (max 30 char)
riga_padre integer SI Progressivo riga del documento padre (>= 1)

* key_doc_host_padre e key_doc_area_padre sono mutuamente esclusivi: esattamente uno dei due deve essere presente.

Classi supportate

classe_documento Descrizione Anagrafica Puo' avere padri
BDPC Buoni di prelievo cliente Cliente (ARPANAGR) SI (solo ORC, solo testata)
DMEF Documenti di entrata da fornitore Fornitore (TBFORNITORI) NO
DMG Documenti generici di magazzino (prima nota) Nessuna (ignorata) NO
DMUF Documenti di uscita a fornitore Fornitore (TBFORNITORI) NO

Tutte le classi inseriscono in ARPDOCTES / ARPDOCDET.

Nota: La classe ORC (ordini clienti) e' supportata solo come padre nei raccordi, non come documento da inserire tramite questo endpoint. Gli ordini risiedono in ARPORTES/ARPORDET e vengono gestiti dall'endpoint /v1/ordini.

Regole di validazione

Deduplicazione

  • Nel payload: non sono ammessi key_doc_host duplicati nello stesso array (errore immediato)
  • Nel database: se un documento con lo stesso key_doc_host e' gia' presente, non viene reinserito e viene riportato nella risposta
  • I documenti nuovi vengono inseriti normalmente anche se nella stessa chiamata esistono duplicati sul DB

Validazione anagrafica

La validazione dell'anagrafica dipende dalla classe documento:

Classi cliente (BDPC):

  • ana_area e ana_host sono mutuamente esclusivi: specificarne entrambi produce un errore
  • Almeno uno dei due deve essere presente
  • ana_area: verificata su ARPANAGR (rana_codana)
  • ana_host: cercato il raccordo host -> codice interno tramite getRaccordiClienti

Documenti generici (DMG):

  • L'anagrafica e' ignorata. Se presente viene comunque salvata, ma non viene validata

Classi fornitore (DMEF, DMUF):

  • E' ammesso solo ana_area (codice interno). ana_host non e' supportato
  • Verificato su TBFORNITORI (a_for_codana)

Documenti padre

  • Solo la classe BDPC puo' avere documenti padre
  • Il raccordo BDPC -> ORC e' gestito solo a livello testata (campo padri[]). Non e' ammesso padre a livello riga per BDPC
  • La classe padre ammessa e' esclusivamente ORC
  • Il documento padre viene cercato tramite key_doc_host_padre o key_doc_area_padre:
    • ORC: key_doc_host_padre cerca su a_ortes_codice_host, key_doc_area_padre cerca su a_ortes_tor_chia
    • Altri: key_doc_host_padre cerca su a_dotes_key_host, key_doc_area_padre cerca su a_dotes_key_area
  • La logica raccordo riga e' mantenuta nel codice per future tipologie di raccordo

Righe

  • Ogni merce deve avere un raccordo valido in ARPMERCI
  • segno_mov deve essere U (uscita) o E (entrata)
  • L'unita' di misura (a_dodet_um_area) viene recuperata automaticamente da ARPMERCI

Serial number (serial_numbers)

Array opzionale di stringhe (min 1 char, max 30 char per ogni s/n) che elenca i serial number movimentati dalla riga.

Vincoli:

  • Ammesso solo per la classe BDPC. Su altre classi produce errore body/{i}/righe/{j}/serial_numbers: ammessi solo per la classe BDPC
  • La merce di riga deve avere il flag gestione s/n attivo (arpmerci.rmer_fl_sn = 'T'), altrimenti errore la merce {merce} non prevede la gestione s/n
  • Se valorizzato, il campo note di riga non e' ammesso (errore la nota verrebbe sovrascritta): la nota verrebbe persa
  • I s/n non vengono validati contro apasnmatri — e' responsabilita' del gestionale gestire eventuali s/n inesistenti

Effetto sulla scrittura:

  • Il campo a_dodet_note viene sovrascritto con l'elenco dei s/n trimmati e separati da "; " (es. "SN001; SN002; SN003")
  • Se la lunghezza totale della stringa risultante supera 2000 caratteri (limite di a_dodet_note), errore l'elenco s/n eccede 2000 caratteri (N)

Raccordi (ARPDOCRAC)

La tabella ARPDOCRAC collega documenti padre-figlio, sia a livello di testata che di riga.

Struttura tabella

CREATE TABLE arpdocrac (
  a_dorac_azi              char(3)  NOT NULL,
  a_dorac_padre_id_pub     integer  NOT NULL,   -- id_pub del documento padre
  a_dorac_padre_riga       integer  NOT NULL,   -- 0 = testata, >0 = riga
  a_dorac_figlio_id_pub    integer  NOT NULL,   -- id_pub del documento figlio
  a_dorac_figlio_riga      integer  NOT NULL,   -- 0 = testata, >0 = riga
  PRIMARY KEY (azi, padre_id_pub, padre_riga, figlio_id_pub, figlio_riga)
);

Raccordo testata -> testata

Inserire nella padri[] della testata, usando key_doc_area_padre o key_doc_host_padre:

{
  "padri": [
    {
      "classe_padre": "ORC",
      "key_doc_area_padre": "ORD-2024-001"
    }
  ]
}

Genera un record in ARPDOCRAC con padre_riga = 0 e figlio_riga = 0.

Raccordo riga -> riga

Inserire nell'oggetto padre della riga:

{
  "riga_doc": 1,
  "segno_mov": "U",
  "merce": "ART001",
  "qta": 10,
  "padre": {
    "classe_padre": "ORC",
    "key_doc_area_padre": "ORD-2024-001",
    "riga_padre": 1
  }
}

Genera un record in ARPDOCRAC con padre_riga = riga_padre e figlio_riga = id_prog (progressivo riga figlio).

Risoluzione padre

La ricerca del documento padre avviene in base alla classe e al campo compilato:

Classe padre key_doc_host_padre key_doc_area_padre
ORC a_ortes_codice_host a_ortes_tor_chia
Altre a_dotes_key_host a_dotes_key_area

Il campo riga_padre nel payload corrisponde direttamente al numero riga usato nel raccordo — non e' necessaria nessuna traduzione.

Campi auto-assegnati

I seguenti campi vengono valorizzati automaticamente dall'endpoint:

Campo DB Valore
a_dotes_id_pub Progressivo auto-incrementato
a_dotes_origine "H" (host)
a_dotes_causale Derivata dalla classe
a_dotes_currency "E" (Euro)
a_dotes_agg_app "A" (flag aggiornamento lato web)
a_dotes_agg_host 1
a_dotes_di_prog "API-DOC" (programma di inserimento)
a_dotes_id_sincro Progressivo da getNextIdSincro
a_dodet_um_area Unita' di misura da ARPMERCI
a_dodet_merce Codice merce interno da raccordo
a_dodet_id_prog Indice riga (1-based)

Formato date

Tutte le date nel payload (input e output) sono integer YYYYMMDD (es. 20260504 = 4 maggio 2026), coerentemente con altri moduli del progetto (fatture, matricole, chiamata, intervento).

Conversione lato server: integerToDate per input -> DB, to_char(..., 'YYYYMMDD')::integer con CASE per output -> client.

Se data_doc e' 0 o omesso, viene usata la data odierna.

data_doc_interlocutore, se omessa o 0, viene salvata come 0001-01-01 su DB (segnaposto "non valorizzata"). In output viene restituito il valore grezzo del DB convertito in YYYYMMDD (es. 10101 per il segnaposto), senza normalizzazione a 0.

Risposta

200 OK

Tutti i documenti inseriti:

{
  "message": "OK",
  "scartati": []
}

Inserimento parziale (alcuni documenti gia' presenti):

{
  "message": "OK",
  "scartati": ["DOC-001", "DOC-002"]
}

Nessun documento inserito (tutti gia' presenti):

{
  "message": "Nessun documento inserito",
  "scartati": ["DOC-001", "DOC-002"]
}

Il campo scartati contiene i key_doc_host dei documenti gia' presenti nel database che non sono stati reinseriti.

400 Bad Request

Errore di validazione (schema TypeBox o logica di business).

Esempio payload completo

[
  {
    "key_doc_host": "BDP-2024-001",
    "classe_documento": "BDPC",
    "ana_host": "CLI001",
    "data_doc": 20240101,
    "mag_host": "MAG01",
    "note": "Buono di prelievo gennaio",
    "padri": [
      {
        "classe_padre": "ORC",
        "key_doc_area_padre": "ORD-2024-010"
      }
    ],
    "righe": [
      {
        "riga_doc": 1,
        "segno_mov": "U",
        "merce": "ART001",
        "qta": 10,
        "prezzo_lordo": 25.50,
        "sconto_1": 5,
        "sconto_2": 0,
        "sconto_3": 0,
        "prezzo_netto": 24.225,
        "importo": 242.25
      },
      {
        "riga_doc": 2,
        "segno_mov": "U",
        "merce": "ART002",
        "qta": 5,
        "prezzo_lordo": 100.00,
        "prezzo_netto": 100.00,
        "importo": 500.00
      }
    ]
  },
  {
    "key_doc_host": "DDT-FORN-2024-007",
    "classe_documento": "DMEF",
    "ana_area": "F00123",
    "data_doc": 20240301,
    "doc_interlocutore": "DDT-789/2024",
    "data_doc_interlocutore": 20240228,
    "mag_host": "MAG01",
    "righe": [
      {
        "riga_doc": 1,
        "segno_mov": "E",
        "merce": "ART001",
        "qta": 100,
        "prezzo_lordo": 12.00,
        "prezzo_netto": 12.00,
        "importo": 1200.00
      }
    ]
  }
]

Note implementative

  • Tutte le operazioni di inserimento sono eseguite in una singola transazione (db.begin). In caso di errore, nessun dato viene scritto
  • L'INSERT avviene su tre tabelle in sequenza: ARPDOCTES (testate), ARPDOCDET (righe), ARPDOCRAC (raccordi)
  • I raccordi testata e riga vengono unificati in un singolo INSERT su ARPDOCRAC
  • L'unita' di misura (a_dodet_um_area) viene recuperata automaticamente da ARPMERCI tramite il codice merce host
  • I campi di aggiornamento (*_da_*) vengono valorizzati come quelli di inserimento (*_di_*)
  • Il campo a_dotes_agg_app = "A" segnala ai processi di sync (come SWN139) che il record e' stato aggiornato lato web

Integrazione lato gestionale

I documenti inseriti tramite questa API vengono importati nel gestionale dal processo SWN139 - Importazione documenti Areagate, che legge ARPDOCTES/ARPDOCDET e crea i corrispondenti documenti tramite COGS26 (documenti magazzino) e COGSA0 (buoni prelievo).

Specifica aggiornata sulla base del documento di import API_Documenti_Schema.md — 2026-03-20