digiFLUX Core

HINWEIS: DAS API UND DIE STRUKTUR FÜR DIE DATENLIEFERUNG PER XLS SIND NOCH IN ARBEIT. DIE UNTENSTEHENDEN ANGABEN SIND ALS ORIENTIERUNGSHILFE GEDACHT. DETAILS KÖNNEN SICH ABER NOCH ÄNDERN.
NOTICE: THE API AND THE XLS STRUCTURE FOR THE FILE UPLOAD FEATURE ARE WORK IN PROGRESS. PLEASE CONSIDER THE INFORMATION BELOW AS AN ORIENTATION GUIDE. DETAILS ARE HOWEVER SUBJECT TO CHANGE.

Shipments

This section explains how shipments of plant protection products, etc. can be administered. The state diagram and the list of business processes cover the whole life cycle of a shipment, i. e. from creation by the sender to acceptance or rejection by the recipient. Four processes are relevant to senders: add a shipment, delete a shipment, get shipment set, and get shipment details. The API services supporting these processes are mentioned below.

Shipment state diagram

Shipment related business processes

add a shipment

sender process
A shipment can be added to digiFLUX via the digiFLUX web application, the file upload funcion or the API. It is given the initial state created.

To add a shipment via the API, use POST {{baseUrl}}/digiflux/core/transactions/v1/shipments.

delete a newly created shipment

sender process
Within 30 minutes after creation, a shipment can be deleted by the sender (or anyone else authorised to act on their behalf). In this case the entry is physically deleted, i. e. removed from the digiFLUX data store. A shipment can be deleted via the web digiFLUX application or the API.
To delete a shipment via the API, use DEL {{baseUrl}}/digiflux/core/transactions/v1/shipments/DIGIFLUX/:id.

automatically update state of newly created shipment

system process
If a newly created shipment isn't deleted within this 30 minutes time window, the digiFLUX backend system automatically sets the shipment state to, respectively, sent or accepted, depending on whether or not the recipient decided to auto-accept delivieries of the product type in question.

accept or reject shipment

recipient process
If the recipient decided to accept or reject shipments manually, they can provide the appropriate feedback via the digiFLUX web application or via an API call. If the recipient chose the setting "accept manually with automated acceptance after 15 days" the system will change the state of transactions in the state sent to accepted after the deadline. A shipment can be accepted or rejected via the web digiFLUX application or the API.

To accept a shipment via the API, use PUT {{baseUrl}}/digiflux/core/transactions/v1/shipments/DIGIFLUX/:id/status with newStatus set to ACCEPTED.

To reject a shipment via the API, use PUT {{baseUrl}}/digiflux/core/transactions/v1/shipments/DIGIFLUX/:id/status with newStatus set to REJECTED.

auto-accept overdue shipments on 30 January

system process

On January 30th, the digiFLUX system automatically sets all transactions of the preceeding year, which are still in the state sent to accepted.

get shipment set

sender and recipient process
The system provides a list of shipments that match given search criteria.
To search for shipments via the API, use GET {{baseUrl}}/digiflux/core/transactions/v1/shipments.

get shipment details

sender and recipient process
The system provides the details of a shipment specified by its ID.
To obtain the details of a shipment via the API, use GET {{baseUrl}}/digiflux/core/transactions/v1/shipments/DIGIFLUX/:id.

Structure of a shipment record in json format

{  
  "id": {  
    "id": "string",  
    "sourceSystemId": "string"  
  },  
  "alternateId": {  
    "id": "string",  
    "sourceSystemId": "string"  
  },  
  "product": {  
    "id": "string",  
    "sourceSystemId": "string"  
  },  
  "productFamily": "string",  
  "productCategoryCode": "string",  
  "productCategoryDe": "string",  
  "productCategoryFr": "string",  
  "productCategoryIt": "string",  
  "productCategoryEn": "string",  
  "shippedFromStock": {  
    "id": "string",  
    "sourceSystemId": "string"  
  },  
  "shippedToStock": {  
    "id": "string",  
    "sourceSystemId": "string"  
  },  
  "quantity": {  
    "value": 0,  
    "unit": "kg"  
  },  
  "shipmentDate": "YYYY-MM-DD",  
  "productShipmentStatus": {  
    "id": "string",  
    "sourceSystemId": "string"  
  },  
  "comment": "string",  
  "rejectionReason": "string",  
  "lastModifiedAt": "YYYY-MM-DD",  
  "backupToAddress": {  
    "name": "string",  
    "givenName": "string",  
    "zip": "string",  
    "city": "string",  
    "canton": "AG",  
    "email": "string",  
    "dateOfBirth": "YYYY-MM-DD",  
    "phone": "string"  
  },  
  "shippedFromAddress": {  
    "companyName": "string",  
    "firstName": "string",  
    "lastName": "string",  
    "street": "string",  
    "streetNumber": "string",  
    "postalCode": "string",  
    "city": "string",  
    "canton": "AG",  
    "country": "CH",  
    "phoneNumber": "string",  
    "email": "string"  
  },  
  "shippedToAddress": {  
    "companyName": "string",  
    "firstName": "string",  
    "lastName": "string",  
    "street": "string",  
    "streetNumber": "string",  
    "postalCode": "string",  
    "city": "string",  
    "canton": "AG",  
    "country": "CH",  
    "phoneNumber": "string",  
    "email": "string"  
  }  
}  

