EN/API/Warehouse

From Smart Biogas Wiki
Jump to navigation Jump to search

◀ Back to API Menu

List of warehouses (internal and external) of a plant

Authentication must be specified in the request header:

X-API-TOKEN: {128-character key provided for the specific plant}

In Smartbiogas, the warehouse is divided into as many units as there are feedstocks (i.e., stored materials) and by origin (Internal or External).

For example: A plant might have 2 warehouses for Maize: - one internal for maize coming from the fields of the company owning the plant or its partners. - one external for maize purchased from external entities.

A plant may have only one (usually internal) if it does not purchase maize from third parties.

This structure is repeated for each feedstock. For example, we might have 1 internal warehouse for slurry, one for manure, one for Maize, and perhaps one external for Wheat.

Warehouse movements are then associated with a specific warehouse. This creates a logical container that groups all movements of a feedstock (internal or external). For each movement, data such as supplier, date/time, quantity, weighing code, vehicle license plate, etc., are saved.

Warehouse List

List of all warehouses for a plant.

GET https://smartbiogas.it/api/v1/warehouse

Result: Json with an array of results 

[
	{
		"warehouse_id": warehouseId,
		"location_id": -1 -> INTERNAL, 1 -> EXTERNAL,
		"substrati_id": feedstockId,
		"f_json_description": "{\"it\": \"Italian Desc\", \"en\": \"English Desc\", \"fr\": \"French Desc\", \"es\": \"Spanish Desc\"}",
		"f_location_description": "Description of the 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"
	},
	...
]


Single warehouse details:

GET https://smartbiogas.it/api/v1/warehouse/{warehouseId}

Example: https://smartbiogas.it/api/v1/warehouse/5869

Result: Same Json as above but with a single record

Single warehouse stock:

GET https://smartbiogas.it/api/v1/warehouse/{warehouseId}/stock_balance/{date in ISO format yyyy-MM-dd hh:mm:ss}

example https://smartbiogas.it/api/v1/warehouse/3857/stock_balance/2024-02-28 23:59:59

Result: 

{
"warehouse_id": warehouseId,
"f_last_stock_datetime": indicates the date of the most recent on-hand stock relative to the input date,
"f_last_movement_datetime":  indicates the last recorded movement before the input date,
"f_quantity":  tons of material calculated between the last on-hand stock and the last movement,
"substrati_id": substrateId,
"location_id": -1 -> INDOOR, 1 -> OUTDOOR,
}

Example: 

{
"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
}

Warehouse movements

[edit | edit source]

Once the warehouse is identified, you can manage movements using the following APIs:

GET [1]

Result: Json with a list of movements 

[
	{
		"movement_id": movementId,
		"warehouse_id": warehouseId,
		"f_quantity": "Quantity in tons",
		"f_movement_datetime": "Date/time in ISO format",
		"f_movement_type": See Warehouse Movement Types,
		"soggetto_id": subjectId (or -1 for no subject (internal movements)),
	},
	{
		"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,
	},
	...
]


Search single movement by movementId

GET https://smartbiogas.it/api/v1/warehouse/{warehouseId}/movements/{movementId}

Example: https://smartbiogas.it/api/v1/warehouse/3857/movements/350000

Result: Json with movement details 

[
	{
		"movement_id": movementId,
		"warehouse_id": warehouseId,
		"f_quantity": "quantity in tons",
		"f_movement_datetime": "Date/time in ISO format",
		"f_movement_type": See Warehouse Movement Types,
		"soggetto_id": subjectId (or -1 for no subject (internal movements)),
		"f_targa": "Vehicle license plate",
		"f_trasportatore": "operator identifier",
		"f_disinfezione": 0 -> without disinfection / 1 -> with disinfection,
		"f_price": "price in euros per ton",
		"f_distance": "trip distance in km",
		"f_provenienza": "origin identifier",
		"plant_suppliers_contracts_id": contractId (-1 if no contract),
		"f_contract_number": Contract number/code (only if contractId <> -1),
		"f_partita": "Batch number associated with the movement",
		"f_ddt_number": "Waybill (DDT) number",
		"f_num_pesata": "Weighing number",
		"f_tipo_documento": -1 -> no document, 1 -> Waybill (DDT), 2 -> immediate invoice, 3 -> other
	},
	{
		"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": 1234
		"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
	}
]

Insert warehouse movement

POST https://smartbiogas.it/api/v1/warehouse/3857/movements

The call must include the X-API-TOKEN authentication and a JSON formatted as follows: 

{
	"f_quantity": INT quantity in tons,
	"f_movement_datetime": DATETIME "date/time in ISO format",
	"f_movement_type": INT See Warehouse Movement Types,
	"soggetto_id": INT subjectId or -1 if supplier/recipient is missing (e.g., internal production or agricultural use),
	"f_targa": TEXT "Vehicle license plate",
	"f_trasportatore": TEXT "Operator identification",
	"f_disinfezione": BIT 0 -> no disinfection, 1 -> disinfection performed,
	"f_price" : DECIMAL price per ton in euros,
	"f_distance" : INT distance in KM,
	"f_provenienza" : TEXT "Origin identifier",
	"plant_suppliers_contracts_id" : INT contractId (-1 if not present),
	"f_partita" : TEXT "Batch code linked to the movement",
	"f_ddt_number": TEXT "Waybill (DDT) number",
	"f_num_pesata": INT weighing number,
	"f_tipo_documento": -1 -> no document, 1 -> Waybill (DDT), 2 -> Immediate invoice, 3 -> other
}

Example: 

{
	"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" : "North Field",
	"plant_suppliers_contracts_id" : -1,
	"f_partita" : "",
	"f_ddt_number": "2027/001",
	"f_num_pesata": 123456,
	"f_tipo_documento": 1
}


Update data of a single movement

PATCH https://smartbiogas.it/api/v1/warehouse/{warehouseId}/movements/{movementId}

The same JSON used for insertion must be passed; the system will update the data instead of adding a new movement.

Since the movement is linked to a specific warehouse (identified by warehouseId), the feedstock type, warehouse location (internal/external), and the plant itself cannot be changed via this method.


Result of insertion and update: Json with status information: 

{
	"error_code": see API Error Codes,
	"movement_id": movementId (for insertion, returns the new ID; for updates, returns the ID target of the operation),
	"message": "Message explaining the outcome or error"
}

Examples: 

{
	"error_code": 0,
	"movement_id": 4578898,
	"message": "Movement inserted correctly"
}

{
	"error_code": 10,
	"movement_id": 4578694,
	"message": "Duplicate detected"
}
In this case, an attempt was made to insert the same movement twice.
A movement is unique based on these keys:
- warehouse_id (which identifies the plant, feedstock, and Internal/External status)
- Date/time (to the second)
- Movement Type

If the system detects an existing record with these matching conditions, it returns error 10.

{
	"error_code": 11,
	"message": "Date not valid: yyyy"
}
Retrieved from "https://wiki.monvisoenergia.it/index.php?title=EN/API/Warehouse&oldid=288"