Documentazione a supporto degli Scendari d'Uso
Per supportare i vari scenari d'uso gestiti, vengono forniti alcuni casi d'uso come esempi.
Nota: Sebbene l'utilizzo dei servizi consenta implementazioni diverse da quelle specificate, si ricorda che le funzionalità supportate sono quelle descritte nei Casi d'Uso indicati.
General Master Data
Default campo ditta nei data transfer object (DTO)
Nelle chiamate POST, è possibile specificare il campo 'ditta' o 'dittaCg18' all'interno del body della chiamata.
Un esempio pratico: Si desidera inserire un documento con tipo documento C-DDT per il cliente 1 e per la ditta 1000.
Fino alla versione 202403000, il campo 'ditta' doveva essere definito obbligatoriamente per ogni proprietà del body, per cui era necessario popolare il campo 'ditta' o 'dittaCg18' come nell'esempio json sotto riportato:
{
"ditta": "1000",
"valutaCg08": "EURO",
"anagraficaDocumentoDitta": {
"dittaCg18": "1000",
"codDocumMg36": "C-DDT",
"indStaperMg36": 1.0
},
"customerSupplierMG": {
"dittaCg18": "1000",
"tipocfCg40": 0,
"cliFor": 1
},
"sezdoc": "00",
"storageWH": {
"dittaCg18": "1000",
"codDep": "00"
},
"righe": [
{
"ditta": "1000",
"progrRiga": 1.0,
"codartMg66": "ART001",
"descart": "Descrizione articolo",
"qta1": 15.000
}
]
}
Dalla versione 202501000 è stata introdotta una logica di default per il campo 'ditta' nei Data Transfer Object (DTO), per cui se il valore del campo 'ditta' dell'entità "root" non viene fornito o è nullo, viene automaticamente popolato con il codice ditta ricavato dalla sessione utente corrente (parametro 'company'). Questa operazione si propaga a tutte le entità 'external' ed 'internal' associate.
Di conseguenza, prendendo in considerazione sempre l'esempio di cui sopra, l'utente ha sempre la stessa chiamata:
POST {{webapi_base_url}}/api/v1/{{scope}}/MG/Documento?company=1000
ma nelle proprietà del body non è più necessario definire il campo 'ditta' o 'dittaCg18', così come nell'esempio json sotto riportato:
{
"valutaCg08": "EURO",
"anagraficaDocumentoDitta": {
"codDocumMg36": "C-DDT",
"indStaperMg36": 1.0
},
"customerSupplierMG": {
"tipocfCg40": 0,
"cliFor": 1
},
"sezdoc": "00",
"storageWH": {
"codDep": "00"
},
"righe": [
{
"progrRiga": 1.0,
"codartMg66": "ART001",
"descart": "Descrizione articolo",
"qta1": 15.000
}
]
}
Nota Bene: Se si definisce comunque il campo 'ditta' in una proprietà del body, è necessario definirlo su tutte le proprietà che compongono il body.
Inserimento minimale di una anagrafica generale
Qui di seguito è riportato l'esempio di inserimento di un'anagrafica generale, con i dati minimi.
{{webapi_base_url}}/{{api}}/V2/{{scope}}/co/generalmasterdataco?company={{azienda}}
{
"city": "Misano",
"isValidGeneralMasterData": 1.0,
"legalName": "Anagrafica test WebApi ",
"nationCode": 86.0,
"taxCity": "Misano",
"taxLegalName": "Anagrafica prova WebApi",
"taxNationCode": 86.0
}
Inserimento minimale di un Cliente/Fornitore
Per inserire un cliente o un fornitore, è necessario aver precedentemente inserito i dati anagrafici comuni e, nel caso dell’inserimento di un cliente, indicare il codice corrispondente dei dati anagrafici comuni, come mostrato nell’esempio seguente:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/co/CustomerSupplierCO?company={{azienda}}
{
"customerSupplierType": 0,
"generalMasterDataCode": 980,
"paymentTermCode": "201",
"currencyCode": "EURO",
"AgenteCode" : "Agente",
"OfficeCode": 1,
"VatCode": 22,
"additionalInformation": {
"macroAreaCode": "UE",
"areaCode": "ITA",
"zoneCode": null,
"macrocategoryCode": "MCQ",
"categoryCode": "CA1",
"subCategory": "SC1"
}
}
Ricerca di un Cliente/Fornitore per Codice Fiscale e/o Partita IVA
Tramite la chiamata
{{webapi_base_url}}/api/v1/{{scope}}/CO/lookup/CustomerSupplierCO?metadata=true&company={{defaultCompany}}&_op=search
è possibile effettuare la ricerca di un cliente per Partita IVA o Codice Fiscale o per Ragione sociale.
{
"filters":
{
"items":
[
{
"comparer": 0,
"propertyName": "CustomerSupplierCO_Tipocf",
"value": "0"
},
{
"operator": 1,
"items":
[
{
"propertyName": "CustomerSupplierCO_GeneralMasterDataCO_Partiva",
"comparer": 0,
"value": "25052733463"
},
{
"operator": 2,
"propertyName": "CustomerSupplierCO_GeneralMasterDataCO_Codfiscale",
"comparer": 30,
"value": "MRARSS13S08H501H"
},
{
"operator": 2,
"propertyName": "CustomerSupplierCO_GeneralMasterDataCO_RagSoAnag",
"comparer": 20,
"value": "ROSSI"
}
]
}
]
},
"pageSize": 5,
"pageNumber": 0
}
Ricerca di una Causale Contabile
Per effettuare la ricerca di una causale contabile è necessario utilizzare una richiesta POST. Ecco un esempio:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/CO/AccountingReasonCodeCO/search?company={{azienda}}&getTotalCount=true
{
"filters": {
"items": [
{
"operator": 0,
"propertyName": "alias",
"comparer": 0,
"value": "FTV1"
}
]
},
"pageSize": 0,
"pageNumber": 0
}
Inserimento di un Anagrafica Agente
Per inserire un agente è necessario utilizzare una richiesta POST. Ecco un esempio:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/co/AgentCO?company={{azienda}}
{
"code": "008",
"companyCode": 2.0,
"generalMasterDataCode": 2593,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Inserimento di una Nazione
Per inserire una Nazione è necessario utilizzare una richiesta POST. Ecco un esempio:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/co/NationCO?company={{azienda}}
{
"code": 811.0,
"currencyCode": "EURO",
"description": "Nazione Italia Webapi",
"euEntryDate": "1995-01-01T00:00:00",
"iso3166Alpha2": "IT",
"iso3166Alpha3": "ITA",
"iso3166Description": "ITALY",
"iso3166Number": "380",
"isoCode": "IT",
"isSepaStandardUsed": 1,
"nationType": 1.0,
"sianCode": null,
"vatNumberLength": "11"
}
MacroCategoria - Categoria - Sottocategoria
Creazione di una MacroCategoria
Per creare una macrocategoria, è necessario utilizzare una richiesta POST. Ecco un esempio:
{{webapi_base_url}}/api/v1/{{scope}}/CO/MacroCategoryCO?company={{defaultCompany}}
{
"descrmacrocat": "Test WebAPI - Macrocategoria",
"macrocat": "{{codMacroCat}}",
"tipocf": "{{TipoCF}}",
}
Questa è la response:
{
{
"descrmacrocat": "Test WebAPI - Macrocategoria",
"dittaCg18": 1000.0,
"macrocat": "MCQ",
"tipocf": 0.0,
"categorie": [],
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
}
Creazione di una Categoria
Per creare una categoria associata a una macrocategoria, è necessario utilizzare una richiesta POST. Ecco un esempio:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/CategoryCO?company={{defaultCompany}}
{
"categ": "{{codCat}}",
"descrcat": "Test WebAPI - Categoria",
"macrocatMg10": "{{codMacroCat}}",
"tipocfMg10": "{{TipoCF}}"
}
Questa è la response:
{
"categ": "CA1",
"descrcat": "Test WebAPI - Categoria",
"dittaCg18": 1000.0,
"macrocatMg10": "MCQ",
"tipocfMg10": 0.0,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Creazione di una SottoCategoria
Per creare una sottocategoria associata a una categoria, è necessario utilizzare una richiesta POST. Ecco un esempio:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/SubCategoryCO?company={{defaultCompany}}
{
"categMg11": "{{codCat}}",
"descrsottocat": "Test WebAPI - SottoCategoria",
"macrocatMg11": "{{codMacroCat}}",
"sottcat": "{{codSubCat}}",
"tipocfMg11": "{{TipoCF}}"
}
Questa è la response:
{
"categMg11": "CA1",
"descrsottocat": "Test WebAPI - SottoCategoria",
"dittaCg18": 1000.0,
"macrocatMg11": "MCQ",
"sottcat": "SCT",
"tipocfMg11": 0.0,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Inserimento minimale di un codice articolo
Tramite la chiamata POST
{{webapi_base_url}}/api/v2/{{scope}}/WH/ItemWH?company={{defaultCompany}}
è possibile inserire un nuovo codice articolo.
Qui di seguito è riportato l'esempio di inserimento di un codice articolo, con i dati minimi.
{
{
"code": "{{ItemCode}}",
"companyCode": {{defaultCompany}},
"description": "Test webapi articolo",
"itemStatusCode": 50,
"vatCode": "22",
"createDate": "2024-05-08T00:00:00",
"updateDate": "2025-10-06T00:00:00",
"barcodes": [],
"currentStatus": {
"statoCorrente": {
"idStato": 4,
"seq": -1,
"indTipoStato": 0
}
},
"descriptions": [
{
"companyCode": 1000.0,
"description": "Test webapi articolo"
}
],
"intrastatData": null,
"packagings": [
{
"capacity": 0.0,
"companyCode": 1000.0,
"packagingCode": "CD",
"packagingPieces": 1.000,
}
],
"stocks": [
{
"companyCode": 1000.0,
"coverIndex": 0.000,
"isAutosaveStocksQuantity": 1,
"maxStock": 100.000,
"minStock": 10.000,
"storageCode": "00",
}
]
}
}
Servizio di lettura Barcode articoli
Il servizio di lettura della Barcode articoli consente di leggere, mediante chiamata search, gli articoli per i quali sono stati configurati e gestiti i codici Barcode. Ad esempio:
POST {{webapi_base_url}}/{{api}}/v2/{{scope}}/WH/ItemBarCodeWH/search?company={{defaultCompany}}
Con indicazione degli operatori di filtro nel body:
{
"filters": {
"operator": 0,
"items": [
{
"operator": 0,
"propertyName": "itemcode",
"comparer": 0,
"value": "ARTICOLO3"
}
]
},
"pageSize": 0,
"pageNumber": 0
}
Esempio di response:
{
"totalCount": 0,
"pageSize": 1,
"pageNumber": 0,
"data": [
{
"barcode": "0000000000079",
"barcodeType": 0.0,
"companyCode": 1000.0,
"hyperMediaId": null,
"isCheckdigitCalculation": 1.0,
"isPrintLabels": 1.0,
"isSendToCashRegisters": 1.0,
"itemCode": "ARTICOLO3",
"itemVariantCode": "",
"managementType": 0.0,
"originType": 1.0,
"piecesPerPackaging": 1.000,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
],
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Servizio di lettura e ricerca ItemStatusWH
Il servizio ItemStatusWH consente di leggere e cercare gli stati standard degli articoli. Ad esempio:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/WH/ItemStatusWH/search?company={{defaultCompany}}
Con indicazione degli operatori di filtro nel body:
{
"filters": {
"items": [
{
"operator": 1,
"propertyName": "indStato",
"comparer": 0,
"value": 10
}
]
},
"pageSize": 0,
"pageNumber": 0
}
Esempio di response:
{
"totalCount": 0,
"pageSize": 1,
"pageNumber": 0,
"data": [
{
"descr": "In progettazione",
"indStato": 10.0,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
],
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Gestione degli stati parametrici su clienti-fornitori, articoli e documenti
Il servizio StateManagementService permette di visualizzare lo Stato Attuale di un oggetto, in base alla guid identificativa e consente di cambiare lo stato attuale con un suo stato disponibile.
Lo Stato Attuale è gestito per le seguenti entità:
- CustomerSupplierMG (solo GET)
- CustomerSupplierCO
- DocumentoCorpoMG
- DocumentoTestataMG
- ItemWH
E' possibile visualizzare e/o modificare lo Stato Attuale di un'oggetto, se da Interfaccia per l'entità interessata è stato definito un Flusso predefinito ed in base ai permessi relativi all'utente che si sta utilizzando.
Tramite una semplice chiamata GET è possibile visualizzare nella response lo Stato Attuale e gli Stati Disponibili per un determinato utente. Per esempio se si desidera verificare lo stato attuale del codice articolo SW6 per utente admin, la chiamata GET dovrà essere così strutturata:
GET {{webapi_base_url}}/{{api}}/v1/{{scope}}/WH/ItemWH/SW6?company={{defaultCompany}}&user=admin
e nella response è riportato lo stato del codice articolo preso in esame e degli stati disponibili per l'utente admin.
"statoAttualeCO": {
"statoCorrente": {
"idStato": 4,
"seq": -1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
"statiDisponibili": [
{
"idStato": 3,
"seq": 3,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 4,
"seq": 4,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 5,
"seq": 5,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 6,
"seq": 6,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
}
}
Se si esegue la stessa chiamata GET, ma specificando un altro utente (che non ha gli stessi permessi dell'utente 'admin' di cui sopra), la response riporterà sempre lo stesso Stato Attuale, ma riporterà solo gli Stati disponibili per l'altro utente.
Tramite la chiamata PUT oppure PATCH invece è possibile modificare il valore dello Stato Attuale dell'entità presa in considerazione, per cui per esempio considerando sempre il codice articolo SW6 la chiamata PATCH deve essere così strutturata:
PATCH {{webapi_base_url}}/{{api}}/v1/{{scope}}/WH/ItemWH/SW6?company={{defaultCompany}}&user=admin
e nel body si deve indicare un nuovo idStato tra quelli disponibili :
{
"statoAttualeCO": {
"statoCorrente": {
"idStato": 5,
"seq":5,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
}
}
}
Tramite il servizio StateManagementService ed attraverso la relativa guid, è possibile visualizzare il currentState (che corrisponde allo StatoAttuale) esistente per l'oggetto preso in esame, ed i availableStates (che corrisponde all'elenco degli Stati disponibili). Ad esempio prendendo sempre in considerazione il codice articolo 'SW6' per l'utente admin, si esegue una chiamata GET, specificando la corrispondente guid del suddetto codice articolo:
GET {{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/StateManagementService/{{guid}}?company={{defaultCompany}}&user=admin
e la response sarà così riportata:
{
"currentState": {
"idStato": 4,
"description": "In uso",
"seq": -1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
"availableStates": [
{
"idStato": 3,
"description": "Rilasciato",
"seq": 3,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 4,
"description": "In uso",
"seq": 4,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 5,
"description": "In esaurimento",
"seq": 5,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 6,
"description": "Dismesso",
"seq": 6,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
}
]
}
Oppure
Per esempio se si desidera verificare lo StatoAttuale di un documento, si esegue una chiamata GET (come riportata), specificando la corrispondente guid della TestataDocumento
GET {{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/StateManagementService/{{guidTestataDocumento}}?company={{defaultCompany}}&user=admin
e la response riporterà lo StatoAttuale (o currentState) del documento e gli eventuali Stati Disponibili (o availableStates) quindi sarà così riportata:
{
{
"currentState": {
"idStato": 41,
"description": "Confermato",
"seq": -1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
"availableStates": [
{
"idStato": 40,
"description": "Acquisito",
"seq": 1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 41,
"description": "Confermato",
"seq": 2,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 42,
"description": "Bloccato",
"seq": 3,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 43,
"description": "In spedizione",
"seq": 4,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 44,
"description": "Evaso",
"seq": 5,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
}
]
}
}
oppure se si desidera verificare lo StatoAttuale di una riga all'interno del documento preso in esame, con una semplice GET sul documento, si recupera la corrispondente guid identificativa della suddetta riga e poi si esegue la seguente chiamata GET per il servizio StateManagementCO:
GET {{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/StateManagementService/{{guidRigaDocumento}}?company={{defaultCompany}}&user=admin
e la response riporterà lo StatoAttuale (o currentState) della riga documento e gli eventuali Stati Disponibili (o availableStates) quindi sarà così riportata:
{
{
"currentState": {
"idStato": 46,
"description": "In evasione",
"seq": -1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
"availableStates": [
{
"idStato": 45,
"description": "Da evadere",
"seq": 1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 46,
"description": "In evasione",
"seq": 2,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 47,
"description": "Evasa",
"seq": 3,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 48,
"description": "Bloccata",
"seq": 4,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 49,
"description": "Annullata",
"seq": 5,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
}
]
}
}
Tramite il servizio StateManagementService e l'azione setstate è anche possibile avanzare il 'currentState' esistente per un oggetto, sempre attraverso la relativa guid, indicando un nuovo 'idStato' tra quelli disponibili per l'utente utilizzato. In questo caso si esegue la seguente chiamata POST:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/StateManagementService/setstate?company={{defaultCompany}}&user=admin
e nel body si specifica la guid dell'oggetto in esame ed il nuovo idStato, specificandolo nel campo "newState" :
{
"guidObject": "{{guid}}",
"newState": 5,
"entityCodeForDefault": null
}
Per esempio, preso in esame un determinato cliente in stato 'Codificato' (idStato=7), dopo le opportune verifiche amministrative, si desidera avanzare lo stato del cliente, da 'Codificato' a 'In uso'(idStato=8) per cui si esegue la chiamata POST indicando nel body la guid del cliente:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/StateManagementService/setstate?company={{defaultCompany}}&user=admin
e nel body si specifica la guid dell'oggetto in esame (in questo caso del Cliente) ed il nuovo idStato, specificandolo nel campo "newState" :
{
"guidObject": "{{guidCliente}}",
"newState": 8,
"entityCodeForDefault": null
}
Si può anche verificare il caso in cui si definisce un Flusso predefinito in un secondo momento, per cui alla creazione di un codice articolo per esempio il codice 'AW1' lo StatoAttualeCO è NULL. Da Interfaccia si indica un flusso come 'Predefinito' per l'entità Articoli. A questo punto, tramite l'azione 'setstate' è possibile impostare il valore dello stato 'Predef.' appartenente al corrispondente 'Flusso predefinito' per entità Articoli.
In questo caso si esegue la stessa chiamata POST di cui sopra, impostando però il parametro "newState" a null ed "entityCodeForDefault": 6 (che corrisponde all'entità Articoli), specificando la guid dell'oggetto in esame (quindi la guid del codice articolo preso in esame AW1)
{
"guidObject": "{{guid}}",
"newState": null,
"entityCodeForDefault": 6
}
Nella response sarà riportato il "currentState" ed i "availableStates", come sotto riportato:
{
"currentState": {
"idStato": 10002,
"description": "articolo inserito",
"seq": -1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
"availableStates": [
{
"idStato": 10002,
"description": "articolo inserito",
"seq": 1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
{
"idStato": 10003,
"description": "articolo confermato",
"seq": 2,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
}
]
}
Tramite il servizio StateManagementService e l'azione history è anche possibile visionare i vari avanzamenti di stato dell'oggetto preso in esame, sempre attraverso la relativa guid. Si effettua una chiamata GET così strutturata:
GET {{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/StateManagementService/history/{{guid}}?company={{defaultCompany}}
e nella response sarà riportato il "currentState" e lo "statusOperationHistory" con diverse informazioni:
{
"currentState": {
"idStato": 10003,
"description": "articolo confermato",
"seq": -1,
"indTipoStato": 0,
"extensionData": [],
"additionalData": {}
},
"statusOperationHistory": [
{
"idHistory": 135,
"idStatus": 10002,
"validityDate": "2025-03-10T00:00:00",
"updateDate": "2025-03-10T15:00:54.713",
"historyAuto": 0,
"statusDescription": "articolo inserito",
"flowDescription": "Flusso Prova",
"userDescription": "Utente amministratore",
"historyDelete": 1
},
{
"idHistory": 136,
"idStatus": 10003,
"validityDate": "2025-03-21T00:00:00",
"updateDate": "2025-03-21T15:03:39.033",
"historyAuto": 0,
"statusDescription": "articolo confermato",
"flowDescription": "Flusso Prova",
"userDescription": "Utente amministratore",
"historyDelete": 0
}
],
}
Inserimento di una Marca da associare ad un Articolo
Tramite il nuovo servizio BrandWh è possibile creare/inserire una Marca che successivamente può essere associata ad un articolo. Per inserire una nuova Marca occore utilizzare la chiamata di tipo POST, ecco un esempio:
POST {{webapi_base_url}}/api/v1/{{scope}}/WH/BrandWH?company={{defaultCompany}}&user=admin
Con il seguente body minimale:
{
"codMarca": "{{codMarca}}",
"descrmarca": "Marca di test"
}
La response che otterremo sarà:
{
"codMarca": "NikeTest",
"descrmarca": "Marca di test",
"dittaCg18": 1000.0,
"idmediaCg99": null,
"idprov": 8,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Servizio BatchInventoryService per Interrogazione Inventario Lotti
Il servizio BatchInventoryService con relativa azione batchinventory consente di ottenere l'interrogazione dell'inventario lotti per gli articoli di magazzino gestiti a lotti, replicando il funzionamento della procedura "Interrogazione e stampa inventario lotti" da Interfaccia.
Nei parametri di input è possibile indicare anche delle condizioni di filtro, di ordinamento e di paginazione.
Per esempio, si esegue la verifica della situazione inventariale del codice articolo LOT_KIT (che gestisce i lotti) sul deposito principale, considerando i "Progressivi da elaborare" pari al parametro "In tempo reale". In questo caso si effettua la seguente chiamata POST:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/WH/BatchInventoryService/batchinventory?company={{defaultCompany}}&user=admin
Nel Body della request in corrispondenza del parametro "searchParameters" si definisce il codice articolo "LOT_KIT" ed il codice deposito principale "00" così come sotto riportato:
{
"entriesCombination": 1,
"progressiveType": 1,
"searchParameters": {
"filterProperties": [
{
"propertyName": "ItemCode",
"fromValue": "LOT_KIT",
"toValue": "LOT_KIT"
},
{
"propertyName": "StorageCode",
"fromValue": "00",
"toValue": "00"
}
],
"pageSize": 0,
"pageNumber": 0
}
}
La response riporta i valori inventariali per codice articolo e per codice lotto, per cui nel nostro esempio il paragrafo "rows" è popolato da tutti i codici lotti movimentati (riportati in corrispondenza del parametro "lotCode") per il codice articolo LOT_KIT, così come sotto riportato:
{
"totalRowsFound": 2,
"totalRowsShowed": 2,
"pageNumber": 0,
"rows": [
{
"itemCode": "LOT_KIT ",
"itemVariantCode": " ",
"itemDescription": "articolo che gestisce i lotti",
"storageCode": "00",
"lotCode": "L1 ",
"lotDescription": "lotto1",
"dueDate": null,
"serialNumber": null,
"palletsCode": null,
"projectCode": null,
"locationCode": null,
"packagingCode": null,
"materialsDyeingCode": null,
"referenceNodeCode": null,
"totalLoadQuantity1": 24.000,
"totalUnloadQuantity1": 9.000,
"totalLoadQuantity2": 0.000,
"totalUnloadQuantity2": 0.000,
"initialStockQuantity1": 0.000,
"currentStockQuantity1": 15.000,
"actualStockQuantity1": 15.000,
"fiscalStockQuantity1": 15.000,
"prodCommQuantity1": 0.000,
"initialStockQuantity2": 0.000,
"currentStockQuantity2": 0.000,
"actualStockQuantity2": 0.000,
"fiscalStockQuantity2": 0.000,
"prodCommQuantity2": 0.000,
"freeUnload2Quantity2": 0.000,
"averageCostQuantity1": 546.670000,
"lastCost": 310.000000
},
{
"itemCode": "LOT_KIT ",
"itemVariantCode": " ",
"itemDescription": "articolo che gestisce i lotti",
"storageCode": "00",
"lotCode": "L2 ",
"lotDescription": "lotto2",
"dueDate": null,
"serialNumber": null,
"palletsCode": null,
"projectCode": null,
"locationCode": null,
"packagingCode": null,
"materialsDyeingCode": null,
"referenceNodeCode": null,
"totalLoadQuantity1": 16.000,
"totalUnloadQuantity1": 6.000,
"totalLoadQuantity2": 0.000,
"totalUnloadQuantity2": 0.000,
"initialStockQuantity1": 0.000,
"currentStockQuantity1": 10.000,
"actualStockQuantity1": 10.000,
"fiscalStockQuantity1": 10.000,
"prodCommQuantity1": 0.000,
"initialStockQuantity2": 0.000,
"currentStockQuantity2": 0.000,
"actualStockQuantity2": 0.000,
"fiscalStockQuantity2": 0.000,
"prodCommQuantity2": 0.000,
"freeUnload2Quantity2": 0.000,
"averageCostQuantity1": 546.670000,
"lastCost": 310.000000
},
]
}
NOTA BENE: Nel caso in cui si indica ProgressiveType=2, il parametro "year" è obbligatorio.
Contabilità Generale
Movimenti di Prima Nota V2
In questa sezione viene illustrato l’utilizzo delle WebAPI V2 per la gestione dei movimenti contabili attraverso i servizi GLEntryFI e InstalmentFI. Questi servizi consentono di registrare e gestire in modo integrato i movimenti di Prima Nota, sia IVA che NON IVA, con particolare attenzione alla creazione delle scadenze.
Ecco un esempio di inserimento Fattura Cliente:
{{webapi_base_url}}/{{api}}/V2/{{scope}}/fi/glentryfi?company={{defaultCompany}}
{
{
"accountingReasonCode": "1",
"Description": "Fattura di vendita",
"amount": 122.00,
"currencyCode": "EURO",
"customerSupplierId": 4,
"documentType": 1.0,
"registrationDate": "2025-12-24",
"documentDate": "2025-12-24",
"sectionalCode": "00",
"documentNumber": 0,
"rows": [
{
"operationType": 1,
"accountId": 3257,
"customerSupplierId": 4,
"amount": 122.00,
"signType": 1
},
{
"operationType": 3,
"accountId": 3686,
"amount": 100.00,
"signType": 2,
"vatRowNumber": 1.0
},
{
"operationType": 2,
"accountId": 3566,
"amount": 22.00,
"signType": 2
}
],
"vatRows": [
{
"rowNumber": 1.0,
"accountId": 3686,
"taxableAmount": 100.00,
"taxAmount": 22.00,
"vatCode": "22",
//"nonDeductibilityVatType" : 1,
"vatAccountingReasonCode": 0.0
}
]
}
Esempio di inserimento Giroconto Contabile:
{{webapi_base_url}}/{{api}}/V2/{{scope}}/fi/glentryfi?company={{defaultCompany}}
{
"accountingReasonCode": "109",
// "registrationDate": "2024-10-21",
"Description": "Giroconto contabile",
"amount": 9.00,
"sectionalCode": "00",
"currencyCode": "EURO",
"movementType": 0,
"officeCode": 0.0,
"rows": [
{
"accountId": 3399,
"amount": 10.00,
"signType": 1,
"operationType": 28
},
{
"accountId": 3382,
"amount": 10.00,
"signType": 2,
"officeCode": 1.0,
"currencyCode": "EURO"
}
],
"vatRows": []
}
Inserimento Scadenze
Servizio per la gestione delle scadenze e dei piani di pagamento, collegato alle registrazioni contabili effettuate con GLEntriFI. Per stabilire l'associazione tra le scadenze e il movimento contabile, è necessario passare il parametro registrationNumber generato dal servizio GLEntryFI al momento della registrazione.
Esempio di inserimento di una scadenza:
{{webapi_base_url}}/{{api}}/V2/{{scope}}/FI/InstalmentFI?company={{defaultCompany}}
{
"acceptanceType": 0,
"accountId": 3257,
"accountingReasonCode": "1",
"accountingRowNumber": 1.0,
"accountStatementProgressive": 0.0,
"accountType": 1.0,
"amount": 61.00,
"art62GoodsType": 0,
"billEffectNumber": 82.0,
"billEffectStatusTransactionType": 0.0,
"billEffectType": 13.0,
"billPresentationType": 0.0,
"billProgressive": 2.0, // progressivo scadenza
"billStatusType": 0.0,
"collectionFees": 0.0,
"commissionSettlementType": 0.0,
"companyCode": 1000,
"currencyAmount": 0.00,
"currencyCode": "EURO",
"currencyCollectionFees": 0.00,
"currencyDocumentTotal": 0.00,
"currencyOriginWithholdingsAmount": 0.00,
"currencyResidualAmount": 0.00,
"currencyResidualAmountExcludingEstimatedEntries": 0.00,
"currencyVatAmount": 0.00,
"currencyWithholdingsAmount": 0.00,
"customerSupplierId": 4,
"description": "Fattura di vendita",
"documentDate": "2025-12-24T00:00:00",
"documentNumber": "19",
"documentTotal": 122.00,
"dueDate": "2026-02-28T00:00:00",
"entryNumber": 9.0,
"entrySectionalCode": "00",
"entryYear": 2025.0,
"exchangeRate": 0.000000,
"exchangeRateAdjustmentOnAccount": 0.00,
"exchangeRateDate": "2025-12-24T00:00:00",
"instalmentNumber": 1.0,
"lastChangeDate": "2025-12-02T14:58:12.063",
"movementType": 0.0,
"originDueDate": "2026-02-28T00:00:00",
"originWithholdingsAmount": 0.00,
"paymentTermId": 56,
"progressiveNumber": 19.0,
"registrationDate": "2025-12-24T00:00:00",
"registrationNumber": "202500002642",
"residualAmount": 61.00,
"residualAmountExcludingEstimatedEntries": 61.00,
"returnExpenseMgmtType": 0.0,
"returnFees": 0.00,
"returnFeesChargedByBank": 0.00,
"sectionalCode": "00",
"stampDutyAmount": 0.0,
"stampDutyCurrencyAmount": 0.00,
"startingDueDate": "2025-12-24T00:00:00",
"totalInstalments": 2.0,
"vatAmount": 11.00
}
Framework
Dlevel e Dlevelkey
Tramite il servizio DlevelEntityName, è possibile recuperare un elenco di informazioni relative alle entità correlate, partendo da un DTO specifico, in modo da poter comprendere i nomi delle Entità (internalNameDeserialization e externalNameDeserialization) per poi valorizzare la proprietà dlevel richiesta in tutte le GET standard.
Il deserialization level è una sintassi che descrive quali rami del grafo, che costituisce l'aggregato, devono essere caricati in una lettura. Sintassi:
[] le parentesi quadre identificano le relazioni interne
le parentesi graffe identificano una relazione esterna
- identifica tutti i nomi di relazioni in quel contesto
Ad esempio, dato un 'DTO name:DocumentoTestataMGDTO si può eseguire la seguente chiamata:
GET {{webapi_base_url}}/api/v1/{{scope}}/FW/DlevelEntityName/DocumentoTestataMGDTO?company={{defaultCompany}}
che riporterà nella response le seguenti informazioni (riporto parziale della response):
[
{
"internalNameDeserialization": "DocumentoDatiAccompagnamentoMG",
"externalNameDeserialization": null,
"relatedDTOEntityName": "DocumentoDatiAccompagnamentoMGDTO",
"relatedDTOPropertyName": "DocumentoDatiAccompagnamentoMG"
},
{
"internalNameDeserialization": "RigheDocumento",
"externalNameDeserialization": null,
"relatedDTOEntityName": "DocumentoRigaMGDTO",
"relatedDTOPropertyName": "Righe"
},
{
"internalNameDeserialization": "DocumentoTestataAgentiMG",
"externalNameDeserialization": null,
"relatedDTOEntityName": "DocumentoTestataAgentiMGDTO",
"relatedDTOPropertyName": "DocumentoTestataAgentiMG"
},
]
Se si desidera visualizzare le informazioni relative all’entità interna 'RigheDocumento', si esegue la stessa chiamata indicando il EntityDTOName:DocumentoRigaMGDTO, per cui:
GET {{webapi_base_url}}/api/v1/{{scope}}/FW/DlevelEntityName/DocumentoRigaMGDTO?company={{defaultCompany}}
che riporterà nella response tutte le 'internalNameDeserialization' e le 'externalNameDeserialization' per il DTO specificato (riporto parziale della response):
[
{
"internalNameDeserialization": "DocumentoCorpoCOINMG",
"externalNameDeserialization": null,
"relatedDTOEntityName": "DocumentoRigaCOINMGDTO",
"relatedDTOPropertyName": "DocumentoRigaCOINMG"
},
{
"internalNameDeserialization": null,
"externalNameDeserialization": "CodIvaCO",
"relatedDTOEntityName": "VatCodeCODTO",
"relatedDTOPropertyName": "CodIva"
},
{
"internalNameDeserialization": "DocumentoCorpoProgettiMG",
"externalNameDeserialization": null,
"relatedDTOEntityName": "DocumentoRigaProgettiMGDTO",
"relatedDTOPropertyName": "DocumentoRigaProgettiMG"
},
{
"internalNameDeserialization": "RigaRiferimenti",
"externalNameDeserialization": null,
"relatedDTOEntityName": "DocumentoRigaRiferimentoMGDTO",
"relatedDTOPropertyName": "RigaRiferimenti"
},
{
"internalNameDeserialization": null,
"externalNameDeserialization": "OfficeCO",
"relatedDTOEntityName": "OfficeCODTO",
"relatedDTOPropertyName": "OfficeCO"
}
]
A questo punto si può eseguire la chiamata GET di un documento specifico e recuperare solo le informazioni desiderate, limitando ad esempio la chiamata GET :
all'entità esterna codici iva da result DocumentoRigaMGDTO ("externalNameDeserialization": "CodIvaCO")
all'entità interna progetti da result DocumentoRigaMGDTO ("internalNameDeserialization": "DocumentoCorpoProgettiMG")
all'entità esterna ClienteFornitore da result DocumentoTestataMGDTO ("externalNameDeserialization": "CustomerSupplierMG")
all'entità esterna AnagraficaDocumentoDitta da result DocumentoTestataMGDTO ("externalNameDeserialization": "CompanyDocumentMasterDataMG")
In questo caso la sintassi corretta si traduce in "[RigheDocumento[CodIvaCO][DocumentoCorpoProgettiMG]][CustomerSupplierMG],CompanyDocumentMasterDataMG}" e deve essere convertita nel formato URL-encoded per aggiungerlo come valore del parametro dlevel.
Quindi si esegue la chiamata GET del documento, il cui numreg corrisponde a 202500000024 e si valorizza nella chiamata anche il parametro dlevel=%5BRigheDocumento%7BCodIvaCO%2COfficeCO%7D%5BDocumentoCorpoProgettiMG%5D%5D%7BCustomerSupplierMG%2C%20CompanyDocumentMasterDataMG%7D: In questo modo nella response saranno riportati solo i valori dell'entità sopra descritte nell'esempio.
Si è reso disponibile anche il servizio DlevelKey, con cui è possibile avere un elenco di tutte le serializzazioni predefinite da usare nella proprietà dlevelkey e presente in tutte le chiamte GET standard del DTOname indicato come parametro nella chiamata.
Ad esempio, dato come 'DTO name' CustomerSupplierCODTO, tramite il servizio DlevelKey, se si esegue la seguente chiamata:
GET {{webapi_base_url}}/api/v1/{{scope}}/FW/DlevelEntityName/CustomerSupplierCODTO?company={{defaultCompany}}
e nella response saranno riportate alcune informazioni, tra cui il parametro 'dlevelkey':
[
{
"entityDTOName": "CustomerSupplierCODTO",
"dLevelKeyName": "DL_CustomerSupplierCO_GeneralMasterDataCO",
"deserializationLevel": "{GeneralMasterDataCO}"
},
{
"entityDTOName": "CustomerSupplierCODTO",
"dLevelKeyName": "DL_GLEntryFI_AnaGen",
"deserializationLevel": "{GeneralMasterDataCO}"
},
{
"entityDTOName": "CustomerSupplierCODTO",
"dLevelKeyName": "DL_IntrastatDataHeaderIN_AnaGen",
"deserializationLevel": "{GeneralMasterDataCO}"
}
]
At this point, for example, you execute a GET call for CustomerSupplierCO, with idclifor=5, and also set the dlevelkey parameter to DL_CustomerSupplierCO_GeneralMasterDataCO:
GET {{webapi_base_url}}/api/v1/{{scope}}/CO/CustomerSupplierCO/5?company={{defaultCompany}}
In this case, the response will display the properties of the root 'CustomerSupplier' and the entity {GeneralMasterDataCO} as shown in the JSON below:
{
"gmdUpdateAdditionalParams": null,
"clifor": 2.0,
"codAbiCg12": null,
"codCabCg13": null,
"codiceCg28": null,
"contoCg24": null,
"contorCg24": null,
"contratto": null,
"datavaliva": null,
"dittaCg18": 1000.0,
"flgArt62": 0,
"flgAttivo": 1.0,
"flgCointestati": 0.0,
"flgIntercompany": 0.0,
"ggscadfix": null,
"gruppoCg10": 80.0,
"guid": "a4630426-554a-4c95-be8b-4bb9bf52a0d2",
"idclifor": 5,
"idmediaCg99": null,
"indElenchimov3000": 99,
"intermedioCg40": null,
"lastchange": "2024-12-04T11:40:36.383",
"progREf08": null,
"tipocf": 1.0,
"idExtendedAttributeEntity": 3,
"idExtendedAttributeSubEntity": 4,
"generalMasterDataCO": {
"alias": null,
"auidAu04": null,
"cap": "20121 ",
"capcor": null,
"capfisc": "20121 ",
"cellnum": null,
"citta": "MILANO",
"cittacor": null,
"cittafisc": "MILANO",
"codfiscale": "00000452151",
"codice": 4,
"codiceCg07": 86.0,
"codiceCg15": null,
"codiceCgc0": null,
"codicecorCg07": null,
"codiceident": null,
"codicesfed": null,
"codrichiamo": null,
"cognome": null,
"comfisCg01": "F205",
"comnascita": null,
"comnascitaCg01": null,
"datanascita": null,
"datavalid": null,
"dtfinepec": null,
"dtiniziopec": null,
"faxnum": null,
"flgAnagval": 1.0,
"flgFattpa": 0,
"flgNoblacklist": 0.0,
"flgOmonimo": 0.0,
"flgPrsfis": 0.0,
"idmediaCg99": null,
"indemail": null,
"indFiscale": "Contrada Fattoria di Greg 1",
"indFiscaleEX": null,
"indirCor": null,
"indirCorEX": null,
"indirizzo": "Contrada Fattoria di Greg 1",
"indirizzoEX": null,
"indsoggrit": 0.0,
"indweb": null,
"lastchange": "2024-12-04T11:40:36.357",
"nome": null,
"partitaIVA": "00000452151",
"partiva": "00000452151",
"partivaEst": null,
"prov": "MI",
"provcor": null,
"provfisc": "MI",
"provnascita": null,
"ragSoAnag": "Greg",
"ragsoanagex": null,
"ragsocor": null,
"ragsocorex": null,
"ragsofisc": "Greg",
"ragsofiscex": null,
"rapazestCg16": null,
"sesso": 0.0,
"statofed": null,
"statofedfisc": null,
"statofiscCg07": 86.0,
"statonascitaCg07": null,
"tel1num": null,
"tel2num": null,
"idExtendedAttributeEntity": 1,
"idExtendedAttributeSubEntity": 2,
"extensionData": [],
"additionalData": {}
},
"extensionData": [],
"additionalData": {}
}
Metadata DTO
E' il servizio che, dato un EntityDTO di riferimento, produce una lista che contiene la mappatura del DTO. Per fare le analisi sulla struttura del DTO, sono forniti i seguenti strumenti:
- Servizio GET - FW/MetadataDTO/EntityDTOname
È stato introdotto un nuovo servizio GET nel modulo IntegrationInfrastructure per la risorsa MetadataDTO. Questo servizio richiede come parametro un EntityDtoName e consente di visualizzare la struttura dell'oggetto, comprese tutte le sue proprietà e le relazioni internal ed external.
Nella response sono visualizzate anche tutte le relazioni dell'entità DTO nel seguente modo:
-
Relazioni interne all’entità root o padre (che appartengono all’entità di partenza e vengono memorizzate dal CRUD nella stessa transazione)
-
Relazioni esterne all’entità (utilizzate per la semplice decodifica dei dati presenti su altre entità)
Ad esempio se si desidera visualizzare la struttura di DocumentoTestataMGDTO, si deve eseguire la seguente chiamata:
GET {{webapi_base_url}}/api/v1/{{scope}}/FW/MetadataDTO/CustomerSupplierCODTO?withdescriptions=true
Il servizio riporta in formato JSON la struttura dell’EntityDTOName. Qui di seguito è riportato solo una parte del json della response:
{
"name": "Documento",
"type": "DocumentoTestataMGDTO",
"entityName": "DocumentoTestataMG",
"properties": [
{
"propertyName": "bancaCg12",
"propertyType": "Decimal",
"isKey": false,
"mandatory": false,
"entityPropertyName": "BancaCg12",
"entityPropertyType": "System.Decimal",
"rangeValue": null,
"description": null,
"shortDescription": null,
"maxLength": 5,
"scale": 0
},
{
"propertyName": "cambio",
"propertyType": "Decimal",
"isKey": false,
"mandatory": false,
"entityPropertyName": "Cambio",
"entityPropertyType": "System.Decimal",
"rangeValue": null,
"description": null,
"shortDescription": null,
"maxLength": 12,
"scale": 6
},
{
"propertyName": "cauprestCg15",
"propertyType": "String",
"isKey": false,
"mandatory": false,
"entityPropertyName": "CauprestCg15",
"entityPropertyType": "System.String",
"rangeValue": null,
"description": null,
"shortDescription": null,
"maxLength": 4,
"scale": null
},
{
"propertyName": "causmagMg51",
"propertyType": "Decimal",
"isKey": false,
"mandatory": false,
"entityPropertyName": "CausmagMg51",
"entityPropertyType": "System.Decimal",
"rangeValue": null,
"description": null,
"shortDescription": null,
"maxLength": 4,
"scale": 0
},
]
}
Nella response sono riportate tutte le proprietà che compongono 'DocumentoTestataMGDTO', ma sono anche riportate tutte le relazioni, legate a 'DocumentoTestataMGDTO'. A titolo di esempio qui di seguito è riportata la relationName: "righe" :
"relationName": "righe",
"relationType": "DocumentoRigaMGDTO[]",
"entityRelationName": "RigheDocumento",
"entityRelationType": "DocumentoCorpoMG",
"multiplicity": "1:*",
"isExternal": false,
"meta": {
"name": "",
"type": "DocumentoRigaMGDTO",
"entityName": "DocumentoCorpoMG",
"properties": [
{
"propertyName": "alivacompCg28",
"propertyType": "String",
"isKey": false,
"mandatory": false,
"entityPropertyName": "AlivacompCg28",
"entityPropertyType": "System.String",
"rangeValue": null,
"description": null,
"shortDescription": null,
"maxLength": 4,
"scale": null
},
]
}
In questo caso si può eseguire una nuova chiamata GET su DocumentoRigaMGDTO per prendere visione di tutte le proprietà e di tutte le relazioni per il DocumentoRigaMGDTO, e così via.
Inoltre è anche possibile utilizzare alcuni parametri aggiuntivi: il Parametro withdescriptions=true che serve per visualizzare le descrizioni nelle proprietà e il parametro Headers: Accept=application/xml per avere un result in formato xml.
- Lookup Service - FW/lookup/MetadataDTOView
È stato introdotto un nuovo servizio che permette di vedere,tramite lookup, SOLO se le proprietà sono esposte sul DTO (sono visualizzate solo le righe con PropertyDTOName NOT NULL).
Si deve eseguire la seguente chiamata:
POST {{webapi_base_url}}/api/v1/{{scope}}/FW/lookup/MetadataDTOView?metadata=true&company={{defaultCompany}}&_op=search
Con tale lookup è possibile eseguire delle selezioni, ad esempio utilizzando il nome della tabella oppure il nome della colonna, per ricavare il nome dell’entità collegata.
Partendo da 'EntityName' presa in considerazione nel precedente esempio 'DocumentoTestataMG', si può eseguire la chiamata POST con il seguente body:
{
"filters": {
"items": [
{
"operator": 0,
"comparer": 0,
"propertyName": "EntityName",
"value": "DocumentoTestataMG"
}
],
"orderingProperties": {
"EntityName": 0
}
},
"pageSize": 0,
"pageNumber": 0
}
e nella response saranno riportate le proprietà esposte per il DTO preso in esame.
Oppure si può eseguire una selezione partendo dal nome della tabella. Ad esempio indicando come TableName=CG44_CLIFOR, come qui di seguito riportato:
{
"filters": {
"items": [
{
"operator": 0,
"comparer": 0,
"propertyName": "TableName",
"value": "CG44_CLIFOR"
}
],
"orderingProperties": {
"EntityName": 0
}
},
"pageSize": 0,
"pageNumber": 0
}
nella response saranno riportate tutte le proprietà esposte. Qui di seguito è riportato solo una parte del json della response a titolo di esempio:
{
"name": "MetadataDTOView",
"resources": [],
"pageNumber": 0,
"pageSize": 77,
"data": [
[
"CustomerSupplierCO",
"CustomerSupplierCODTO",
"Property",
null,
null,
"Tipocf",
"Tipocf",
"Tipo Cliente / Fornitore",
null,
"CG44_CLIFOR",
"CG44_TIPOCF",
"decimal",
1,
true,
null,
"0= Cliente - 1= Fornitore",
false
],
],
}
Oppure è anche possibile effettuare un'ulteriore selezione tramite il nome della colonna, per cui indicando FieldName=CG44_TIPOCF:
{
"filters": {
"items": [
{
"operator": 0,
"comparer": 0,
"propertyName": "FieldName",
"value": "CG44_TIPOCF"
}
],
"orderingProperties": {
"EntityName": 0
}
},
"pageSize": 0,
"pageNumber": 0
}
nella response saranno riportate tutte le proprietà esposte dove è utilizzato il suddetto FieldName:
{
"name": "MetadataDTOView",
"resources": [],
"pageNumber": 0,
"pageSize": 4,
"data": [
[
"CustomerSupplierCO",
"CustomerSupplierCODTO",
"Property",
null,
null,
"Tipocf",
"Tipocf",
"Tipo Cliente / Fornitore",
null,
"CG44_CLIFOR",
"CG44_TIPOCF",
"decimal",
1,
true,
null,
"0= Cliente - 1= Fornitore",
false
],
[
"CustomerSupplierFI",
"CustomerSupplierFIDTO",
"Property",
null,
null,
"Tipocf",
"Tipocf",
"Tipo Cliente / Fornitore",
null,
"CG44_CLIFOR",
"CG44_TIPOCF",
"decimal",
1,
true,
null,
"",
false
],
]
}
- Query Descriptor on FW/Lookup service
Nell'elenco delle lookup disponibili, richiamabile mediante il servizio Get di FWK "FW/Lookup", sono stati definiti i parametri obbligatory da indicare nella SearchDTO.
Ad esempio: il servizio FW/Lookup ci restituisce la Lookup relativa all'entità ProjectWH
{
"lookupName": "ItemProjectWH",
"description": "ItemProjectWH",
"href": "/api/v1/LDB_TESTWAPILEG/WH/Lookup/ItemProjectWH",
"typeQuery": "QueryDescriptor",
"parametersQueryDescriptor": "ProjectCode"
}
Per questa entità i parametri devono essere riporati nel modo di seguito indicato:
{
"parameters": {
"ProjectCode": "1"
}
}
Upload/Download CLOUD files
Il servizio EditPathFW consente di gestire l'upload e il download dei file su Cloud. In particolare mediante la chiamata:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/FW/EditPathFW/uploadfile?company={{defaultCompany}}&user=admin
è possibile effettuare l'upload del file specificato nel body che dovrà essere di tipo form-data, nel quale devono essere specificati i seguenti valori Key con i relativi Value:
- file (di tipo file) e Value: --indicare il nome del file che si vuole caricare sul cloud
- fixedPathType (di tipo Text) e Value: UseFileTemp
- relativePath (di tipo Text) con Value: import
Con la chiamata:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/FW/EditPathFW/getfilelist?company={{defaultCompany}}&user=admin
è possibile ottenere la lista dei file caricati sul cloud
{
"files": [
"nomefile.xxx"
]
}
E', inoltre, possibile effettuare il download del file, prima caricato sul cloud, con la seguente chiamata:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/FW/EditPathFW/getfile?company={{defaultCompany}}&user=admin
Nel body con i parametri "esAttachment" e "deleteAfter" è possibile specificare se scaricare il file come allegato e se disporre l'eliminazione dopo averne effettuato il download.
{
"asAttachment": false,
"deleteAfter": false,
"filename": "TestFile.txt",
"fixedPathType": "UserFileTemp",
"relativePath": "import"
}
Infine è possibile eliminare il file precedentemente caricato sul cloud con il seguente servizio:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/FW/EditPathFW/removefile?company={{defaultCompany}}&user=admin
riportando le seguenti informazioni nel body:
{
"filename": "filename.xxx",
"fixedPathType": "UserFileTemp",
"relativePath": "import"
}
Task Exec
Viene introdotto un servizio che consenta di poter eseguire azioni definite come "insiemi" presenti nel modulo "Schedulazione Applicativi" (legacy).
Nell'esempio della schermata si vuole creare una attività pianificata per il job con codice 4, che contiene il programma "3166" ("Schedulazione operazioni TS Commerce"). Quindi, proseguendo nella creazione della pianificazione si passa alla schermata seguente:
Viene quindi creata una nuova attività con codice 3222, nell'esempio "Attivita3222" e, dopo aver indicato l'utente tecnico per le schedulazioni Windows, mediante l'apposito pulsante è possibile intervenire sulla periodicità della pianificazione:
Si riporta di seguito la chiamata:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/CO/PgmExec/pgmexecschedulerasync?company={{defaultCompany}}&user=admin'
con il relativo body:
{
"idTaskScheduled": "3222",
"timeoutSeconds": 90,
"skipIfRunning": true
}
Il numero indicato nel campo "idTaskScheduled" indica l'identificativo che rappresenta l'"insieme" delle attività schedulate. Ad esempio il valore 3122 indica l'insieme delle attività relative a TS Commerce
License Service
Dalla versione 2025002000 è stato introdotto il nuovo servizio LicenseFW che sostituisce il precedente FW/Licenze reso obsoleto. L'unica azione possibile attualmente è la GET per ottenere tutte le informazioni riguardo un id di licenza passato tramite parametro:
GET {{webapi_base_url}}/{{api}}/v1/{{scope}}/FW/LicenseFW/info/{{idLicenza}}?company={{defaultCompany}}
Un esempio di json di risposta è il seguente:
{
"codLicenza": 1055,
"numLicenza": "XXYYZZW0",
"keyAttivazione": "9gTE8Rwo",
"dataRilascio": "2025-04-14T00:00:00",
"partitaIvaCliente": "11281128112",
"partitaIvaRivenditore": "01030103010",
"licenzaDemo": 0,
"numeroPostazioni": 2,
"quantita": 0,
"isValid": true,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
AsyncSchedulerFW - Schedulazione applicativi
Con la build 2025003000 è stata introdotta la versione V2 dell'endpoint AsyncSchedulerFw. Questo endpoint permette di schedulare i programmi dell'applicativo. Ecco un esempio pratico:
Post {{webapi_base_url}}/{{api}}/v2/{{scope}}/fw/asyncschedulerfw?company={{defaultCompany}}
Un esempio di json di risposta è il seguente:
{
"additionalInfo": "Esecuzione di pulizia dei dettagli di elaborazione",
"asyncCatalogId": "CLEAN_PROCESSING_DETAILS",
"cronExpression": "0 0/30 * * * ?",
"endUtcDateTime": "2025-09-30T08:00:00.073",
"isDisabled": false,
"isWithCompany": true,
"lastExecutionUtcDateTime": "2025-09-26T08:00:00.073",
"nextExecutionUtcDateTime": "2025-09-26T08:30:00",
"serializedParameter": "{ \"daysToKeep\": 30 }",
"startUtcDateTime": "2023-02-20T15:03:31.29",
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Documenti
Inserimento documento con dati minimi
La risorsa "Documento" può essere utilizzata per inserire / eliminare / modificare un documento in TSE. La risorsa è utilizzabile per l'inserimento di un qualsiasi tipo di documento, basta semplicemente cambiare il codice documento nella chiamata.
Affinché le informazioni passate alla WebAPI documenti con il relativo DTO siano effettivamente recepite e memorizzate è necessario che il wizard del codice documento utilizzato le gestisca sull'interfaccia utente. Quindi in fase di progettazione della soluzione è opportuno effettuare sempre un doppio check per assicurarsi che un documento inserito da interfaccia utente con le medesime informazioni che vengono passate via WebAPI sia correttamente inserito.
L'inserimento di un documento può avvenire in modo sincrono con il metodo POST.
Si tenga presente che per inserire un documento non è necessario valorizzare tutte le proprietà del complesso DTO che lo rappresenta.Ecco un esempio di inserimento minimale del documento con le informazioni minimali di testata e Riga di tipo articolo, con codice articolo e quantità
Post {{webapi_base_url}}/{{api}}/v2/{{scope}}/MG/DocumentMG?company={{defaultCompany}}
con il seguente body:
{
{
"callOptions": {
"forceStampExpensesToZero": false,
"forceCollectionExpensesToZero": false,
"lockInsertExistingDocument": false,
"excludeLoadingMultipleAgents": true,
"excludeHeaderVat": false,
"disableLetterOfIntent": true,
"excludeCSExpensesFixedTexts": false,
"disableExistingItemCheck": false
},
"companyCode": 1000,
"currencyCode": "EURO",
"customerSupplierCode": 1.0,
"customerSupplierType": 0.0,
"documentCode": "CLI-ORDINE",
"documentDate": "2025-10-15T00:00:00",
"documentSubtype": 1.0,
"documentType": 21.0,
"documentTypeNumbering": 39.0,
"registrationDate": "2025-10-15T00:00:00",
"storageCode": "00",
"vatCode": "317",
"sectionalCode": "00",
"officeCode": "YYY",
"agents": [],
"rows": [
{
"callOptions": {
"forcePriceDiscount": false
},
"companyCode": 1000,
"description": "Descrizione articolo",
"itemCode": "ART001",
"qty1": 1.000,
"qty2": null,
"rowProgressive": 2.0,
"rowType": 0
}
],
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
}
Alcune osservazioni/confronti sulla versione V2
il campo "ditta" o "dittaCg18" (il codice della ditta di lavoro) è stato rinominato in companyCode proprietà in DocumentHeaderV2MG.
"anagraficaDocumentoDitta": La proprietà è stata rimossa è gestita con il campo documentCode. Valorizzando il campo indicato il sistema riconosce autometicamente se il codice documento è standard o personalizzato.
"customerSupplierMG": La proprietà di tipo customerSupplierMGDTO è stata eliminata. Il cliente o il fornitore a cui viene intestato il documento è stato gestito con i campi customerSupplierCode e customerSupplierType
Ad esempio per intestare il documento al cliente con codice 123 è necessario valorizzare il campo "customerSupplierCode": 123 e "customerSupplierType": 0.0
{
"customerSupplierCode": 123,
"customerSupplierType": 0.0,
}
Si noti che "customerSupplierCode" è il codice del cliente (o del fornitore per documenti di tipo fornitore) e non il suo ID presente sulla tabella CG44_CLIFOR. Si ricorda infine che se il codice documento prevede il cliente o il fornitore, è necessario definire l'indicatore 'customerSupplierType' con i possibili valori del campo CG44_TIPOCF della tabella CG44_CLIFOR che sono:
0 per i clienti 1 per i fornitori
"sectionalCode": il sezionale della numerazione del documento (es. "sezdoc": "00")
"storageCode": il campo storageCode rappresenta il deposito da movimentare.
Quindi ad esempio, lavorando sulla ditta 100, per ordinare la merce sul deposito "00", sarà necessario valorizzare il campo storageCode in questo modo:
{
"storageCode": "00",
}
"Rows": l'array delle righe da inserire nel documento; è un array di oggetti di tipo DocumentRowV2MGDTO. La tipologia di riga attualmente gestite nel corpo documento sono le seguenti:
- Articolo (rowType = 0)
- Articolo manuale (rowType = 1)
- Descrittiva (rowType = 2)
- Spesa (rowType = 4)
- Testo Fisso (rowType = 6)
- Nodo (rowType = 15)
- Attività (rowType = 16)
- Spesa di progetto (rowType = 17)
Le altre tipologie utilizzabili dall'interfaccia di emissione diretta documenti non sono supportate.
A seconda della tipologia di riga che si desidera inserire nel documento, si deve specificare un diverso "rowType", come sopra descritto. Per ogni riga documento, occorre indicare almeno il progressivo riga, il codice e la quantità.
- Per le righe di tipo articolo occorre almeno indicare progressivo riga, codice articolo, descrizione articolo e quantità. La proprietà rowType prende il valore 0 di default, se non valorizzata.
{
"rowProgressive": 1.0,
"itemCode": "ART001",
"description": "Descrizione articolo ART001",
"qty1": 1.000
}
NOTA BENE: Nel caso in cui si inseriscano righe documento di tipo articolo e un codice articolo preveda l'esplosione automatica di righe aggiuntive, il rowProgressive è ricalcolato in automatico dalla procedura.
- Per le righe di tipo spesa varia occorre almeno indicare "rowType", "rowProgressive", quantità (normalmente unitaria) e codice spesa come nel seguente esempio:
{
{
"rowProgressive": 4,
"rowType": 4.0,
"qta1": 1.000,
"variousExpenseCode": "ST",
}
}
Recupero dei prezzi in inserimento delle righe Se i prezzi e gli sconti degli articoli di magazzino inseriti nel corpo del documento vengono passati con valore zero, allora la logica di business li valorizza in base alla configurazione del recupero prezzo impostata sulla parametrizzazione del codice documento utilizzato.
Se il prezzo e gli sconti passati nel DTO sono diversi da zero, allora i valori proposti dalla logica del recupero prezzo da configurazione verranno sovrascritti con i valori passati nel DTO.
Per quanto riguarda gli scenari dei Documenti, vengono resi disponibili direttamente all'interno della chiamata POST (Create) del modulo IntegrationMG\DocumentMG dello swagger alcuni esempi:
Tramite il Try it out sarà possibile eseguire automaticamente la chiamata, sostituendo i segnaposti indicati negli esempi con i relativi dati opportuni.
Esempi disponibili di Documenti su Swagger:
Default (complete): riporta il body completo di chiamata; Min required: Informazioni minimali obbligatorie di testata; Order: esempio di body di un documento di tipo Ordine; Delivery Note: esempio di body di un documento di tipo bolla; Invoice: esempio di body di un documento di tipo fattura; Transfer warehouses: esempio di body di un documento trasferimento tra depositi.
Proprietà callOptions
La proprietà callOptions consente di raggruppare tutte le opzioni/parametri di chiamata che non sono dei veri campi dell’entità.
Attualmente sono disponibili le seguenti opzioni:
- flgSpbolliForceZero (default false): impostare a true se si vuole forzare il valore = 0 del flag spese bolli;
- flgSpincasForceZero (default false): impostare a true se si vuole forzare il valore = 0 del flag spese incassi;
- esclusioneAgentiMultipli (default false): impostare a true per escludere il caricamento degli agenti multipli in testata;
- esclusioneIvaTestata (default false): impostare a true per forzare Null il codice Iva di testata del documento;
- flgLockOnDocExist (default false): impostare a true per bloccare l'inserimento di un documento già esistente;
- disableLetterOfIntent (default false): impostare a true per disattivare le lettere di intento;
- esclusioneSpeseTestiCliFor (default false): impostare a true per escludere la proposta delle righe spese e testi fissi di default del Cliente;
- flgDisableItemControl (default false): impostare a true per disabilitare il controllo di esistenza degli articoli;
- enableAdditionalValidations (default false): impostare a true per attivare il controllo di obbligatorietà in base ai parametri definiti in Console parametri lotti.
Interrogazione Wizard Personalizzazione Documenti
Servizio per visualizzare tutti i moduli attivi associati a un documento in base alla sua configurazione con la procedura guidata Documento. Ecco un esempio pratico:
Esempio di GET per estrarre la lista dei moduli attivi per documento:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/MG/CompanyDocumentMasterDataMG/CLI-ORDINE/enablementwizard?company={{defaultCompany}}
il servizio ritorna il seguente Json:
{
"document": "CLI-ORDINE ",
"documentCustom": 1.0,
"description": "Ordine da clienti",
"isDocumentHeader": true,
"isDocumentHeaderReference": true,
"isDocumentTotal": true,
"isDocumentHeaderShipmentData": true,
"isDocumentHeaderCustomizedAttribute": true,
"isDocumentHeaderOrder": true,
"isDocumentHeaderStandardAttribute": true,
"isDocumentHeaderCommission": true,
"isDocumentHeaderAccrual": true,
"isDocumentHeaderProject": true,
"isDocumentHeaderAgent": true,
"isDocumentRow": true,
"isDocumentRowOrder": true,
"isDocumentRowCommission": true,
"isDocumentRowReference": true,
"isDocumentRowCustomizedAttribute": true,
"isDocumentRowStandardAttribute": true,
"isDocumentRowPackaging": false,
"isDocumentRowProject": true,
"isDocumentRowAccrual": true,
"isDocumentRowLot": false,
"isDocumentRowAnalyticalCorrelation": true,
"isDocumentRowIntra": false
}
Gestione dell'Agente Preferenziale
È possibile gestire l'agente preferenziale in fase di salvataggio di un cliente (CustomerSupplierCO). L'eventuale agente associato al cliente viene inserito negli agenti multipli come agente preferenziale. Sul cliente è anche possibile definire ulteriori agenti multipli.
In fase di inserimento di un documento, sono recuperati gli agenti multipli memorizzati in Anagrafica cliente.
Se però in inserimento di un documento si specificano agenti diversi nella proprietà DocumentoTestataAgentiMG, allora questi ultimi sostituiscono quelli recuperati dall'anagrafica cliente.
Tramite la proprietà callOptions è possibile escludere o meno gli agenti multipli.
EsclusioneAgentiMultipli = false (con proprietà callOptions o parametro=0 su versione 8)
- Se nel DTO non viene valorizzata la proprietà
DocumentoTestataAgentiMG, il sistema popolerà la tabellaDO29_DOCTESAGENTIcon gli agenti collegati al cliente e recuperati con le usuali logiche utilizzate dal gestionale in fase di inserimento del documento da interfaccia. - Se nel DTO viene valorizzata la proprietà
DocumentoTestataAgentiMG, il sistema popolerà la tabellaDO29_DOCTESAGENTIcon gli agenti di cui al punto precedente e con gli agenti passati inDocumentoTestataAgentiMG(viene fatta l'unione dei due insiemi di agenti).
EsclusioneAgentiMultipli = true (con proprietà callOptions o parametro=1 su versione 8)
- Il sistema popolerà la tabella
DO29_DOCTESAGENTIcon i soli eventuali agenti passati inDocumentoTestataAgentiMG, ignorando quelli che verrebbero proposti da configurazione del cliente.
Ricerca prezzi da Listini prioritari
Recupero dei prezzi in inserimento delle righe da listini prioritari: servizio PricePriorityLI Il servizio consente di eseguire una ricerca prezzi da listini prioritari attraverso il servizio PricePriorityLI
L'esempio allegato riporta il prezzo dei listini prioritari elaborati in base alla Tabella priorità definita su TSE, utilizzati per generare il PricePriorityLI e visualizza nel Result ("RowElaboratePriceList"), se impostato il parametro "ResultElaboratePriceList" = true.
Parametri
- Tipo prezzo (typeSalePurchaseProd):
Decimal(DO11_TIPOCF_CG44/2)
0 = Vendite (default)
1 = Acquisti
2 = Produzione - Codice Articolo (CodartMg66):
String(DO30_CODART_MG66) — mandatory - Codice Cliente/Fornitore:
Decimal(DO11_CLIFOR_CG44) - Data Registrazione:
Datetime(DateElab) — mandatory - Quantità 1 (di riga) (qty1):
Decimal(DO30_QTA1) - Numero Listino (numPriceList):
Decimal(DO11_LISTMAG) - Codice Deposito (codDepMg58):
String(DO30_CODDEP_MG58) - Attivazione visualizzazione elenco dei prezzi elaborati (resultElaboratePriceList): if set =
true
Esempio
{
"typeSalePurchaseProd": 0,
"codArtMg66": "ART_LI",
"cliforCg44": 1,
"dateElab": "2024-06-14 00:00:00",
"qty1": 0,
"numPriceList": 1,
"codDepMg58": "00",
"resultElaboratePriceList": true
}
Ricerca prezzi da Listini parametrici
Recupero dei prezzi in inserimento delle righe da listini parametrici: servizio PriceParametricLI Il servizio PriceParametricLI consente di individuare il prezzo in base ai listini parametrici partendo dal codice priorità definito in Tabella priorità su TSE.
Questo servizio richiede i Parametri "PriceParametricParameters" e richiama la store Procedure SPLP_QUOTPROBELIST per recuperare il prezzo corrente con eventuali sconti in "PriceParametricLI".
Viene previsto anche un parametro per richiedere il dettaglio dell’esito dell’elaborazione dei listini parametrici che permette di capire come si è formato il prezzo in base alla tabella priorità e ai provider utilizzati.
ATTENZIONE!: Attualmente la store procedure gestisce anche le condizioni commerciali e le provvigioni per piede documento che in questa prima fase non sono gestite, (viene passato alla store procedure il parametro fisso @RIGA_PIEDE=0).
Parametri
- ResultElab bool (default false) Parametro per attivare l’esito dell’elaborazione listini parametrici. Se attivato è necessario passare alla store procedure il nome di una tabella temporanea dove vengono memorizzate tutte le righe dei prezzi che sono state trovate per generare il prezzo finale;
- dataReg - Data registrazione ___ obbligatorio
- CodTabPriority int64 (ID_TABPRIORITA) ___ obbligatorio Attraverso il codice viene ricavato l’IdTabPriority da passare alla store procedure
- tipocfCg44 - Tipo Cliente/fornitore Decimal (DO11_TIPOCF_CG44) ATTENZIONE: Conversione tipo documento: cliente= 0--> diventa 1 e fornitore=1 diventa 2 da passare alla store procedure
- cliforCg44 - Codice Cliente/fornitore Decimal (DO11_CLIFOR_CG44) Tutti i campi dei clienti/fornitori vengono letti automaticamente
- codartMg66 - String (DO30_CODART_MG66) ___ obbligatorio
- documentData - Data documento Datetime (DATADOC) Se non valorizzata viene valorizzata con data registrazione
Esempio
{
"resultElab": false,
"dataReg": "2023-06-22T13:34:35.125Z",
"CodTabPriority": "TVEN",
"tipocfCg44": 0,
"cliforCg44": 2,
"codartMg66": "2",
"documentData": {
"qta1": 10,
"documMg36": "CLI-FATIMM"
}
}
Lettura lista dei report per Documento
Tramite il servizio Print/ReportName è possibile ottenere una lista di tutti i report utilizzabili per il servizio printPDF e generare lo streamPDF.
Esempio di GET per estrarre la lista dei report associati al documento:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/MG/Documento/{{NumReg}}/print/reportname?user=admin&company={{azienda}}
il servizio ritorna il seguente Json:
{
{
"documentReports": [
{
"reportName": "CRMG_DDT_PERS.rpt",
"description": "Fatt con rpt ddt",
"path": "C:\\Program Files (x86)\\TeamSystem Software\\Enterprise\\Userfile\\Rpt",
"default": 1,
"document": "1-C-FATIMM"
},
{
"reportName": "CRMG_STINTINV_SINT.rpt",
"description": "Fat Imm CRMG_STINTINV_SINT",
"path": "C:\\Program Files (x86)\\TeamSystem Software\\Enterprise\\Userfile\\Rpt",
"default": 0,
"document": "1-C-FATIMM"
},
{
"reportName": "CRMG_FIM_es_LAS.rpt",
"description": "ORDf",
"path": "C:\\Program Files (x86)\\TeamSystem Software\\Enterprise\\Userfile\\Rpt",
"default": 0,
"document": "1-C-FATIMM"
}
]
}
}
Servizio Print documenti: generazione stampa documento su pdf
Per consentire la stampa in pdf di un documento è possibile recuperare con una GET, tramite il comando Print, lo streamPDF di un documento che dovrà essere poi decodificato e convertito in PDF tramite un qualsiasi programma di conversione.
Esempio di GET per generare lo streamPDF:
webapi_base_url/api/v1/{{scope}}/MG/Documento/<NumeroDocumento>/print?company={{defaultCompany}}
il servizio ritorna il seguente Json:
{
"streamPDF": "JVBERi0xLjMgCiXi48/ …………………………………….. ",
"error": ""
}
Il contenuto dello streamPDF deve essere copiato ed inserito in un qualsiasi programma di conversione per procedere con la decodifica e la conversione in pdf.
Attenzione - in caso di Stampa archiviata e valida: nel caso di stampa archiviata e valida, è necessario rieseguire l’esportazione ed il programma recupera il pdf archiviato sul disco.
Estensione della funzionalità di Print PDF
Tramite il servizio Print PDF, oltre alla generazione del documento standard tramite streamPDF, è possibile stampare report personalizzati associati al tipo di documento Esempio di richiesta GET per generare lo streamPDF
{{webapi_base_url}}/api/v1/{{scope}}/mg/documento/{{numreg}}/print?user=admin&company={{azienda}}&reportname=CRMG_STINTINV_SINT.rpt
Risposta del servizio:
{
"streamPDF": "JVBERi0xLjMgCiXi48/ …………………………………….. ",
"error": ""
}
Il campo reportName consente la selezione dinamica del layout di stampa desiderato, sia in formato Crystal che Jasper, rendendo il sistema più flessibile alle configurazioni personalizzate dei clienti.
Gestione KIT
E' possibile ricercare, inserire, modificare e cancellare un kit e di conseguenza utilizzarlo all’interno dei documenti opportunamente configurati (Parametri Generali documenti-Personalizzazione) con relativa esplosione dei componenti nelle righe documento.
Utilizzando l'entità Master KitWH e Detail KitLinkWH è possibile creare kit semplici, definendo solo articolo e quantità
{
"codProductMg66": "BICI",
"dittaCg18": {{azienda}},
"exclusionChild1Mg82": null,
"exclusionChild2Mg82": null,
"exclusionChild3Mg82": null,
"exclusionChild4Mg82": null,
"exclusionFather1Mg82": "OR",
"exclusionFather2Mg82": "BO",
"exclusionFather3Mg82": "FA",
"exclusionFather4Mg82": "PR",
"optionProductMg5e": "",
"kitLinkWH": [
{
"codComponentMg66": "BICI2",
"optionComponentMg5e": "",
"qtyComponent1": 10.000000
},
{
"codComponentMg66": "MSE003",
"qtyComponent1": 15.000000
}
]
}
o creare kit completi, dove è possibile valorizzare ulteriori proprietà:
{
"codProductMg66": "MSE002",
"dittaCg18": {{azienda}},
"exclusionChild1Mg82": null,
"exclusionChild2Mg82": "BO",
"exclusionChild3Mg82": "PR",
"exclusionChild4Mg82": null,
"exclusionFather1Mg82": "OR",
"exclusionFather2Mg82": "BO",
"exclusionFather3Mg82": "FA",
"exclusionFather4Mg82": "PR",
"optionProductMg5e": "",
"kitLinkWH": [
{
"codComponentMg66": "BICI2",
"optionComponentMg5e": "",
"StartingDate": "2024-01-15T00:00:00",
"endingDate": "2024-12-31T00:00:00",
"qtyComponent1": 13.000000,
"qtyComponent2": 10.000000,
"fixedQta": 1,
"typeBomLink": 3,
"typeOptionalLink": 1,
"typeVal": 2,
"costComponent": 10.0000
},
{
"codComponentMg66": "BICI",
"optionComponentMg5e": "",
"StartingDate": "2024-01-15T00:00:00",
"edningDate": "2024-06-31T00:00:00",
"qtyComponent1": 25.000000,
"qtyComponent2": 33.000000,
"fixedQta": 1,
"typeBomLink": 3,
"typeOptionalLink": 0,
"typeVal": 3,
"costComponent": 150.0000
}
]
}
Componenti KIT che sono a loro volta KIT
Nella gestione di un KIT, tramite la proprietà IdKitNode è possibile verificare se un componente è una materia prima oppure è a sua volta un KIT.
Per esempio, si esegue la ricerca del codice articolo KSE001 (che corrisponde a idKit=32) tramite la seguente chiamata:
GET {{webapi_base_url}}/{{api}}/v1/{{scope}}/WH/KitWH/{{idKit}}?company={{defaultCompany}}&utente=admin
La response contiene due righe KIT, dove il codComponentMg66=KSE002 è a sua volta un Kit, mentre il codComponentMg66=00003 è una materia prima. Di conseguenza il parametro "idKitNode" assume una volta il valore null per indicare che è una materia prima, mentre nell'altro caso questo parametro ha un valore numerico (nel nostro esempio 31.0), che corrisponde all'identificativo KIT del codComponentMg66=KSE002 che è a sua volta un KIT.
La response di esempio è:
{
"codProductMg66": "KSE001",
"codTypeBom": "",
"dittaCg18": {{azienda}},
"idKit": 32.0,
"kitLinkWH": [
{
"codComponentMg66": "KSE002",
"idKit": 32.0,
"idKitLink": 46.0,
...
"idKitNode": 31.0, // id KIT figlio
...
},
{
"codComponentMg66": "00003",
...
"idKit": 32.0,
"idKitLink": 47.0,
"idKitNode": null, // materia prima
...
}
],
}
Inserimento Documento con Codice Articolo di Tipo Kit
Tramite una normale chiamata di inserimento documento, è possibile indicare tra le righe documento anche un codice articolo di tipo Kit. L'esplosione dei relativi componenti e la modalità di esplosione deve essere definita preventivamente da Erp in Parametri generali documenti oppure da Personalizzazione documenti oppure da Personalizzazione documenti azienda, a seconda delle esigenze aziendali.
Il seguente esempio prevede l'inserimento di un DDT tramite il Tipo documento 'C-DDT' personalizzato che prevede due righe documento:
- Una con un codice articolo normale.
- L'altra con un codice articolo di tipo kit.
Il suddetto Tipo documento prevede l'esplosione dei componenti del Kit e che ogni componente sia riportato sul documento come riga descrittiva.
{
"valutaCg08": "EURO",
"anagraficaDocumentoDitta": {
"codDocumMg36": "C-DDT",
"indStaperMg36": 1.0
},
"customerSupplierMG": {
"tipocfCg40": 1,
"cliFor": 1
},
"sezdoc": "00",
"storageWH": {
"codDep": "00"
},
"righe": [
{
"progrRiga": 1.0,
"codartMg66": "ART001",
"descart": "Articolo ordinario",
"qta1": 15.000
},
{
"progrRiga": 1.0,
"codartMg66": "MSE002",
"descart": "Articolo kit",
"qta1": 15.000
}
]
}
Generazione automatica di documenti Carico prodotti Kit e di Scarico componenti Kit
Se il documento di vendita o di impegno da cliente contengono righe articolo di tipo Kit, ma il tipo documento utilizzato non prevede la generazione del Carico prodotti Kit e dello Scarico componenti Kit oppure se si inserisce un documento di Carico prodotti Kit che non prevede l'esplosione dei componenti, è possibile effettuarlo in un secondo momento tramite il servizio KitDocumentService.
Il servizio prevede due azioni:
-
unloadcomp che consente di eseguire lo scarico componenti Kit al primo livello, in base ai documenti di Carico prodotti Kit in essere;
-
loadkit che permette di creare il documento di Carico prodotto Kit ed il documento di Scarico componenti Kit, a fronte di documenti di vendita o di impegni cliente presi in considerazione.
Generazione lotti per Carico Prodotti Kit e per Scarico Componenti Per una corretta generazione dei documenti in oggetto, si ricorda che la movimentazione lotti per il documento Carico prodotti deve essere definita nella Console Lotti per "Articolo singolo", mentre per il documento Scarico componenti deve essere definita per "Articoli multipli".
Generazione documenti Scarico componenti Kit
Il servizio KitDocumentService, tramite l'azione unloadcomp, consente di eseguire lo scarico componenti Kit al primo livello, in base ai documenti di Carico prodotti KIT inseriti per i quali non si è eseguita l'esplosione componenti ed il relativo scarico componenti. Se sono presenti anche i Semilavorati, viene eseguito un documento di carico per il Semilavorato ed un documento di scarico per i componenti del Semilavorato.
Qui di seguito è riportato un esempio pratico: Il codice articolo KIT è composto dal codice articolo (componente1) 00001 e dal codice articolo (componente2) 00002. Si inserisce un documento di Carico prodotti Kit con due righe articolo, entrambe riferite al codice articolo KIT ma per quantità e prezzo diversi. Si genera il numero documento 40 del 08/07/2025 e non si effettua l'esplosione componenti.
Per poter generare in un secondo momento il documento di Scarico componenti Kit, si deve eseguire la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/KitDocumentService/unloadcomp?company={{defaultCompany}}
Nel body della chiamata si devono indicare i parametri necessari per generare il nuovo documento (unloadComponentKitParameter) e definire i parametri necessari per una sorta di selezione/ricerca a livello di testata documento (headLoadDocumentsFilter) e/o a livello di riga documento(rowLoadDocumentsFilter), per cui si definiscono gli estremi del documento di Carico prodotti Kit preso in esame e/o il codice articolo Kit. I suddetti parametri sono obbligatori (come da interfaccia):
{
"loadDocumentCodeFilter": "INT-CARKIT",
"unloadComponentKitParameter": {
"documentCode": "INT-SCARKIT",
"postingDate": "2025-07-08",
"documentDate": "2025-07-08",
"documentSectional": "00",
"documentNumber": 0,
"storageCode": "00",
"indExplosionLevel": "0",
"numberLevel": 1,
"indSemiFinishedProducts": "0",
"recalculateCostKitProduct": false,
"includeBOMComponents": false
},
"headLoadDocumentsFilter": {
"filters": {
"items": [
{
"propertyName": "datadoc",
"comparer": 0,
"value": "2025-07-08"
},
{
"operator": 1,
"propertyName": "numdoc",
"comparer": 0,
"value": 40
}
]
}
},
"rowLoadDocumentsFilter": {
"filters": {
"items": [
{
"propertyName": "codartMg66",
"comparer": 0,
"value": "KIT"
}
]
}
}
}
La response riporta l'elenco dei documenti generati, in base alle righe articolo, oggetto della ricerca sopra evidenziata.
{
{
"numRegLoadProductKit": [],
"numRegUnloadComp": [
"202500000897",
"202500000898"
]
}
}
Generazione documenti Carico Prodotto Kit e Scarico componenti Kit contemporaneamente
Il servizio KitDocumentService, tramite l'azione loadkit, permette di generare i documenti di Carico prodotti Kit, a fronte di documenti di vendita inseriti. Per ogni documento di Carico prodotti Kit è possibile generare anche contemporaneamente i relativi documenti di Scarico componenti Kit.
Qui di seguito è riportato un esempio pratico: Si prende in considerazione sempre il codice articolo KIT, composto dal codice articolo (componente1) 00001 e dal codice articolo (componente2) 00002. Si inserisce un documento di vendita con una riga articolo KIT con numero documento 408 del 08/07/2025 e non si effettua l'esplosione componenti.
Per poter generare il documento di Carico Kit ed il documento di Scarico componenti Kit, si deve eseguire la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/KitDocumentService/loadkit?company={{defaultCompany}}
Nel body della chiamata si devono indicare i parametri necessari per generare il nuovo documento di Carico Prodotti Kit (loadProductKitParameter) ed i parametri per il nuovo documento Scarico componenti Kit(unloadComponentKitParameter). Nel body è anche possibile applicare dei filtri di ricerca a livello di Testata documento, tramite i parametri headLoadDocumentsFilter e/o a livello di riga (rowLoadDocumentsFilter), in questo caso si specificano quindi gli estremi del documento di vendita interessato e/o il codice articolo Kit preso in esame:
{
{
"loadProductKitParameter": {
"documentCode": "INT-CARKIT",
"postingDate": "2025-07-08",
"documentDate": "2025-07-08",
"documentSectional": "00",
"documentNumber": 100
},
"unloadComponentKitParameter": {
"documentCode": "INT-SCARKIT",
"postingDate": "2025-07-08",
"documentDate": "2025-07-08",
"documentSectional": "00",
"documentNumber": 101,
"storageCode": "00",
"indExplosionLevel": "0",
"numberLevel": 1,
"indSemiFinishedProducts": "0",
"recalculateCostKitProduct": false,
"includeBOMComponents": false
},
"headUnloadDocumentsFilter": {
"filters": {
"items": [
{
"propertyName": "datadoc",
"comparer": 0,
"value": "2025-07-08"
},
{
"operator": 1,
"propertyName": "numdoc",
"comparer": 0,
"value": 408
}
]
}
},
"rowUnloadDocumentsFilter": {
"filters": {
"items": [
{
"propertyName": "codartMg66",
"comparer": 0,
"value": "KIT"
}
]
}
}
}
}
La response riporta l'elenco dei documenti corrispondenti al Carico prodotti Kit (numRegLoadProductKit) e l'elenco dei documenti relativi allo Scarico componenti Kit (numRegUnloadComp), in base alle righe articolo prese in esame.
{
{
"numRegLoadProductKit": [
"202500000904"
],
"numRegUnloadComp": [
"202500000905"
]
}
}
Controllo quadratura q.tà lotti
Il controllo di quadratura sulla quantità dei lotti viene effettuato, sia quando è attivo il "Controllo quadratura per documento", sia quando è attivo il "Controllo quadratura per movimentazione". Nel secondo caso, il controllo sul front-end viene eseguito dal programma di inserimento lotti per ogni riga articolo indicata nel documento.
In caso di controllo lotti non quadrato, ad esempio riga articolo di 10 pz e riga lotto con quantità di 3 pz viene segnalato un errore o un warning in base al parametro “Controllo quadratura per documento” definito nella Console parametri lotti:
-
Si avrà segnalazione di Warning se è stato selezionato il parametro = “Richiedi se continuare la registrazione del documento”
-
Si avrà segnalazione di Errore se, invece, è stato selezionato il parametro = “Blocca la registrazione del documento”
Entrambe le segnalazioni possono essere forzate aggiungendo il parametro "&force=16099" su base url.
Esempio di messaggio con dettaglio articoli squadrati e segnalazione di warning:
{
"items": [
{
"message": "Check balancing by document:\r\n Reg: 202500000578 \r\n - Item: 1_KIT_LOTTO qty1: 5 (Type mov.: LOT qty1: 0)\r\n Reg: 202500000579 \r\n - Item: 1_KIT_LOT2/42 W qty1: 10 (Type mov.: LOT qty1: 0)\r\n(Source: CMD_GENERACAR_ButtonClick)",
"warningCode": 16099,
"isWarning": true,
"isError": false,
"dtoName": null,
"dtoPropertyName": null,
"entityPropertyPath": null
}
],
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Documento di trasferimento tra depositi
Si può emettere un DDT di scarico deposito, generando automaticamente un nuovo DDT di carico a deposito.
Nel json per la parte di Testata si devono compilare le proprietà storageWH per il deposito di partenza
{
"storageWH": {
"codDep": "00"
}
}
e storageWHCollegato per il deposito di arrivo
{
"storageWHCollegato": {
"codDep": "01",
"descrdep": "Deposito secondario",
}
}
Se all’interno di un documento l’utente vuole definire un deposito di riga diverso da quello di testata, nel file json, nella sezione delle righe documento, si devono compilare coddepcolMg58 e coddepMg58 :
{
"coddepcolMg58": "01",
"coddepMg58": "00",
}
dove il primo indica il deposito di destinazione ed il secondo il deposito di partenza.
Servizi Documenti
DocumentService contiene un set di servizi di elaborazione a corredo della parte CRUD dei documenti, quali la trasformazione, l'evasione, il controllo evadibilità portafoglio ordini e l'inserimento massivo dei documenti di tipo sincrono e asincrono.
Trasformazione Documenti 1 a 1 e verifica Stato Evasione
Nell'esempio allegato viene presentato lo scenario di interazione ERP-B2C che prevede l'inserimento di un Ordine cliente con:
- Informazioni minimali obbligatorie di testata
- Riga di tipo articolo, con codice articolo e quantità (prezzo recuperato da listino nel BO)
Per quanto concerne la Trasformazione Documenti (transform), con la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/DocumentService/transform?company={{defaultCompany}}&force=24368,89522
Viene eseguita la trasformazione documento in fattura, indicando il numero registrazione di origine del documento ordine ed il relativo modello di trasformazione, nella response è riportato il numero registrazione della fattura generata.
Il servizio recupera i parametri da "DocumentTransformationParameterDTO" che contiene il modello di trasformazione, definito su ERP, e la lista del numero registrazione dei documenti di origine e restituisce in "DocumentTransformationMGDTO" la lista dei numeri di registrazione del documento generati.
DocumentTransformationParameterDTO
{
"[NumRegOrigin]" - obbligatorio (Numero di registrazione che si vuole trasformare/evadere)
"CodModelTransfDoc" - obbligatorio (Codice modello per la trasformazione documento)
}
DocumentTransformationResponseDTO
{
"<NumRegDestination>" - (Elenco dei numero di registrazione creati)
}
In caso di messaggi di warning è possibile forzarli con i seguenti parametri:
&force=24368: in presenza di segnalazione articoli bloccati; &force=29074: in presenza di segnalazione articoli e lotti trasformati sottoscorta.
Sono anche disponibili le seguenti Lookup per risalire ai modelli di trasformazione e alla loro composizione ed anche delle Lookup che interrogano oltre le entità già presenti, ModelTrasformationCompanyMG, con dettaglio ModelTrasformationCompanyDetMG, le nuove entità ModelTrasformationMG, con dettaglio ModelTrasformationDetMG, contenenti i codici documento di origine e di destinazione utilizzati dal modello di trasformazione utilizzato:
Lookup Modelli Trasformazione Generale
Visualizza tutti i modelli (archivio generale) dettagliati con i documenti di origine e destinazione
webapi_base_url/api/v1/{{scope}}/MG/Lookup/ModelTrasformationMG
- **Lookup Dettaglio Modelli Trasformazione Generale**: visualizza tutti i dettagli dei modelli (archivio generale)
webapi_base_url/api/v1/{{scope}}/MG/Lookup/ModelTrasformationDetMG
- **Lookup Modelli Trasformazione Generale**: visualizza i modelli attivati per azienda (senza dettagli)
webapi_base_url/api/v1/{{scope}}/MG/Lookup/ModelTrasformationCompanyMG
Lookup Modelli Trasformazione con Dettaglio Documenti
visualizza i modelli attivati per azienda o archivio generale con i dettagli dei documenti di origine e destinazione effettivi (viene recuperata dall'Erp la proprietà ModelTrasformationCompanyMG.IndEvasmult, se a 99 vengono utilizzati i documenti dell’archivio generale se a 1 vengono utilizzati invece i documenti dell'azienda).
webapi_base_url/api/v1/{{scope}}/MG/Lookup/ModelTrasformationCompanyDetMG
webapi_base_url/api/v1/{{scope}}/MG/Lookup/ModelTrasformationCompanyWithCodeDoc
Verifica Stato Evasione
Successivamente con la lookup Verifica Stato Evasione è possibile indicare il numero registrazione o il numero documento dell'ordine iniziale e nella response viene restituita la lista delle righe del documento indicato in input con il relativo stato evasione (q.tà documento, q.tà evase, q.tà residua) e riferimento alla/alle righe che hanno prelevato il documento.
Per quanto concerne la verifica Stato Evasione Documento (docprocessingstatus), la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/DocumentService/docprocessingstatus?company={{defaultCompany}}&user=admin&loadEntireDomain=true&getTotalCount=true
elabora il risultato in funzione di una Search tipica che, tramite una Action POST, nel cui body è possibile impostare tutte le proprietà esposte dal DTO di riferimento in maniera dinamica, restituisce una collection di entity contenente le righe del documento di riferimento con gli stati di avanzamento ed il proprio stato di evasione.
Nel query param è possibile impostare anche il criterio di paginazione con totalizzazioni, tramite la valorizzazione a True del parametro "getTotalCount".
Inoltre è disponibile un servizio di Lookup di interrogazione dello stato di evasione del singolo ordine come riportato di seguito:
webapi_base_url/api/v1/{{scope}}/MG/Lookup/DocumentoStatoEvasoMG?metadata=true&company={{defaultCompany}}&_op=search
Evadibilità Portafoglio Ordini
Il servizio di Evadibilità Portafoglio Ordini che appartiene allo scenario di spedizione esterna consente di reperire l'elenco evadibilità portafoglio ordini per la spedizione impostato nell'Erp indicando il Parametro utilizzato, in questo caso 1 e con tipo evadibilità per singolo articolo, in modalità sincrona. L'elenco degli ordini è visibile nella response.
Per recuperare l'elenco degli ordini evadibili per la spedizione effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/DocumentService/orderavailability?company={{defaultCompany}}
{
"LimiteEvadibilita": 1,
"tipoEvadibilita": 0,
"codart":"",
"IsAsyncMode": "true",
"MinExpire": "180"
}
Il parametro LimiteEvadibilita consente una pre-parametrizzazione dei filtri via ERP, che verranno considerati in fase del payload nella Post della richiesta. E' inoltre possibile definire la tipologia di evadibilità (tipoEvadibilita), il valore di default è 0.
I valori accettati dal nodo "tipoEvadibilita" in body sono:
- 0 complessiva per tutti gli articoli (default);
- 1 per articolo selezionato ;
- 2 complessiva per tutti i documenti.
Se il parametro di asincronismo (IsAsyncMode"*) della chiamata è impostato a false, l’elaborazione avverrà in modalità sequenziale con l’obbligo di attesa della risposta col resultset risultante.
Il nodo "IsAsyncMode", se impostato a ‘true’, farà si che la gestione del recupero dei valori sia di tipo asincrono, modificando il solito comportamento delle richieste; in questo caso vengono considerati tutti gli articoli e nella response viene restituito un GuidSession.
Con il "guidSession" restituito sarà possibile recuperare il risultato tramite:
- apposita Lookup impostata sulla entity:
webapi_base_url/api/v1/{{scope}}/MG/Lookup/DocumPortfolioEvaMG?metadata=true&company={{defaultCompany}}&_op=search
- oppure riutilizzando lo stesso endpoint di chiamata, ampliando il body con il nodo della "guidSession" ottenuto:
webapi_base_url/api/v1/{{scope}}/MG/DocumentService/orderavailability?company={{defaultCompany}}
{
"LimiteEvadibilita": 1,
"tipoEvadibilita": 0,
"codart":"",
"IsAsyncMode": "true",
"MinExpire": "180",
"guidSession": "{{guidSession}}"
}
Il parametro "MinExpire", consente di stabilire la durata della persistenza tra una chiamata e l’altra del risultato, espresso in termini di minuti, e verrà utilizzato per simulare una cache della griglia dei dati depositata su una tabella. Ad ogni chiamata verrà ripulita la tabella delle righe dei result precedenti che avranno espirato i termini di tempo previsti (MGM2_PORTAFOGLIOORDINI).
Per entrambe le modalità, sincrona e asincrona è possibile reperire l'elenco evadibilità portafoglio filtrando per singolo articolo e per la sua variante.
Esempio con "tipoEvadiblità":1 ossia ricerca evadibilità portafoglio ordini per articolo e con filtro per variante:
// body content
{
"LimiteEvadibilita": 1,
"tipoEvadibilita": 1,
"codart":"{{Articolo1}}",
"variante":"{{Variante}}",
"IsAsyncMode": "false",
"MinExpire": "180"
}
Nel body della chiamata è importante indicare correttamente il filtro “variante” riportando esattamente lo schema di indicazione configurato nel gestionale TSE, ossia indicare le varianti con lo stesso numero di caratteri configurate nel gestionale.
- La delete consente di eliminare il set di elaborazioni per GuidSession.
La Lookup Borderaux consente la visualizzazione di una lista righe documenti con i dati della spedizione in stile borderaux.
E' disponibile anche una Lookup che consente la visualizzazione di una lista righe documenti con i dati della spedizione in stile Borderaux, eseguendo la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/Lookup/BorderauxMG?metadata=true&company={{defaultCompany}}&_op=search
Trasformazione documenti 1 a n (Evasione DDT e Generazione fatture)
A fronte di un documento di partenza si possono generare automaticamente più documenti di destinazione (Trasformazione documenti 1 a n), tramite la configurazione della Rottura di riga sul modello di trasformazione documenti utilizzato. Gli elementi di rottura di riga sono quelli gestiti nell'Erp :
- Pagamento articolo
- Causale di magazzino
- Deposito
- Deposito collegato
- Sede
- Divisione
- Indicatore merce articolo 62
- CIG/CUP
A fronte di un DDT è possibile generare n Fatture, tramite la Trasformazione Documenti, se il modello di Trasformazione Documenti prevede la rottura di riga in base ad un elemento definito. Simulando la chiamata di una trasformazione documenti per rottura di riga per deposito, la response restituisce n numRegDestination per ogni deposito di riga presente nel documento di origine, per il quale appunto sul documento di origine (DDT) si valorizza il coddepMg58 ossia il deposito di riga differente per ogni riga articolo. Sul modello di Trasformazione scelto nella chiamata, si definisce da Interfaccia la Rottura di riga per deposito. A questo punto viene eseguita la chiamata per effettuare la trasformazione documento, indicando il numero registrazione di origine del documento (DDT) e lo specifico modello di trasformazione (che gestisce la rottura di riga per deposito) per generare le n fatture corrispondenti. Nella response saranno restituiti n numero registrazioni di destinazione relativi alle fatture generate e quindi per ogni deposito di riga gestito sul documento di origine.
// body content
{
"numRegDestination": [
"202400000494",
"202400000495"
]
}
Trasformazione Documenti n a n
A fronte dell'inserimento di un ordine fornitore con:
- informazioni minimali obbligatorie di testata
- due righe di tipo articolo, con codice articolo diverso e quantità Viene poi eseguita la chiamata per effettuare la Trasformazione documenti in DDT, indicando il numero registrazione di origine ed il relativo modello di trasformazione, mentre nella response è recuperato il numero registrazione del DDT generato.
Sono resi disponibili alcuni casi d'uso, a titolo di esempio, riportando il relativo body della chiamata:
Evasione totale di un documento, con il riporto del numero documento di origine sul documento di destinazione
Per procedere con il riporto corretto del documento di origine sul documento di destinazione da generare, è necessario compilare il parametro DocumentTransformationProcessExtremLimitDTO ed impostare AcceptDocMode = 1.
{
"numRegOrigin": ["202400000288"],
"codModelTransfDoc": "{{TrasformazioneORD-DDT}}",
"processExtremLimits": {
"acceptDocMode": 1,
"destinationDocParams": {
"dataReg": "2024-10-14",
"dataDoc": "2024-10-14",
"dataCompVatMan": "2024-10-14",
"sezdoc": "00",
"numDoc": 101.0,
"numDocOrig": 19.0
}
}
}
In contemporanea alla trasformazione documenti, è anche possibile procedere con l'applicazione di uno o più filtri, definiti in SearchDTO.
Evasione parziale di una o più righe documento, specificando solo il progrRiga del documento di origine
Se si desidera effettuare l'evasione parziale di una o più righe documento, è necessario specificare anche i parametri aggiuntivi in DocumentTransformationPartialEvadContainerGeneralDataDTO per ogni numRegOrigin della request.
Nota Bene:
- numRegOrigin - obbligatorio (Numero di registrazione che si desidera trasformare)
- progrRiga - obbligatorio (Progressivo riga corrispondente alla riga documento che si desidera trasformare)
- qtaTransf - obbligatorio (La quantità da riportare sul documento di destinazione)
{
"numRegOrigin": ["202400002619"],
"codModelTransfDoc": "1-FOR-ORDDDT",
"processExtremLimits": {
"acceptDocMode": 1,
"destinationDocParams": {
"dataReg": "2024-10-01T09:29:27.355Z",
"dataDoc": "2024-10-01T09:29:27.355Z",
"dataCompVatMan": "2024-10-01T09:29:27.355Z",
"sezdoc": "00",
"numDoc": 42,
"numDocOrig": 44
}
},
"documentTransformationPartialEvadContainerGeneralData": [
{
"numRegOrigin": "202400002619",
"documentTransformationGeneralData": [
{
"progrRiga": 1,
"qtaTransf": 2
},
{
"progrRiga": 2,
"qtaTransf": 4
}
]
}
]
}
Evasione parziale di n documenti di origine, applicando anche un'eventuale variazione di prezzo e sconti a percentuale
Nel caso in cui si desidera evadere l'ordine con un'eventuale variazione di prezzo o di sconto o di maggiorazione rispetto al documento di origine, si devono compilare gli opportuni parametri corrispondenti. Se si desidera mantenere le condizioni commerciali del documento di origine, i suddetti parametri non devono essere indicati nella request.
{
"numRegOrigin": [
"202400002730",
"202400002731"
],
"codModelTransfDoc": "1-FOR-ORDDDT",
"processExtremLimits": {
"acceptDocMode": 1,
"destinationDocParams": {
"dataReg": "2024-10-14T09:29:27.355Z",
"dataDoc": "2024-10-14T09:29:27.355Z",
"dataCompVatMan": "2024-10-14T09:29:27.355Z",
"sezdoc": "00",
"numDoc": 104,
"numDocOrig": 96
}
},
"documentTransformationPartialEvadContainerGeneralData": [
{
"numRegOrigin": "202400002730",
"documentTransformationGeneralData": [
{
"progrRiga": 1,
"qtaTransf": 5,
"price1": 300,
"scper1": 2
},
{
"progrRiga": 2,
"qtaTransf": 3,
"price1": 100,
"scper1": 2.5
}
]
},
{
"numRegOrigin": "202400002731",
"documentTransformationGeneralData": [
{
"progrRiga": 1,
"qtaTransf": 2
},
{
"progrRiga": 2,
"qtaTransf": 4
}
]
}
]
}
Evasione totale di n documenti, applicando un filtro per codice articolo
{
"numRegOrigin": [
"202400002401",
"202400002402"
],
"codModelTransfDoc": "1-FOR-ORDDDT",
"processExtremLimits": {
"acceptDocMode": 1,
"destinationDocParams": {
"dataReg": "2024-10-04",
"dataDoc": "2024-10-04",
"dataCompVatMan": "2024-10-04",
"sezdoc": "00",
"numDoc": 102.0,
"numDocOrig": 76.0
}
},
"rowSearchTransformationCriteria": {
"filters": {
"items": [
{
"operator": 0,
"comparer": 0,
"propertyName": "CodartMg66",
"value": "{{Articolo1}}"
}
]
}
}
}
Evasione parziale di un documento, evadendo parzialmente la prima riga e dichiarando la seconda riga come "Non più evadibile" per il residuo
Se in fase di evasione parziale di un documento, si desidera dichiarare una riga documento come Non più evadibile, si deve impostare il parametro rowNotEvad a "true" per il progrRiga corrispondente.
{
"numRegOrigin": [
"202400002889"
],
"codModelTransfDoc": "1-FOR-ORDDDT",
"documentTransformationPartialEvadContainerGeneralData": [
{
"numRegOrigin": "202400002889",
"documentTransformationGeneralData": [
{
"progrRiga": 1,
"indtiporiga": 0,
"qtaTransf": 3.0
},
{
"indtiporiga": 0,
"progrRiga": 2,
"qtaTransf": 4.0,
"rowNotEvad": true
}
]
}
]
}
Inserimento massivo documenti
Nell'esempio allegato viene presentato lo scenario di un verticale integrato per la gestione del magazzino che consente l'inserimento massivo di più documenti, ad esempio n. 3 documenti di tipo fattura immediata, composti da:
- n. 8 righe di tipo articolo
- n. 1 riga con articolo di tipo KIT
- n. 1 riga con articolo manuale
La response della chiamata di inserimento massivo documenti rilascerà un GuidSession che può essere interrogato mediante Lookup.
Esistono due tipi di Lookup:
- Dettaglio Analitico: Restituisce una lista con dettaglio analitico relativo allo stato di avanzamento della elaborazione dell'inserimento massivo documenti.
- Lista Strutturata: Restituisce una lista strutturata per verificare lo stato di avanzamento della elaborazione massiva dell'inserimento documenti.
L'operazione di delete consente di eliminare il set di elaborazioni per GuidSession.
Nell'ipotesi in cui, a seguito di Inserimento Massivo Documenti, alcuni di questi siano in stato di errore, è possibile, dopo aver individuato e corretto l'errore sul documento, utilizzare il servizio di riprocessamento. Questo servizio consente di procedere all'inserimento dei documenti corretti che erano andati in errore.
Con il rilascio della versione 202502000 versione di rilascio è possibile ultilizzare un codice articolo cliente o un codice articolo fornitore anche nel servizio di inserimento massivo. Basta semplicemnte riportare nel Body della chiamata POST l'entità codartcli in luogo di codartMg66 come qui di seguito riportato:
{
"righe": [
{
"progrRiga": 1.0,
"codartcli": "ARTCLI124500",
"qta1": 1.000
}
]
}
Servizi di Import/Export
Acquisizione listini dall'esterno: Servizio IEImportLI
Il servizio IEImportLI permette di importare i listini messi a disposizione da terze parti e in formati diversi (formati supportati excel/csv), per cui tramite questo servizio è possibile importare un listino articolo per un fornitore specifico da un file esterno in modalità sincrona o asincrona, utilizzando uno specifico tracciato di import.
Per eseguire l'importazione listino da file esterno, si deve effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/LI/IEImportLI/pricelist?company={{defaultCompany}}
Il servizio recupera i parametri da ImportParameterDTO e restituisce nella response in ImportExportResultDTO il numero delle righe importate correttamente ed il numero di righe non importate con relativa segnalazione di errore .
ImportParameterDTO
CodLayout - obbligatorio (Codice tracciato che si vuole utilizzare per eseguire l’import) TypeSalePurchase - obbligatorio (Tipo di listino 0=Vendita 1=Acquisto) StreamFileImport – obbligatorio (File da importare in formato Base64)
ImportExportResultDTO
guidSessione - guid dell'elaborazione stateProcess - stato dell'elaborazione idStateProcess - id corrispondente allo stato dell'elaborazione headProcess: guidResult - guid del risultato dell’importazione totRowImpExp- numero totale delle righe da importare impExpWithErrors rowElab - righe oggetto dell’importazione typeResult - id corrispondente al risultato dell'importazione typeResultDescription - information description - descrizione delle note di importazione e di eventuali errori
Inoltre sono disponibili le chiamate su entità di base, necessarie per effettuare l'importazione listini fornitore: LayoutCO con dettaglio IELayoutCODTO per recuperare il codice tracciato da utilizzare, StructureType con dettaglio IEStructureTypeCODTO e StructureSubType con dettaglio IEStructureSubTypeCODTO che corrispondono al Tipo struttura e Sottotipo struttura legati al tracciato in uso.
webapi_base_url/api/v1/{{scope}}/CO/IEStructureTypeCO/{{CodStructureType}}?company={{defaultCompany}}
webapi_base_url/api/v1/{{scope}}/CO/IEStructureSubTypeCO/{{CodStructureSubType}}?company={{defaultCompany}}
webapi_base_url/api/v1/{{scope}}/CO/IELayoutCO/{{CodLayout}}?company={{defaultCompany}}&CodStructureType={{CodStructureType}}
Il servizio accetta solo i tracciati che hanno CodStructureType = 18 (Listino articoli) e CodStructureSubType = 4 (Listino clienti/fornitori).
Esempio
L'esempio riportato importa un listino fornitore da file esterno convertito in Base64 (indicato in "StreamFileImport"), in base al tracciato definito precedentemente su ERP ed impostando i parametri obbligatori.
{
"TypeSalePurchase" : "1",
"CodLayout": "{{CodLayout}}",
"StreamFileImport":
}
Durante l'importazione del listino fornitore, è anche possibile contemporaneamente:
- creare nuovi articoli (presenti nel file e non presenti su ERP), impostando il parametro "insertNewItem": true, (il default è a false);
- aggiornare articoli già esistenti, impostando il parametro "updateInsertPriceList": true (il default è a false);
- forzare il periodo di validità del listino rispetto a quello definito nel file, tramite i parametri "forceBeginDate" e "forceEndDate"
- aggiornare un listino a parità di periodo di validità, definendo il parametro "updatePriceList" : true;
- forzare unità di misura oppure il codice valuta oppure il codice cliente, rispetto al file esterno.
Tale funzionalità è gestibile definendo nel body della chiamata anche l'elemento parametro addParameters:
{
"addParameters": {
"forceTypeInUseOrToExpect": "0",
"insertNewItem": false,
"updateExistingItem": false,
"forceBeginDate": "1900-01-01T08:18:28.461Z",
"forceEndDate": "2099-12-31T08:18:28.461Z",
"dateUpdate": "2024-08-07T08:18:28.461Z",
"updateInsertPriceList": true,
"updatePriceList": false,
"forceTypeUnitOfMeasure": "1",
"forceCodCurrency": null,
"forceCodCustomerSupplier": null
},
"isAsyncMode": false,
"TypeSalePurchase" : "1",
"CodLayout": "{{CodLayout}}",
"StreamFileImport":
}
Al termine dell'importazione, la response visualizza in ImportExportResultDTO il risultato dell'elaborazione, il numero delle righe importate e le segnalazioni di eventuali errori.
L'import listino fornitore può essere eseguito anche in modalità asincrona, impostando tra i parametri obbligatori il parametro "isAsyncMode" a true.
{
"TypeSalePurchase" : "1",
"isAsyncMode": true,
"CodLayout": "{{CodLayout}}",
"StreamFileImport":
}
In questo caso la response visualizza la guidSession:
{
"guidSession": "2718c758-7ec2-46a3-8f2a-57faaa0a5ac9",
"stateProcess": "Inserted",
"idStateProcess": 0,
"headProcess": null
}
A questo punto per recuperare il risultato dell'elaborazione in ImportExportResultDTO è necessario utilizzare il servizio IEServiceCO eseguendo una chiamata di tipo GET :
webapi_base_url/api/v1/{{scope}}/CO/IEServiceCO/{{guidSession}}?company={{defaultCompany}}
{
"guidSession": "2718c758-7ec2-46a3-8f2a-57faaa0a5ac9",
"stateProcess": "Terminate",
"idStateProcess": 2,
"headProcess": {
"guidResult": "4E175429D751488D985891CCCAFA92D8",
"totRowImpExp": 7,
"impExpWithErrors": false,
"rowElab": [
{
"typeResult": 1,
"typeResultDescription": "Information",
"description": "Importazione terminata.\r\nNumero di righe importate correttamente: 7 \r\nNumero di righe non importate: 0"
}
]
}
}
Esportazione e Importazione clienti o fornitori dall'esterno: Servizio IEImportCO e IEExportCO
Il servizio IEExportCO permette di esportare i clienti o i fornitori da TSE, generando uno streamfile, mentre il servizio IEImportCO consente di importare i clienti o i fornitori tramite file messo a disposizione da terze parti. I formati supportati del file sono excel e csv. L'esportazione dei clienti e/o fornitori genera uno streamfile che può essere convertito in un file csv o excel. Tramite i suddetti servizi è possibile esportare uno o più clienti e/o fornitorì oppure importarli da file, previa creazione di uno specifico tracciato definito su ERP e tramite specifici parametri, è possibile creare automaticamente le relative anagrafiche oppure aggiornarle se già esistenti.
Il servizio può essere eseguito sia in modalità sincrona sia asincrona, tramite il parametro "isAsyncMode".
Importazione clienti/fornitori
Per eseguire l'importazione clienti/fornitori da file esterno, si deve effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/CO/IEImportCO/customersupplier?company={{defaultCompany}}
Il servizio recupera i parametri da ImportParameterDTO e restituisce nella response in ImportExportResultDTO il numero delle righe importate correttamente ed il numero di righe non importate con relativa segnalazione di errore .
ImportParameterDTO
isAsyncMode - obbligatorio (modalità di importazione - sincrona (true) o asincrona (false)) CodLayout - obbligatorio (Codice tracciato che si vuole utilizzare per eseguire l’import) StreamFileImport – obbligatorio (File da importare in formato Base64)
ImportExportResultDTO
guidSessione - guid dell'elaborazione stateProcess - stato dell'elaborazione idStateProcess - id corrispondente allo stato dell'elaborazione headProcess: guidResult - guid del risultato dell’importazione totRowImpExp- numero totale delle righe da importare impExpWithErrors rowElab - righe oggetto dell’importazione typeResult - id corrispondente al risultato dell'importazione typeResultDescription - information description - descrizione delle note di importazione e di eventuali errori
Il servizio accetta solo i tracciati che hanno CodStructureType = 2 (Anagrafiche ClientiFornitori) e CodStructureSubType = 0. Il file, oggetto dell'importazione, deve essere convertito in formato Base64 per poter essere importato, tramite il servizio.
Durante l'importazione dei clienti e/o fornitori, è anche possibile contemporaneamente:
- creare nuovi clienti e/o fornitori (presenti nel file e non presenti su ERP), impostando il parametro "insertCustomerSupplier": true, (il default è a false);
- aggiornare clienti e/o fornitori già esistenti, impostando il parametro "updateExistingCustomerSupplier": true (il default è a false);
- definire la modalità di importazione (come da ERP), tramite il parametro "typeImportModeCustomerSupplier" (il default è 0 che corrisponde "Tutte le anagrafiche")
Tale funzionalità è gestibile definendo nel body della chiamata anche l'elemento parametro addParameters:
{
"addParameters": {
"typeImportModeCustomerSupplier": "0",
"insertCustomerSupplier": true,
"updateExistingCustomerSupplier": true
},
"isAsyncMode": false,
"CodLayout": "{{CodLayout}",
"StreamFileImport": " "
}
Al termine dell'importazione, la response visualizza in ImportExportResultDTO il risultato dell'elaborazione, il numero delle righe importate e le segnalazioni di eventuali errori.
L'import clienti/fornitori può essere eseguito anche in modalità asincrona, impostando tra i parametri obbligatori il parametro "isAsyncMode: true.
{
"isAsyncMode": true,
"CodLayout": "{{CodLayout}}",
"StreamFileImport":
}
In questo caso la response visualizza la guidSession:
{
"guidSession": "2718c758-7ec2-46a3-8f2a-57faaa0a5ac9",
"stateProcess": "Inserted",
"idStateProcess": 0,
"headProcess": null
}
Per recuperare il risultato dell'elaborazione in ImportExportResultDTO è necessario utilizzare il servizio IEServiceCO eseguendo una chiamata di tipo GET ed indicando la guidSession della response precedente:
webapi_base_url/api/v1/{{scope}}/CO/IEServiceCO/{{guidSession}}?company={{defaultCompany}}
{
"guidSession": "2718c758-7ec2-46a3-8f2a-57faaa0a5ac9",
"stateProcess": "Terminate",
"idStateProcess": 2,
"headProcess": {
"guidResult": "4E175429D751488D985891CCCAFA92D8",
"totRowImpExp": 7,
"impExpWithErrors": false,
"rowElab": [
{
"typeResult": 1,
"typeResultDescription": "Information",
"description": "Importazione terminata.\r\nNumero di righe importate correttamente: 7 \r\nNumero di righe non importate: 0"
}
]
}
}
Esportazione clienti/fornitori
Per eseguire l'esportazione clienti/fornitori, generando uno Streamfile, si deve effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/CO/IEExportCO/customersupplier?company={{defaultCompany}}
Nella body della request deve essere indicato il codice tracciato da utilizzare (precedentemente creato da interfaccia), si deve definire se si effettua l'esportazione in modalità sincrona o asincrona ed è anche possibile definire eventuali parametri aggiuntivi, così come previsto da Interfaccia.
{
"addParameters": {
"selectionValidityGeneralMasterData": "0",
"referenceValidDate": "2024-11-11T08:18:28.461Z"
},
"isAsyncMode": false,
"CodLayout": "{{CodLayout}}"
}
Con il parametro "selectionValidityGeneralMasterData" è possibile scegliere di esportare tutte le anagrafiche valide oppure solo quelle valide alla data di sistema oppure solo quelle valide da una data precisa che viene definita nel parametro successivo "referenceValidDate".
Nella body della response sono riportati eventuali messaggi di errore ed è generato lo streamfile in formato a 64bit, che dovrà essere convertito a cura dell'utente.
Uso dei filtri Come da interfaccia, è possibile anche applicare dei filtri di estrazione, tramite la funzione Search. Nell'esempio sotto riportato, si esportano tutte le anagrafiche valide e si utilizza come criterio di estrazione il 'tipocf' quindi si esportano tutte le anagrafiche di tipo fornitori.
{
"addParameters": {
"selectionValidityGeneralMasterData": "1"
},
"isAsyncMode": false,
"CodLayout": "{{CodLayoutClifor}}",
"searchFilter": {
"filters": {
"operator": 0,
"items": [
{
"operator": 0,
"comparer": 0,
"propertyName": "tipocf",
"value": "1"
}
]
}
}
}
NOTA BENE: Se l'utente desidera estrarre i dati secondo un criterio che non è gestito dalla Search, si ricorda che si può definire il criterio aggiuntivo nel tracciato in uso, tramite le 'Condizioni di import' in caso di importazione o le 'Condizioni di export' in caso di esportazione, si sceglie la Modalità Avanzata e si specifica il criterio, tramite istruzione SQL.
Ad esempio, se si desidera esportare solo i clienti che appartengono al codice Area ITA e al codice Zona NOR, l'istruzione SQL è:
[Codice_area] = 'ITA' AND [Codice_zona] = 'NOR'
In questo caso il tracciato deve prevedere tra i campi esportabili il codice area ed il codice zona.
Esportazione e Importazione anagrafica articoli dall'esterno: Servizio IEImportWH e IEExportWH
Il servizio IEExportWH permette di esportare le anagrafiche articoli da TSE, generando uno streamfile, mentre il servizio IEImportWH consente di importare le anagrafiche articoli tramite file messo a disposizione da terze parti. I formati supportati del file sono excel e csv. L'esportazione delle anagrafiche articoli genera uno streamfile che può essere convertito in un file csv o excel. Tramite i suddetti servizi è possibile esportare uno o più articoli oppure importarli da file, previa creazione di uno specifico tracciato definito su ERP e tramite specifici parametri, è possibile creare automaticamente le relative anagrafiche articoli oppure aggiornarle se già esistenti.
Il servizio può essere eseguito sia in modalità sincrona sia asincrona, tramite il parametro "isAsyncMode".
Importazione anagrafiche articoli
Per eseguire l'importazione delle anagrafiche articoli da file esterno, si deve effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/WH/IEImportWH/item?company={{defaultCompany}}
Il servizio recupera i parametri da ImportParameterDTO e restituisce nella response in ImportExportResultDTO il numero delle righe importate correttamente ed il numero di righe non importate con relativa segnalazione di errore .
ImportParameterDTO
isAsyncMode - obbligatorio (modalità di importazione - sincrona (true) o asincrona (false)) CodLayout - obbligatorio (Codice tracciato che si vuole utilizzare per eseguire l’import) StreamFileImport – obbligatorio (File da importare in formato Base64)
ImportExportResultDTO
guidSessione - guid dell'elaborazione stateProcess - stato dell'elaborazione idStateProcess - id corrispondente allo stato dell'elaborazione headProcess: guidResult - guid del risultato dell’importazione totRowImpExp- numero totale delle righe da importare impExpWithErrors rowElab - righe oggetto dell’importazione typeResult - id corrispondente al risultato dell'importazione typeResultDescription - information description - descrizione delle note di importazione e di eventuali errori
Il servizio accetta solo i tracciati che hanno CodStructureType = 1 (Anagrafiche Articoli) e CodStructureSubType = 0. Il file, oggetto dell'importazione, deve essere convertito in formato Base64 per poter essere importato, tramite il servizio.
Durante l'importazione delle anagrafiche articoli, è anche possibile contemporaneamente:
- creare nuove anagrafiche articoli (presenti nel file e non presenti su ERP), impostando il parametro "insertNewItem": true, (il default è a false);
- aggiornare anagrafiche articoli già esistenti, impostando il parametro "updateExistingItem": true (il default è a false);
- creare nuovi prezzi di listino collegati alle anagrafiche articoli importate (come da ERP), tramite il parametro "insertNewPriceList" (il default è a false);
- definire la data inizio validità e la data fine validità (se non definite, per la data inizio validità è considerata la data di sistema, mentre per la data fine validità è considerata la data 31-12-2099)
Tale funzionalità è gestibile definendo nel body della chiamata anche l'elemento parametro addParameters:
{
"addParameters": {
"insertNewItem": true,
"updateExistingItem": true,
"insertNewPriceList": true,
"beginDatePriceList": "2025-01-01T13:39:23.654Z",
"endDatePriceList": "2025-01-31T13:39:23.654Z"
},
"isAsyncMode": false,
"CodLayout": "{{CodLayout}",
"StreamFileImport": " "
}
Al termine dell'importazione, la response visualizza in ImportExportResultDTO il risultato dell'elaborazione, il numero delle righe importate e le segnalazioni di eventuali errori.
L'import anagrafiche articoli può essere eseguito anche in modalità asincrona, impostando tra i parametri obbligatori il parametro "isAsyncMode: true.
{
"isAsyncMode": true,
"CodLayout": "{{CodLayout}}",
"StreamFileImport":
}
In questo caso la response visualizza la guidSession:
{
"guidSession": "1949fcab-3030-43a6-b363-dab3af2f91cf",
"stateProcess": "Inserted",
"idStateProcess": 0,
"headProcess": null,
"streamFileExport": null
}
Per recuperare il risultato dell'elaborazione in ImportExportResultDTO è necessario utilizzare il servizio IEServiceCO eseguendo una chiamata di tipo GET ed indicando la guidSession della response precedente:
webapi_base_url/api/v1/{{scope}}/CO/IEServiceCO/{{guidSession}}?company={{defaultCompany}}
{
"guidSession": "1949fcab-3030-43a6-b363-dab3af2f91cf",
"stateProcess": "Terminate",
"idStateProcess": 2,
"headProcess": {
"guidResult": "FC114860E4234F68A37F56C130504E64",
"totRowImpExp": 3,
"impExpWithErrors": false,
"rowElab": [
{
"typeResult": 1,
"typeResultDescription": "Information",
"description": "Importazione terminata.\r\nNumero di righe importate correttamente: 3 \r\nNumero di righe non importate: 0",
"isDone": false,
"isImportance": true,
"isError": false,
"isWarning": false,
"isInformation": true,
"isCreate": false,
"isUpdate": false,
"isDelete": false
}
]
},
}
Esportazione anagrafiche articoli
Per eseguire l'esportazione anagrafiche articoli, generando uno Streamfile, si deve effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/WH/IEExportWH/item?company={{defaultCompany}}
Nel body della request deve essere indicato il codice tracciato da utilizzare (precedentemente creato da Interfaccia) e si deve definire se si effettua l'esportazione in modalità sincrona o asincrona. E' anche possibile definire eventuali parametri aggiuntivi, così come previsto da Interfaccia.
{
"addParameters": {
"selectItemsToExtracted": "0",
"updateExtractedItem": false,
"priceListReferenceDate": "2025-03-14T09:03:36.101Z",
"storageWHCode": "00",
"extractGeneratedVariants": false
},
"isAsyncMode": false,
"CodLayout": "{{CodLayout}}"
}
Con il parametro "selectItemsToExtracted" (che corrisponde al parametro "Articoli da estrarre" presente in Interfaccia) è possibile scegliere se esportare Tutti gli articoli (= valore 0 che corrisponde al default) oppure solo quelle variate a livello di dati anagrafici (= valore 1) oppure solo quelle che hanno subito variazioni sui listini (= valore 2) oppure tutte le anagrafiche articoli che hanno subito una qualunque variazione (= valore 3).
Il parametro "priceListReferenceDate" è la data riferimento listino, mentre il parametro "storageWHCode" corrisponde al deposito scorte, ove sono presenti le anagrafiche articoli che si desidera esportare.
Con il parametro "extractGeneratedVariants" valorizzato a true, è possibile esportare anche le opzioni varianti per le anagrafiche articoli che gestiscono le varianti.
Con il parametro "updateExtractedItem", nel momento in cui si effettua l'esportazione delle anagrafiche articoli, se il suddetto parametro è valorizzato a "true", si aggiorna il flag di variazione per ogni codice articolo esportato. Un esempio pratico: si effettua l'esportazione di Tutti gli articoli, si imposta il suddetto parametro a "true", si eseguono alcune variazioni sui dati anagrafici o sui listini di alcuni articoli, se a questo punto si effettua una nuova esportazione dati, valorizzando "selectItemsToExtracted=3", il servizio esporterà solo le anagrafiche articoli variate, rispetto alla prima esportazione fatta in precedenza.
Nella body della response sono riportati eventuali messaggi di errore ed è generato lo streamfile in formato a 64bit, che dovrà essere convertito a cura dell'utente.
Uso dei filtri Come da interfaccia, è possibile anche applicare dei filtri di estrazione, tramite la funzione Search. Nell'esempio sotto riportato, si esportano tutte le anagrafiche articoli e si utilizza come criterio di estrazione la propertyName 'um1' con valore "PZ" quindi si esportano tutte le anagrafiche articoli che hanno unità di misura principale PZ.
{
"addParameters": {
"selectItemsToExtracted": "0",
"updateExtractedItem": false,
"priceListReferenceDate": "2024-01-01T09:03:36.101Z",
"storageWHCode": "00",
"extractGeneratedVariants": false
},
"isAsyncMode": false,
"codLayout": "{{CodLayout}}",
"SearchFilter": {
"filters": {
"operator": 0,
"items": [
{
"operator": 0,
"propertyName": "um1",
"comparer": 0,
"value": "PZ"
}
]
}
}
}
NOTA BENE: Se l'utente desidera estrarre i dati secondo un criterio che non è gestito dalla Search, si ricorda che si può definire il criterio aggiuntivo nel tracciato in uso, tramite le 'Condizioni di import' in caso di importazione o le 'Condizioni di export' in caso di esportazione, in questo caso si sceglie la Modalità Avanzata e si specifica il criterio, tramite istruzione SQL.
In questo caso il tracciato deve prevedere tra i campi esportabili il codice utilizzato come criterio.
Esportazione e Importazione Documenti dall'esterno: Servizio IEImportMG e IEExportMG
Il servizio IEExportMG permette di esportare i documenti da TSE, generando uno streamfile, mentre il servizio IEImportMG consente di importare i documenti tramite file messo a disposizione da terze parti. I formati supportati del file sono excel e csv.
Il servizio IEExportMG genera uno streamfile (in formato 64bit) che può essere convertito in un file csv o excel. Tramite questo servizio è possibile esportare tutti i documenti oppure solo quelli "da estrarre" (non ancora estratti) oppure uno o più documenti specifici, applicando i filtri di ricerca.
Il servizio IEImportMG invece permette di importare n documenti presenti su file esterno, con un codice documento specifico oppure con un codice documento diverso da quello presente sul file e tramite l'uso di parametri aggiuntivi, creare\aggiornare i clienti/fornitori oppure le anagrafiche articoli ed alcune tabelle ad esse collegate.
Per utilizzare i suddetti servizi, è necessario creare un determinato tracciato, definito su ERP. Entrambi i servizi accettano solo i tracciati che hanno CodStructureType = 4 (Documenti, articoli, cli/for) e CodStructureSubType = 0.
Entrambi i servizi, possono essere eseguiti sia in modalità sincrona sia asincrona, tramite il parametro "isAsyncMode".
Importazione Documenti
Per eseguire l'importazione documenti da file esterno, si deve effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/IEImportMG/document?company={{defaultCompany}}
Il servizio recupera i parametri da ImportParameterDTO e restituisce nella response in ImportExportResultDTO il numero delle righe importate correttamente ed il numero di righe non importate con relativa segnalazione di errore .
ImportParameterDTO
isAsyncMode - obbligatorio (modalità di importazione - sincrona (true) o asincrona (false)) CodLayout - obbligatorio (Codice tracciato che si vuole utilizzare per eseguire l’import) StreamFileImport – obbligatorio (File da importare in formato Base64)
ImportExportResultDTO
guidSessione - guid dell'elaborazione stateProcess - stato dell'elaborazione idStateProcess - id corrispondente allo stato dell'elaborazione headProcess: guidResult - guid del risultato dell’importazione totRowImpExp- numero totale delle righe da importare impExpWithErrors rowElab - righe oggetto dell’importazione typeResult - id corrispondente al risultato dell'importazione typeResultDescription - information description - descrizione delle note di importazione e di eventuali errori
Il file, oggetto dell'importazione, deve essere convertito in formato Base64 per poterlo importare.
Durante l'importazione dei documenti, è anche possibile contemporaneamente:
- definire un codice documento specifico da utilizzare per l'import, tramite il parametro "documentCode" quindi tutti i documenti presenti nel file esterno, saranno importati con il codice documento definito nel body (e ovviamente attivo per l'azienda di lavoro) ;
- specificare quale azione intraprendere se il documento (che si sta importando) esiste già su ERP, tramite il parametro "selectionActionDocumentExist" (il default è 4 - Inserisci con stesso numero);
- creare nuovi clienti o fornitori, a seconda del tipo documento che si sta importando (presenti nel file e non presenti su ERP), tramite il parametro "insertNewCustomerSupplier" (il default è a true);
- aggiornare anagrafiche clienti o fornitori già esistenti, tramite il parametro "updateExistingCustomerSupplier" (il default è a false);
- creare nuove anagrafiche articoli (presenti nel file e non presenti su ERP), impostando il parametro "insertNewItem": true, (il default è a true);
- aggiornare anagrafiche articoli già esistenti, impostando il parametro "updateExistingItem": true (il default è a false);
- inserire nuovi dati per alcune tabelle collegate ai clienti/fornitori oppure alle anagrafiche articoli, se non presenti in ERP, tramite il parametro "insertDataForNotExistingTables" (il default è a true);
Per i clienti/fornitori: Banche e Agenzie, Agenti, Condizioni di pagamento, Vettori, Destinatario merce. Per le anagrafiche articoli: Famiglie, Sottofamiglie, Gruppi, Sottogruppi.
Tali funzionalità sono gestibili definendo nel body della chiamata anche l'elemento parametro addParameters:
{
"addParameters": {
"documentCode": "CLI-FATIMM",
"selectionActionDocumentExist": "4",
"insertNewCustomerSupplier": true,
"updateExistingCustomerSupplier": false,
"insertNewItem": true,
"updateExistingItem": false,
"insertDataForNotExistingTables": true
},
"isAsyncMode": false,
"CodLayout": "{{CodLayout}",
"StreamFileImport": " "
}
Al termine dell'importazione, la response visualizza in ImportExportResultDTO il risultato dell'elaborazione, il numero delle righe importate e le segnalazioni di eventuali errori.
Per una corretta importazione documenti da file CSV, il tracciato record utilizzato può essere formato da una sola riga di Tipo Riga "Testata e corpo gruppo dati" oppure può contenere due righe, di cui una riga con Tipo Riga "Testata gruppo dati", dove definire tutti i campi di Testata documento ed una seconda con Tipo Riga "Corpo" dove indicare tutti i campi di Riga documento che si intendono gestire. In entrambi i casi, per il Tipo Riga "Testata gruppo dati" si deve anche definire un campo FILLER con Trascodifica=Fissa e Valore=T per identificare che si tratta di "TestataDocumento" e per il Tipo Riga "Corpo" si deve definire anche un campo FILLER con Trascodifica=Fissa e Valore=R per identificare che si tratta di "RigaDocumento". Si ricorda che, per una corretta importazione dati, è anche necessario definire in modo appropriato le Condizioni di Import ossia nel prospetto "Modalità Base" specificare le corrispondenti posizioni dei suddetti campi FILLER.
Per una corretta importazione documenti da file EXCEL, il tracciato record utilizzato può essere formato da una sola riga di Tipo Riga "Testata e corpo gruppo dati" e come già indicato precedentemente, si devono definire un campo FILLER per la Testata documento ed un campo FILLER per la Riga documento. In questo caso per una corretta importazione dati, si ricorda che è necessario definire le Condizioni di import nel prospetto "Modalità avanzata" la seguente istruzione SQL:
(PRECEDENTE [Numero_documento] <> [Numero_documento] )
L'import documenti può essere eseguito anche in modalità asincrona, impostando tra i parametri obbligatori il parametro "isAsyncMode: true".
{
"isAsyncMode": true,
"CodLayout": "{{CodLayout}}",
"StreamFileImport":
}
In questo caso la response visualizza la guidSession:
{
"guidSession": "1949fcab-3030-43a6-b363-dab3af2f91cf",
"stateProcess": "Inserted",
"idStateProcess": 0,
"headProcess": null,
"streamFileExport": null
}
Per recuperare il risultato dell'elaborazione in ImportExportResultDTO è necessario utilizzare il servizio IEServiceCO eseguendo una chiamata di tipo GET ed indicando la guidSession della response precedente:
webapi_base_url/api/v1/{{scope}}/CO/IEServiceCO/{{guidSession}}?company={{defaultCompany}}
{
"guidSession": "1949fcab-3030-43a6-b363-dab3af2f91cf",
"stateProcess": "Terminate",
"idStateProcess": 2,
"headProcess": {
"guidResult": "FC114860E4234F68A37F56C130504E64",
"totRowImpExp": 3,
"impExpWithErrors": false,
"rowElab": [
{
"typeResult": 1,
"typeResultDescription": "Information",
"description": "Importazione terminata.\r\nNumero di righe importate correttamente: 3 \r\nNumero di righe non importate: 0",
"isDone": false,
"isImportance": true,
"isError": false,
"isWarning": false,
"isInformation": true,
"isCreate": false,
"isUpdate": false,
"isDelete": false
}
]
},
}
Esportazione Documenti
Per eseguire l'esportazione documenti, generando uno Streamfile, si deve effettuare la seguente chiamata:
webapi_base_url/api/v1/{{scope}}/MG/IEExportMG/document?company={{defaultCompany}}
Nel body della request deve essere indicato il codice tracciato da utilizzare (precedentemente creato da Interfaccia) e si deve definire se si effettua l'esportazione in modalità sincrona o asincrona. E' anche possibile definire eventuali parametri aggiuntivi, così come previsto da Interfaccia.
{
"addParameters": {
"selectDocToExtracted": "0",
"updateExtractedDocuments": true
},
"isAsyncMode": false,
"CodLayout": "{{CodLayout}}"
}
Con il parametro selectDocToExtracted (che corrisponde al parametro "Documenti da estrarre" presente in Interfaccia) è possibile scegliere se esportare "Tutti" i documenti (= valore 0 che corrisponde al Valore default) oppure solo quelli "Da estrarre" (= valore 1) oppure solo quelli "Estratti" (= valore 2).
Nel momento in cui si esegue l'esportazione documenti, se il parametro updateExtractedDocuments è valorizzato a "true", si contrassegnano tutti i documenti coinvolti nell'esportazione come "Estratti", tramite specifico indicatore. In questo modo ad una successiva esportazione, se si indica il parametro "selectDocToExtracted" a 1, saranno recuperati solo i nuovi documenti oppure se il parametro "selectDocToExtracted" a 2, saranno recuperati solo i documenti estratti in precedenza.
Nella body della response sono riportati eventuali messaggi di errore ed è generato lo streamfile in formato a 64bit, che dovrà essere convertito a cura dell'utente.
Uso dei filtri Come da interfaccia, è possibile anche applicare dei filtri di estrazione, tramite la funzione Search. Nell'esempio sotto riportato, si esportano tutti i documenti con data documento uguale a 15-04-2025.
{
"addParameters": {
"selectDocToExtracted": "0",
"updateExtractedDocuments": true
},
"isAsyncMode": false,
"CodLayout": "WAC_DOCUM",
"searchFilter": {
"filters": {
"operator": 0,
"items": [
{
"operator": 0,
"propertyName": "datadoc",
"comparer": 0,
"value": "2025-04-15"
}
]
}
}
}
NOTA BENE:
Per una corretta esportazione documenti, si ricorda che nel tracciato record utilizzato, è necessario definire nelle Condizioni di export la seguente istruzione SQL in modalità Avanzata:
"(PRECEDENTE [Numero_documento] <> [Numero_documento] )"
Produzione
Avanzamento quantità e versamenti tempi relativi a una o più fasi interne di produzione
Per gestire l'avanzamento delle quantità di produzione ed i versamenti tempi di un prodotto finito, a fronte di documenti di produzione interna, sono forniti i seguenti servizi:
- Il servizio per recuperare gli ordini in lavorazione è OrderProdPD
- Il servizio per evidenziare il dettaglio degli ordini in lavorazione è OrderWorkingCyclePD
- Il servizio per verificare la struttura della Distinta Base localizzata è OrderBomPD
- Il servizio per l'avanzamento delle quantità di produzione ed i versamenti tempi per fasi interne è il WorkOrderService e con l'uso dell'action internalstepprogress
Servizio OrderProdPD
Questo servizio serve per visualizzare tutte le righe articolo dei documenti con Tipo documento=Documenti di produzione interna e Sottotipo documento=Ordini a produzione monolivello e con indicatore "stato consegnato" maggiore di 2.
Si esegue una chiamata di tipo SEARCH, come sotto indicato:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/OrderProdPD/search?company={{defaultCompany}}
e nel Body si può applicare per esempio il filtro sulla proprietà "IndDeliveredStatus" che corrisponde allo "stato consegnato", per cui si desidera recuperare tutti i documenti evadibili. In questo caso il Body sarà così strutturato:
{
"filters": {
"items": [
{
"operator": 0,
"propertyName": "IndDeliveredStatus",
"comparer": 11,
"value": 5
}
]
},
"orderingProperties": {
"DeliveryDate": "0",
"OrderRegistrationNumber": "0",
"OrderLine": "0"
},
"pagesize": 10,
"pagenumber": 0
}
La response riporta l'elenco dei documenti di produzione interna e per ogni documento le righe articolo che lo compongono,recuperando alcune informazioni necessarie, ai fini della produzione. Per ogni riga, è riportato il seguente body:
{
"company": 2.0,
"custSuppCode": null,
"custSuppLegalName": null,
"deliveryDate": "2025-02-28T00:00:00",
"documentCode": "INT-ORDLAV",
"documentNotes": null,
"documentNumber": 4.0,
"documentSectional": "00",
"indDeliveredStatus": 2.0,
"itemCode": "BICI",
"itemDescription": "DESCRIZIONE BICI",
"itemVariantCode": "",
"lastChangeDate": "2025-04-03T15:57:41.48",
"manufacturingStartDate": null,
"orderLine": 1.0,
"orderRegistrationNumber": "202500000484",
"priority": null,
"qtyHandled": null,
"qtyOrdered": 10.000,
"qtyPutIn": 0.000,
"routingCode": "MONT",
"routingVersion": 0.0,
"storageCode": "00",
"unitOfMeasure": "PZ",
},
Prendiamo in considerazione, a titolo di esempio, "orderRegistrationNumber": "202500000484", per il quale si devono produrre 10 pezzi (come indicato su "qtyOrdered") del codice articolo BICI.
Prima di tutto, si verifica il dettaglio delle fasi interne di produzione, tramite il servizio OrderWorkingCyclePD.
Servizio OrderWorkingCyclePD
Questo servizio visualizza il dettaglio delle fasi delle righe degli ordini di produzione.
Si esegue una chiamata di tipo SEARCH con i seguenti parametri:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/OrderWorkingCyclePD/search?company={{defaultCompany}}
e nel Body si può applicare per esempio il filtro sulla proprietà "StepState" (che corrisponde allo 'Stato fase'), per cui il Body è così strutturato:
{
"filters": {
"items": [
{
"operator": 0,
"propertyName": "StepState",
"comparer": 11,
"value": 3
}
]
},
"orderingProperties": {
"OrderRegistrationNumber": "0",
"OrderLine": "0",
"StepProgressive": "0",
"SubStepProgressive": "0"
},
"pagesize": 10,
"pagenumber": 0
}
La response riporta per ogni riga articolo di un documento di produzione interna diverse informazioni, utili per procedere al successivo avanzamento quantità e versamenti tempi (ad esempio lo "StepCode" che corrisponde al 'codice fase di lavorazione').
Per orderRegistrationNumber="202500000484" (esempio di riferimento), la response è riportata come segue:
{
{
"centerCode": null,
"company": 2.0,
"departmentCode": "R1",
"documentCode": "INT-ORDLAV",
"documentNumber": 4.0,
"documentSectional": "00",
"flagGeneratedOrderWork": 0,
"machineCode": null,
"manufacturingEndDate": "2025-02-28T00:00:00",
"manufacturingStartDate": "2025-02-28T00:00:00",
"manufacturingTime": 0.00000000,
"numberPieces": null,
"orderLine": 1.0,
"orderRegistrationNumber": "202500000484",
"qty1": 10.000,
"qty1Delivered": 0.000,
"qty1Scrapped": 0.000,
"qty2": 0.000,
"qty2Delivered": 0.000,
"qty2Scrapped": 0.000,
"qtyReferenceLot": null,
"queueTime": 0.00000000,
"setUpTime": 0.00000000,
"stepCode": 1.0,
"stepDescription": "PRODUZIONE BASE",
"stepProgressive": 1.0,
"stepSequence": 10.0,
"stepState": 0,
"subcontractorCode": null,
"subStepProgressive": 0.0,
"toolCode": null,
"toolVariant": null,
"typeProduction": 0,
"waitingTime": 0.00000000,
"extensionData": [],
"additionalData": {}
},
}
Tramite il servizio OrderBomPD (descritto successivamente), è possibile verificare da quali componenti è formato il codice articolo 'BICI'.
Servizio OrderBomPD
Questo servizio permette di visualizzare la struttura della Distinta Base localizzata. Si esegue una chiamata di tipo SEARCH con i seguenti parametri:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/OrderBomPD/search?company={{defaultCompany}}&user=admin
e nel Body si può definire ad esempio l'ordinamento per Numero registrazione del documento di produzione interna (OrderRegistrationNumber), Progressivo riga interna (OrderLine) e Sequenza componente (ComponentSequence), per cui il body è così strutturato:
{
"orderingProperties": {
"OrderRegistrationNumber": "0",
"OrderLine": "0",
"ComponentSequence": "0"
},
"pagesize": 10,
"pagenumber": 0
}
Per orderRegistrationNumber="202500000484" (esempio di riferimento), la response riporta per ogni riga documento i componenti che formano il prodotto finito 'BICI', per cui il body della response è così riportato:
{
{
"bomLinkStorageCode": "00",
"company": 2.0,
"componentCode": "RUOTA",
"componentSequence": 10.0,
"componentVariantCode": "",
"documentCode": "INT-ORDLAV",
"documentNumber": 4.0,
"documentSectional": "00",
"guid": "47d608d9-55ee-4854-aa38-65e501b6f903",
"idBom": 16.0,
"orderLine": 1.0,
"orderRegistrationNumber": "202500000484",
"qtyExploded": 20.000,
"reservationStorageCode": "00",
"stepCode": 1.0,
"extensionData": [],
"additionalData": {}
},
}
A questo punto si può procedere con la produzione del codice articolo 'BICI' per le quantità necessaria, tramite il servizio WorkOrderService e l'action internalstepprogress.
Servizio WorkOrderService
Se all'interno di un documento è presente un codice articolo che è un prodotto finito di una distinta base, l'utente ha la possibilità di avanzare le quantità e/o di versare i tempi relativi alla produzione interna oppure di avanzare le fasi relativi alla produzione esterna.
Il servizio prevede due azioni:
-
internalstepprogress che consente di avanzare le quantità e/o di versare i tempi, relativi ad una o più fasi interne in corrispondenza di una riga documento di un ordine di lavorazione (ODL);
-
subcontractingstepprogress che permette di avanzare le fasi esterne lavorate da un terzista per una riga di ordine di produzione oppure di versare una riga ordine di c/lavoro passivo intestato ad un terzista.
Avanzamento tempi e quantità per ordine di Produzione Interna
Per eseguire l'azione internalstepprogress si deve effettuare la seguente chiamata POST:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/WorkOrderService/internalstepprogress?company={{defaultCompany}}
e nel body si possono indicare gli opportuni parametri (Data registrazione delle operazioni, numero registrazione e riga ordine su cui eseguire le operazioni, dati della fase o delle fasi da avanzare, dati dei tempi da versare, dati dei materiali da scaricare, dati di tracciabilità sia per l’articolo in ordine che per i materiali da scaricare).
Per esempio a fronte di un ordine di lavorazione, il cui orderRegistrationNumber="202500000484" (esempio di riferimento), si stabilisce di mettere in produzione in data registrazione 4 Aprile la quantità PZ 2 del codice articolo 'BICI' e di versare il tempo necessario per produrlo (nel nostro esempio 1 - un'ora). Di conseguenza il body è così strutturato:
{
"postingDate": "2025-04-04",
"orderRegistrationNumber": "202500000484",
"orderLine": 1,
"stepData": [
{
"stepCode": 1,
"stepProgressive": 1,
"qtyToProgress": 2,
"stepTimesData": [
{
"timesPostingDate": "2025-04-04",
"timeHours": 1
}
]
}
]
}
Nota bene: Si deve sempre indicare ALMENO un valore tra stepCode e StepProgressive (non è necessario indicarli entrambi).
La response riporta l'elenco dei numeri registrazione dei documenti generati, quindi il numReg del documento di Avanzamento per il codice articolo BICI e per la quantità indicata in "qtyToProgress" ed il numReg del documento di Scarico produzione per il componente della distinta ossia le RUOTE:
{
"result": true,
"documentRegistrationNumbers": [
"202500000542",
"202500000543"
],
"extensionData": [],
"additionalData": {}
}
Avanzamento C/Lavoro passivo
Per eseguire l'azione subcontractingstepprogress si deve effettuare la seguente chiamata POST:
POST {{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/WorkOrderService/subcontractingstepprogress?company={{defaultCompany}}
e nel body si possono indicare gli opportuni parametri (data registrazione delle operazioni, tipo ordine OCL(Ordine c/lavoro) oppure ODP (Ordine di Produzione), numero registrazione e numero riga ordine su cui eseguire le operazioni, codice terzista, estremi del documento relativo al terzista (fornitore), dati di una o più fasi da versare, dati dei materiali da scaricare, dati tracciabilità sia per l'articolo in ordine che per i materiali da scaricare).
Per un corretto avanzamento ordine c/lavoro passivo, si deve eseguire dall'ERP preventivamente la Generazione DDT invio a conto lavoro passivo.
Per esempio a fronte di un ordine di lavorazione, il cui orderRegistrationNumber è "202500000959" (esempio di riferimento), si stabilisce di avanzare le fasi esterne di produzione per il codice articolo-componente e di versare una riga ordine di conto lavoro passivo per il codice articolo-prodotto finito, in data registrazione 14 Luglio per la quantità PZ 2 del codice articolo 'PADRE-EST'.
In questo caso il body deve essere così strutturato:
{
"postingDate": "2025-07-14",
"orderType": 0,
"orderRegistrationNumber": "202500000959",
"orderLine": 1,
"subContractorCode": 1,
"subContractorDocument": "ABC123",
"subContractorDocumentDate": "2025-07-14",
"documentDate": "2025-07-14",
"documentSectional": "00",
"loadingStorage": "00",
"recipientSubContractorCode": 0,
"stepData": [
{
"stepCode": 101,
"qtyToProgress": 2,
"qtyToScrap": 1,
"stepComponentsData": [
{
"stepCode": 101,
"componentCode": "FIGLIO-EST",
"componentQty": 6,
}
]
}
]
}
Nel body della chiamata si definiscono i parametri qtyToProgress e qtyToScrap per specificare la quantità in produzione e l'eventuale quantità di scarto. Inoltre si possono anche definire i parametri traceabilityData per il codice articolo-prodotto finito e componentsTraceabilityData per il codice articolo-componente, nel caso in cui gli articoli presi in esame gestiscono i lotti, per specificare il corrispondente codice lotto.
La response riporta l'elenco dei numeri registrazione dei documenti generati, quindi il numReg dell'ordine conto lavoro passivo per il codice articolo PADRE-EST ed il numReg del documento di Avanzamento Fasi per il componente della distinta ossia FIGLIO-EST:
{
"result": true,
"documentRegistrationNumbers": [
"202500000960",
"202500000961"
],
"extensionData": [],
"additionalData": {}
}
Inserimento di un Progetto
Il servizio ProjectPD V2 è un endpoint REST che consente l’inserimento di un nuovo progetto all’interno del gestionale aziendale. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/PD/ProjectPD?company={{defaultCompany}}
con il seguente body:
{
"customerCode": 1,
"description": "PROGETTO DI PROVA",
"manufacturingStartDate": "2025-12-15T00:00:00",
"statusCode": "1",
"typeCode": "1",
"code": "PROVA2",
"companyCode": 2.0,
"manufacturingEndDate": "2026-12-15T00:00:00",
"activities": [
{
"actualEndDate": null,
"actualStartDate": null,
"code": "1",
"companyCode": 2.0,
"costCurrencyCode": "EURO",
"description": "Attività 1",
"isSocialSecurityTaxSubject": 0,
"isSupplementaryTaxSubject": 0,
"isVatReduced": 0.0,
"isWithholdingTaxSubject": 0,
"manualEstimatedCost": 0.0,
"manualEstimatedRevenue": 0.0,
"projectCode": "PROVA",
"revenueCurrencyCode": "EURO",
"vatCode": "22"
}
],
"nodes": [
{
"description": "Nodo 1",
"manualEstimatedCost": 0.0,
"statusCode": "APERTO",
"code": "NODO 1 ",
"companyCode": 2.0,
"costCalculationType": 0,
"costCurrencyCode": "EURO",
"projectCode": "PROVA",
"revenueCalculationType": 0.0,
"revenueCurrencyCode": "EURO",
"vatCode": "22 ",
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
]
}
Inserimento di un Reparto
Il servizio DepartmentPD è un endpoint REST che consente l’inserimento di un nuovo reparto all’interno del gestionale aziendale. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/PD/DepartmentPD?company={{defaultCompany}}
con il seguente body:
{
"companyCode": {{defaultCompany}},
"code": "TestP",
"description": "Descrizione Progetto test",
"shiftCode": 1,
"statusType": 0,
"storageCode": "00",
"worth": 1
}
Contabilità Analitica
Inserimento di un Movimento di Contabilità Analitica
Per registrare un Movimento di Contabilità Analitica, è necessario utilizzare una richiesta POST. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/CI/CostAccountingEntryCI?company={{defaultCompany}}
{
{
"datareg": "{{datareg}}",
"numdoc": "{{numdoc}}",
"sezdoc": "{{sezdoc}}",
"accountingReasonCodeCI": {
"codCaus": "{{codCaus}}"
},
"costAccountingEntryDetailCI": [
{
"sedeCg31": "{{sedeCg31_1}}",
"codPdcPc01": "{{codPdcPc01_1}}",
"codVdsPc01": "{{codVdsPc01_1}}",
"commessaPd25": "{{commessaPd25_1}}",
"contoPc03": "{{contoPc03_1}}",
"dadatacomp": "{{dadatacomp_1}}",
"descragg": "{{descragg_1}}",
"dittaCg18": "{{dittaCg18_1}}",
"importo": "{{importo_1}}",
"progRiga": "{{progRiga_1}}",
"vdsPc03": "{{vdsPc03_1}}",
"officeCO": {
"codice": "{{officeCO_codice_1}}"
}
}
],
"customerSupplierCO": "{{customerSupplierCO}}",
"ifrsTypeCO": "{{ifrsTypeCO}}",
"movementTypeCO": {
"codice": "{{movementTypeCO_codice}}"
},
"officeCO": {
"codice": "{{officeCO_codice}}"
}
}
}
Esempio di response:
{
{
"totalAmount": 0.0,
"codCausCi03": "CO99",
"descrcaus": "Test da WebAPI",
"datadoc": null,
"datareg": "2025-09-01T00:00:00",
"descragg": null,
"dittaCg18": 1000.0,
"flgDocbis": 0.0,
"flgMovvar": 1.0,
"guid": "79e4ae72-c79b-4f88-9223-9bac1df8afec",
"indProvenienza": 1,
"numdoc": 2.0,
"numdocorig": null,
"numregCo99": "202500001191",
"sezdoc": "HR",
"tipodoc": 66.0,
"accountingReasonCodeCI": {
"causcollrifCi03": null,
"flgAutomatico": 0.0,
"flgCostomanod": 0.0,
"idEntityWithDescriptions": 903,
"idprov": 37.0,
"indCorrmag": 0.0,
"indMovcostipers": 0.0,
"indPropcosto": 0.0,
"indProvcosto": 2.0,
"indStaperCi04": 0.0,
"indTipocosric": 0.0,
"indTipocostomag": 0.0,
"indTipopsBu01": null,
"modelloCi04": null,
"codCaus": "CO99",
"codCauscoll": null,
"descr": "Test da WebAPI",
"flgInvsegno": 0.0,
"flgNumautom": 0.0,
"flgObblcommessa": 0.0,
"flgObblcompetenza": 0.0,
"flgObblprogetto": 0.0,
"flgRiccommessa": 0.0,
"flgRiccompetenza": 0.0,
"flgRicprogetto": 0.0,
"flgRilprog": 0.0,
"flgTipomovdaorigine": 0,
"idmediaCg99": null,
"indOperazione": 0.0,
"indQuadratura": 99.0,
"indRegoridest": 0,
"indRegvalqta": 0,
"indRicclifor": 0.0,
"indRichcorrareaamm": 0.0,
"indTipomov": 1,
"indTipomovdati": 0.0,
"sottotipopsBu01": null,
"extensionData": [],
"additionalData": {},
"pluginData": {}
},
"costAccountingEntryDetailCI": [
{
"sedeCg31": 0.0,
"adatacomp": null,
"codDipPd06": null,
"codiceCgc0": null,
"codPdcPc01": 81.0,
"codRepPd07": null,
"codVdsPc01": 80.0,
"commessaPd25": null,
"contoPc03": "00001 ",
"dadatacomp": null,
"descragg": null,
"dittaCg18": 1000.0,
"guid": "f948750c-d3a8-4556-9496-8eb6f4d0a5bc",
"importo": 1000.00,
"numregCo99": "202500001191",
"progettoPd68": null,
"progRiga": 1.0,
"qta": null,
"rigacontCg42": null,
"scommessaPd25": null,
"sprogettoPd69": null,
"vdsPc03": "5800050115 ",
"officeCO": {
"cap": "00600",
"citta": "Roma",
"codice": 0.0,
"dittaCg18": 1000.0,
"idmediaCg99": null,
"indDimcentrocomm": 0.0,
"indIrizzo": "Default",
"numerorea": null,
"progRea": null,
"prov": "RM",
"rowversion": "AAAAAAAg678=",
"extensionData": [],
"additionalData": {},
"pluginData": {}
},
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
],
"customerSupplierCO": null,
"ifrsTypeCO": null,
"movementTypeCO": {
"codice": 1,
"descr": null,
"descrbreve": "Dc",
"descrmedia": "Da Consol.",
"flgBilanci": 1,
"flgBilancicons": 1,
"flgCanrevoke": 1,
"flgCoan": 1,
"flgContrsaldi": 1,
"flgDoc": 1,
"flgEc": 1,
"flgElabiva": 1,
"flgHyperion": 1,
"flgMovcont": 1,
"flgMoviva": 1,
"flgPartitari": 1,
"flgPf": 1,
"flgQuerypn": 1,
"indAcconti": 2,
"indCambiali": 2,
"indChiuseff": 2,
"indConsolidamento": 1,
"indDatabilanci": 0,
"indEcportaper": 2,
"indEcportchius": 2,
"indIncassobf": 2,
"indInsoluti": 2,
"indProforma": 0,
"indRaggr": 0,
"indRatrisc": 2,
"indRettifica": 0,
"indSimulbilanci": 0,
"indTipoifrs": 0,
"extensionData": [],
"additionalData": {},
"pluginData": {}
},
"officeCO": null,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
}
Inserimento Causali Contabilità Analitica
Per registrare una causale di Contabilità Analitica, è necessario utilizzare una richiesta POST. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/CI/AccountingReasonCodeCI?company={{defaultCompany}}
{
"codCaus": "{{codCausCoAn}}",
"descr": "Test da WebAPI"
}
Esempio di response:
{
"causcollrifCi03": null,
"flgAutomatico": 0.0,
"flgCostomanod": 0.0,
"idEntityWithDescriptions": 903,
"idprov": 38.0,
"indCorrmag": 0.0,
"indMovcostipers": 0.0,
"indPropcosto": 0.0,
"indProvcosto": 2.0,
"indStaperCi04": 0.0,
"indTipocosric": 0.0,
"indTipocostomag": 0.0,
"indTipopsBu01": null,
"modelloCi04": null,
"codCaus": "12",
"codCauscoll": null,
"descr": "Test da WebAPI",
"flgInvsegno": 0.0,
"flgNumautom": 0.0,
"flgObblcommessa": 0.0,
"flgObblcompetenza": 0.0,
"flgObblprogetto": 0.0,
"flgRiccommessa": 0.0,
"flgRiccompetenza": 0.0,
"flgRicprogetto": 0.0,
"flgRilprog": 0.0,
"flgTipomovdaorigine": 0,
"idmediaCg99": null,
"indOperazione": 0.0,
"indQuadratura": 99.0,
"indRegoridest": 0,
"indRegvalqta": 0,
"indRicclifor": 0.0,
"indRichcorrareaamm": 0.0,
"indTipomov": 1,
"indTipomovdati": 0.0,
"sottotipopsBu01": null,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Attivazione dei conti di contabilità generale
Per l'attivazione dei conti COGE utilizzati in CoAN, è necessario utilizzare una richiesta POST. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/CI/ActiveAccountCI?company={{defaultCompany}}
{
"accountCode": "{{accountCodeCI}}",
"companyCode": "{{defaultCompany"}}",
"accountGroupCode": "{{CodeaccountGroup}}"
}
Esempio di response:
{
"accountCode": "0300050099",
"accountGroupCode": 80.0,
"companyCode": 1000.0,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Correlazione Causali con Contabilità Generale
Per l'inserimento della Correlazione Causali con Contabilità Generale, è necessario utilizzare una richiesta POST. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/CI/CorrelationAccountingReasonCodeCI?company={{defaultCompany}}
{
"accountingReasonCode": "{{accountingReasonCode}}",
"analyticalAccountingReasonCode": "{{analyticalAccountingReasonCode}}",
"companyCode": {{defaultCompany}},
"isDefault": 0
}
Esempio di response
{
"accountingReasonCode": "1",
"analyticalAccountingReasonCode": "CO01",
"companyCode": 1000.0,
"isDefault": 0.0,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Configurazione Proposta Sezionali
Per l'inserimento dela confgirazione della Proposta Sezionali, è necessario utilizzare una richiesta POST. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v2/{{scope}}/CI/SectionalProposalCI?company={{defaultCompany}}
{
"analyticalAccountingReasonCode": "{{analyticalAccountingReasonCode}}",
"companyCode": {{defaultCompany}},
"sectionalCode": "HR"
}
Esempio di response:
{
"analyticalAccountingReasonCode": "CO01",
"companyCode": 1000.0,
"sectionalCode": "HR",
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Configurazione tipologia di costi/ricavi
Per l'inserimento della configurazione della tipologia di costi/ricavi, è necessario utilizzare una richiesta POST. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/CI/CostNatureCI?company={{defaultCompany}}
{
"costNatureCode": 6,
"costNatureDescription": "Ricavo WebAPI",
"costRevenueType": 2,
"hyperMediaId": null,
"printOrder": 5,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Esempio di response:
{
"costNatureCode": 6.0,
"costNatureDescription": "Ricavo WebAPI",
"costRevenueType": 2.0,
"hyperMediaId": null,
"printOrder": 5.0,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Gestione dei conti di Contabilità Analitica
Per l'inserimento dei contri di Contabilità Analitica, è necessario utilizzare una richiesta POST. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/CI/AccountCI?company={{defaultCompany}}
{
"accountCode": "{{accountCode}}",
"description": "conto piano 80",
"accountGroupCode": {{accountGroupCode}},
"costNatureCode": {{codNature}},
"costSourceType": 0
}
Esempio di response:
{
"accountCode": "58000",
"accountGroupCode": 81.0,
"costNatureCode": null,
"costSourceType": 0.0,
"description": "conto piano 80",
"hyperMediaId": null,
"extensionData": [],
"additionalData": {},
"pluginData": {}
}
Inserimento prezzo listino su un nuovo articolo
Il servizio ListinoArticoloLI/addlistinotonewarticolo è un endpoint REST che consente di inserire un nuovo listino prezzi. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/LI/ListinoArticoloLI/addlistinotonewarticolo?Company={{defaultCompany}}
con il seguente body:
{
"codiceArticolo": "00001",
"prezzo": 123,
"dataInizioVal": "2026-02-26T16:33:45.281Z",
"dataFineVal": "2026-02-28T16:33:45.281Z",
"isVendita": true
}
Ricerca del prezzo di listino in base alla data di riferimento
Il servizio ListinoArticoloLI/searchlistino è un endpoint REST che consente di ricercare il prezzo di listino in base alla data di riferimento. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/LI/ListinoArticoloLI/searchlistino?Company={{defaultCompany}}
con il seguente body:
{
"dataRiferimento": "2026-02-25T15:35:38.382Z"
}
Ricerca del prezzo di listino
Il servizio ListinoArticoloLI/search è un endpoint REST che consente di ricercare il prezzo di listino in base alla data di riferimento. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/LI/ListinoArticoloLI/search?Company={{defaultCompany}}
con il seguente body:
{
"dataRiferimento": "2026-02-25T15:35:38.382Z",
"pageSize": 10,
"pageNumber": 0
}
Inserimento di una classe di progetto A
Il servizio ProjectClassAPD è un endpoint REST che consente di inserire le classi di progetto A. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/ProjectClassAPD?Company={{defaultCompany}}
con il seguente body:
{
"code": "TEST_AAA",
"companyCode": 2.0,
"description": "Descrizione Classe A",
"isHierarchic": 1,
"structureType": 0
}
Inserimento di una classe di progetto B
Il servizio ProjectClassBPD è un endpoint REST che consente di inserire le classi di progetto B. Ecco un esempio pratico:
{{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/ProjectClassBPD?Company={{defaultCompany}}
con il seguente :
{
"code": "TEST_BBB",
"companyCode": 2.0,
"description": "Descrizione Classe B",
"isHierarchic": 1.0,
"structureType": 0.0,
"projectClassA": {
"code": "TEST_AAA",
"companyCode": 2.0
}
}
Inserimento di una classe di progetto C
Il servizio ProjectClassCPD è un endpoint REST che consente di inserire le classi di progetto C. Ecco un esempio pratico: :
{{webapi_base_url}}/{{api}}/v1/{{scope}}/PD/ProjectClassCPD?Company={{defaultCompany}}
con il seguente body:
{
"code": "TEST_CCC",
"companyCode": 2.0,
"description": "Descrizione Classe C",
"structureType": 0.0,
"projectClassB": {
"code": "TEST_BBB",
"companyCode": 2.0
}
}
Gestioni non supportate
Qui di seguito un elenco di gestioni particolari attualmente non supportate in inserimento di un documento via WebAPI:
- Controllo rischio
- Esplosione schede multiple articoli