API/Magazzino
Elenco dei magazzino (interni ed esterni) di un impianto
Nell'header delle richieste va specificata l'autenticazione
X-API-TOKEN: {chiave da 128 caratteri fornita per l'impianto in questione)
In smartbiogas il magazzino è frazionato in tanti magazzini quanti sono i substrati (cioè le materie stoccate) e per provenienza Interna o esterna.
Ad esempio
Un impianto potrebbe avere 2 magazzini per il Mais:
- uno interno per il mais proveniente dai campi dell'azienda proprietaria dell'impianto o dai suoi soci.
- uno esterno per il mais proveniente da acquisti da soggetto esterni.
Un impianto può averne anche solo uno (normalmente interno) se non acquista mais da esterni.
Questo viene ripetuto per ogni substrato. Ad esempio potremmo avere 1 magazzino interno per liquame, uno per letame, uno per Mais e magari uno esterno per Frumento.
I movimenti di magazzino vengono quindi associati ad un magazzino, in tal modo abbiamo un contenitore logico che raggruppa tutti i movimenti di un substrato (interno o esterno) e, per ogni movimento, rimangono salvati dati quali: fornitore, data/ora, quantità, codice della pesata, targa del mezzo ecc...
Elenco Magazzini
Elenco di tutti i magazzini di un impianto.
GET https://smartbiogas.it/api/v1/warehouse
Risultato: Json con un array di risultati
[
{
"warehouse_id": idMagazzino,
"location_id": -1 -> INTERNO, 1 -> ESTERNO,
"substrati_id": idSubstrato,
"f_json_description": "{\"it\": \"Desc italiana\", \"en\": \"Desc inglese\", \"fr\": \"Desc francese\", \"es\": \"Desc spagnola\"}",
"f_location_description": "Descrizione della location_id (Internal/External)"
},
{
"warehouse_id": 5332,
"location_id": -1,
"substrati_id": -10,
"f_json_description": "{\"it\": \"Digestato solido\", \"en\": \"Solid digestate\", \"fr\": \"\", \"es\": \"\"}",
"f_location_description": "Internal"
},
...
]
Dati del singolo magazzino:
GET https://smartbiogas.it/api/v1/warehouse/{idMagazzino}
esempio https://smartbiogas.it/api/v1/warehouse/5869
Risultato: stesso Json di sopra ma con un solo record
Stock del singolo magazzino:
GET https://smartbiogas.it/api/v1/warehouse/{idMagazzino}/stock_balance/{data in formato ISO yyyy-MM-dd hh:mm:ss}
esempio https://smartbiogas.it/api/v1/warehouse/3857/stock_balance/2024-02-28+23:59:59
Risultato:
{
"warehouse_id": idMagazzino,
"f_last_stock_datetime": indica la data della più recente giacenza rispetto la data in input,
"f_last_movement_datetime": indica l'ultimo movimento registrato prima della data in input,
"f_quantity": tonnellate di materiale calcolato tra l'ultima giacenza e l'ultimo movimento,
"substrati_id": idSubstrato,
"location_id": -1 -> INTERNO, 1 -> ESTERNO,
}
Esempio:
{
"warehouse_id": 3857,
"f_last_stock_datetime": "2000-01-01 00:00:00",
"f_last_movement_datetime": "2022-12-31 23:59:59",
"f_quantity": "4954.000",
"substrati_id": 6,
"location_id": 1
}
Movimenti di magazzino
[edit | edit source]Una volta identificato il magazzino si può lavorare sui movimenti con le seguenti API
GET https://smartbiogas.it/api/v1/warehouse/3857/movements
Risultato: Json con elenco di movimenti
[
{
"movement_id": idMovimento,
"warehouse_id": idMagazzino,
"f_quantity": "Quantità in tonnellate",
"f_movement_datetime": "Data/ora in formato ISO",
"f_movement_type": Vedi Tipologia Movimenti magazzino,
"soggetto_id": subjectId (o -1 per nessun soggetto collegato (esempio movimenti interni)),
},
{
"movement_id": 448825,
"warehouse_id": 3857,
"f_quantity": "-9.000",
"f_movement_datetime": "2013-02-01 23:59:59",
"f_movement_type": 11,
"soggetto_id": -1
},
...
]
Ricerca movimenti per data
[edit | edit source]Indicanto un parametro è possibile filtrare i movimenti solo a partire da una data specificata in formato ISO
GET https://smartbiogas.it/api/v1/warehouse/5239/movements?f_data_da={iso_date}&f_data_a={iso_date}
f_data_a e f_data_da possono essere usate anche da sole
esempio https://smartbiogas.it/api/v1/warehouse/5239/movements?f_data_da=2026-01-01+23:59:59
Ricerca singolo movimento per idMovimento
GET https://smartbiogas.it/api/v1/warehouse/{idMagazzino}/movements/{idMovimento}
esempio https://smartbiogas.it/api/v1/warehouse/3857/movements/350000
Risultato: Json con dettagli del movimento
[
{
"movement_id": idMovimento,
"warehouse_id": idMagazzino,
"f_quantity": "quantità in tonnellate",
"f_movement_datetime": "Data/ora in formato ISO",
"f_movement_type": Vedi Tipologia Movimenti magazzino
"soggetto_id": subjectId (or -1 nessun soggetto (per movimenti interni)),
"f_targa": "Targa del mezzo",
"f_trasportatore": "identificativo dell'operatore",
"f_disinfezione": 0 -> senza disinfezione / 1 -> con disinfezione,
"f_price": "prezzo in euro a tonnellata",
"f_distance": "distanza in km del viaggio",
"f_provenienza": "identificativo della provenienza",
"plant_suppliers_contracts_id": idContratto (-1 se non c'è contratto),
"f_contract_number": Numero/codic del contratto (solo se idContratto <> -1),
"f_partita": "Numero della partita a cui il movimento è associato",
"f_ddt_number": "Numero di DDT",
"f_num_pesata": "Numero della pesata",
"f_tipo_documento": -1 -> non c'è documento, 1 -> DDT, 2 -> fattura immediata, 3 -> altro
},
{
"movement_id": 350000,
"warehouse_id": 3857,
"f_quantity": "3500.000",
"f_movement_datetime": "2013-01-01 00:00:00",
"f_movement_type": 1,
"soggetto_id": -1,
"f_targa": "",
"f_trasportatore": "",
"f_disinfezione": 0,
"f_price": "0.00",
"f_distance": "0",
"f_provenienza": "",
"plant_suppliers_contracts_id": -1,
"f_contract_number": null,
"f_partita": "",
"f_ddt_number": "",
"f_num_pesata": "",
"f_tipo_documento": -1
}
]
Inserimento movimento di magazzino
POST https://smartbiogas.it/api/v1/warehouse/3857/movements
La chiamata deve avere oltre all'autenticazione X-API-TOKEN un JSON così formato:
{
"f_quantity":INT quantità in tonnellate,
"f_movement_datetime": DATETIME "data/ora in formato ISO",
"f_movement_type": INT Vedi Tipologia Movimenti magazzino,
"soggetto_id": INT idSoggetto o -1 se manca il fornitore o il destinatario (nei casi di produzione interna o utilizzazione agricola),
"f_targa":TEXT "Targa del mezzo",
"f_trasportatore":TEXT "Identificazione dell'operatore",
"f_disinfezione": BIT 0 -> no disinfezione, 1 -> disinfezione eseguita,
"f_price" : DECIMAL prezzo a tonnellata in euro,
"f_distance" : INT distanza in KM,
"f_provenienza" : TEXT "Identificativo della provenienza",
"plant_suppliers_contracts_id" : INT idContratto (-1 se non presente),
"f_partita" : TEXT "codice della partita a cui è collegato il movimento",
"f_ddt_number": TEXT"Numero DDT",
"f_num_pesata": INT numero della pesata,
"f_tipo_documento": -1 -> no documento, 1 -> DDT, 2 -> Fattura immediata, 3 -> altro
}
Esempio
{
"f_quantity":101,
"f_movement_datetime":"2027-01-01 02:58:59",
"f_movement_type":1,
"soggetto_id": 2278,
"f_targa":"ZZ 999 YY",
"f_trasportatore":"Mario Rossi",
"f_disinfezione": 0,
"f_price" : 0.23,
"f_distance" : 25,
"f_provenienza" : "Campo nord",
"plant_suppliers_contracts_id" : -1,
"f_partita" : "",
"f_ddt_number":"2027/001",
"f_num_pesata": 123456,
"f_tipo_documento": 1
}
Aggiornamento dei dati di un singolo movimento
PATCH https://smartbiogas.it/api/v1/warehouse/{idMagazzino}/movements/{idMovimento}
Come per l'inserimento va passato lo stesso json, il sistema invece di aggiungere un movimento andrà ad aggiornare i dati.
essendo il movimento collegato ad un magazzino identificato da idMagazzino risulta evidente che il tipo di substrato, la locazione del magazzino (interno/esterno), tantomeno l'impianto non possono essere variate in questo modo.
Risultato inserimento e aggiornamento: json con informazioni sullo stato della riuscita:
{
"error_code": vedi Codici errore API,
"movement_id": idMovimento (in caso di inserimento torna l'id appena inserito, in caso di aggiornamento l'idMovimento su cui si è tentata l'operazione),
"message": "Messaggio per capire l'eventuale errore"
}
esempi:
{
"error_code": 0,
"movement_id": 4578898,
"message": "Movement inserted correctly"
}
{
"error_code": 10,
"movement_id": 4578694,
"message": "Duplicate detected"
}
In questo caso si è tentato di inserire per 2 volte di fila lo stesso movimento.
Un movimento è univoco per queste chiavi:
- idMagazzino (che identifica già un magazzino di un impianto di un substrato e se Interno o Esterno)
- Data/ora (al secondo)
- Tipo Movimento
se il sistema rileva che si sta tentando di inserire un movimento ma esiste già per un record con quelle condizioni, da l'errore 10.
{
"error_code": 11,
"message": "Date not valid: aaaa"
}