Note

To determine a recipient's BUR number, they can consult the Business and Enterprise Register provided by the Federal Statistical Office. You can apply to use their API to submit queries or obtain data in xml format. For details see the BURWeb page.

File upload

To add new shipments to digiFLUX via the file upload function, the data must be structured according to this xlxs template. A version with sample data can be found here.

Column	must	format	example / note	corresponding API attribute	eCH std
Liefer-Nr. Delivery-No external
Kassensystem
Name Kassensystem external system name
Delivery date Lieferdatum	y	YYYY-MM-DD	2024-31-12	shipmentDate	y
Comment Kommentar	n	text	"Ihre Bestellung vom 20.10.2024"	comment	y
Product-ID Produkt-ID	y	text			y
Quantity Menge	y	num	5.000	quantity.value
Unit Einheit	y	["KG", "M3", "PC"]	farmyard & recycled fertilisers must be declared in "KG" or "M3"	quantity.unit
ID Sender inventory ID Abgeber Vorrat	y	text
Typ Abgeber Vorrat Type Sender inventory	y	["DIGIFLUX", "BUR", "AGATE"]	DIGIFLUX → id is digiFLUX inventory ID BUR → id is a BUR no AGATE → id is Agate no of a person	shippedFromStock.id
Firstname Sender inventory Vorname Abgeber Vorrat	cond	text	mandatory for pseudo inventory with private address	shippedToAddress.lastName	n
Nachname Abgeber Vorrat	cond	text		shippedToAddress.lastName
Lastname Sender inventory Company name Sender inventory	Cond	text	see above	shippedToAddress.companyName
Street Sender inventory Straße Abgeber Vorrat	cond	text	see above
House number Sender inventory Hausnummer Abgeber Vorrat	cond	text	see above
Postal code Sender inventory Postleitzahl Abgeber Vorrat	cond	text	see above
City Sender inventory Stadt Abgeber Vorrat	cond	text	see above
Country Sender inventory Land Abgeber Vorrat	cond	text	see above
Canton Sender inventory Kanton Abgeber Vorrat	cond	text	see above
Phone number Sender inventory Telefonnummer Abgeber Vorrat	cond	text	see above
Email Sender inventory E-Mail Abgeber Vorrat	cond	text	see above
ID Recipient inventory ID Empfänger Vorrat	cond	text	see above
Type Recipient inventory Typ Empfänger Vorrat
Firstname Recipient inventory Vorname Empfänger Vorrat	cond	text	mandatory if type recipient inventory
Lastname Recipient inventory Nachname Empfänger Vorrat	cond	text	see above
Company name Recipient inventory Firmenname Empfänger Vorrat	cond	text	see above
Street Recipient inventory Straße Empfänger Vorrat	cond	text	see above
House number Recipient inventory Hausnummer Empfänger Vorrat	cond	text	see above
Postal code Recipient inventory Postleitzahl Empfänger Vorrat	cond	text	see above
City Recipient inventory Stadt Empfänger Vorrat	cond	text	see above
Country Recipient inventory Land Empfänger Vorrat	cond	text	see above
Canton Recipient inventory Kanton Empfänger Vorrat	cond	text	see above
Phone number Recipient inventory Telefonnummer Empfänger Vorrat	cond	text	see above
Email Recipient inventory E-Mail Empfänger Vorrat	cond	text	see above
Backup Backup	yes	bool	[TRUE, FALSE]	TRUE if backup address is used
Backup Lastname Backup Nachname	cond	text	mandatory of Backup is set to TRUE	backupToAddress.name
Backup Firstname Backup Vorname	cond	text	see above	backupToAddress.givenName
Backup Birthdate Backup Geburtsdatum	cond	YYYY-MM-DD	see above	backupToAddress.dateOfBirth
Backup Email Backup E-Mail	cond	text	see above	backupToAddress.email
Backup Postalcode Backup Postleitzahl	cond	text	see above	backupToAddress.zip
Backup City Backup Ort	cond	text	see above	backupToAddress.city
Backup Canton Backup Kanton	cond	text	see above	backupToAddress.canton
Backup Phone Backup Telefon	cond	text	see above	backupToAddress.phone