¶ Creating a Waste transportdocument by API
First of all you can find here a complete Json example of a waste transportdocument. Next the Json is split up into different blocks and explained more in detail.
Did you know that when creating a waste transportdocument, an e-Cmr is created simultaneously?
¶ Full example
NOTE ! Do not use this message to post to eWastra. Use your proper company id/externalId, if used (replace "id" : 123 or externalId : "To be configured on the eWastra portal").
{
"properties": {
"documentTypeId": 7
},
"documents": [
{
"documentTypeId": 7,
"countrylayout" : "BE"
},
{
"documentTypeId": 1,
"countrylayout" : "BE"
}
],
"extraProperties": {
"instructions": "Be carefull with load",
"isTest": "True"
},
"company": {
"id": 123,
"externalId": "To be configured on the Xynaps portal"
},
"externalId": "81983fd3-c945-4611-84a0-aa620a3fd371",
"orderNumber": "TEST-89-1635507489",
"dossierNumber": "DOS-1635507489",
"issuedDate": "2021-10-29T09:28:06.789895+00:00",
"issuedPlace": "Beernem",
"orderState": "Draft",
"state": "Draft",
"consignorInstructions": "string",
"consignor": {
"registrationNumbers": {
"OVAM": "123456",
"BRUDALEX": "B123456",
"SPW": "S123456"
},
"address": {
"additionalLine": "",
"streetAddress": "Warehouselaan 234A",
"postalcode": "9000",
"city": "Gent",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapswarehouse.be",
"id": 123,
"name": "Xynaps Warehouse",
"organizationNumber": "AC111.111.113",
"telephoneNumber": "+00 000 00 00"
},
"consignee": {
"registrationNumbers": {
"OVAM": "O-12345611"
},
"address": {
"streetAddress": "Bakkerstraat",
"postalcode": "1000",
"city": "Brussel",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapsbakeries.com",
"id": 349525,
"name": "A.C.M.E. Bakeries",
"organizationNumber": "AC111.111.111",
"telephoneNumber": "+00 000 00 00"
},
"pickup": {
"datetime": "2021-10-5T20:00:00Z",
"id": 123,
"responsibleContact": {
"name": "Eve Middleton",
"mobileNumber": "+31 6 7979979",
"telephoneNumber": "+31 6 7555555",
"emailAddress": "eve@xynapswarehouse.be"
},
"reference": "L- 45678913458",
"extraInformation": {
"openingHoursStart": "05:00",
"openingHoursEnd": "23:00",
"serviceWindowStart": "05:00",
"serviceWindowEnd": "23:00"
},
"address": {
"additionalLine": "",
"streetAddress": "Warehouselaan 234A",
"postalcode": "9000",
"city": "Gent",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapswarehouse.be",
"name": "Xynaps Warehouse",
"organizationNumber": "AC111.111.113",
"telephoneNumber": "+00 000 00 00"
},
"delivery": {
"datetime": "2021-10-5T20:00:00Z",
"id": 349525,
"responsibleContact": {
"name": "Bob Gould",
"mobileNumber": "+32 6 7979979",
"telephoneNumber": "+32 6 7555555"
},
"reference": "U-1578134567814}",
"extraInformation": {
"openingHoursStart": "07:00",
"openingHoursEnd": "22:00",
"serviceWindowStart": "05:00",
"serviceWindowEnd": "23:00"
},
"address": {
"streetAddress": "Bakkerstraat",
"postalcode": "1000",
"city": "Brussel",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapsbakeries.com",
"externalId": "6345",
"license": "555",
"name": "A.C.M.E. Bakeries",
"organizationNumber": "AC111.111.111",
"telephoneNumber": "+00 000 00 00",
"text": "A.C.M.E. Bakeries\r\nBakkerstraat\r\n1000 Brussel\r\nBE"
},
"primaryCarrier": {
"registrationNumbers": {
"OVAM": "123456",
"BRUDALEX": "B123456",
"SPW": "S123456"
},
"address": {
"additionalLine": "",
"streetAddress": "Transportlaan",
"postalcode": "9060",
"city": "Zelzate",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapstransport.be",
"id": 349527,
"name": "A.C.M.E. Transport"
},
"goods": [
{
"packagingDescription": "1 x Rolcontainer >360L <1000L",
"externalId": "01",
"code": "07 01 01*",
"description": "AFVAL, CALFAX DB-45",
"quantity": 1,
"grossWeight": 600.0,
"grossWeightUnit": "kg",
"packagingDetails": [
{
"grossWeight": {
"value": 440.0,
"unit": "kg"
},
"serviceType": "Collect",
"code": "0057",
"description": "Rolcontainer >360L <1000L",
"quantity": 1,
"externalAttributes":
{
"Issuer ref": "Package1 Issuer ref 645644",
"Producer ref": "Package1 Producer ref 1234",
"Carrier ref": "Package1 Carrier ref 5454",
"Treatment operator ref": "Package1 Treatment operator ref 225454",
"Collector ref": "Package1 Collector ref 8787877"
}
},
{
"grossWeight": {
"value": 160.0,
"unit": "kg"
},
"serviceType": "Collect",
"code": "0058",
"description": "Container",
"quantity": 1
}
],
"wasteInfo":
{
"processingNature": "R3",
"processingNatureDescription": "Recyclage/terugwinning van organische stoffen die niet als oplosmiddel worden gebruikt (met inbegrip van compostering en andere biologische omzettingsprocessen)",
"stateOfAggregation": "Vast",
"treatmentTechnique": "Recycleren ..."
},
"externalAttributes":
{
"Issuer ref": "Goods Issuer ref 645644",
"Producer ref": "Goods Producer ref 1234",
"Carrier ref": "Goods Carrier ref 5454",
"Treatment operator ref": "Goods Treatment operator ref 225454",
"Collector ref": "Goods Collector ref 8787877"
}
},
{
"packagingDescription": "1 x Rolcontainer >360L <1000L",
"externalId": "AB-73793",
"code": "06 03 15*",
"description": "AFVAL, F200",
"quantity": 1,
"grossWeight": 440.0,
"grossWeightUnit": "kg",
"packagingDetails": [
{
"grossWeight": {
"value": 440.0,
"unit": "KG"
},
"serviceType": "Exchange",
"externalId": "extid0057",
"code": "0057",
"description": "Rolcontainer >360L <1000L",
"quantity": 1
}
],
"wasteInfo": {
"processingNature": "R3",
"processingNatureDescription": "Rrecyclage/terugwinning van organische stoffen die niet als oplosmiddel worden gebruikt (met inbegrip van compostering en andere biologische omzettingsprocessen)",
"stateOfAggregation": "Vast",
"treatmentTechnique": ""
}
}
],
"consignorDocuments": "Bon de Livraison: 0082116699/n Bon de pesée",
"contacts": [
{
"contact": {
"responsibleContact": {
"name": "Eve Middleton",
"mobileNumber": "+31 6 7979979",
"telephoneNumber": "+31 6 7555555",
"emailAddress": "eve@xynapswarehouse.be"
},
"registrationNumbers": {
"OVAM": "4564646"
},
"address": {
"additionalLine": "",
"streetAddress": "Baron de Maerelaan",
"postalcode": "8380",
"city": "Zeebrugge",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@pionira.be",
"externalId": "PIONIRA",
"license": "123456789",
"name": "PIONIRA NV",
"organizationNumber": "BE0505688120",
"telephoneNumber": "646468486"
},
"role": "Producer"
},
{
"contact": {
"registrationNumbers": {
"OVAM": "123456",
"BRUDALEX": "B123456",
"SPW": "S123456"
},
"address": {
"additionalLine": "",
"streetAddress": "Warehouselaan 234A",
"postalcode": "9000",
"city": "Gent",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapswarehouse.be",
"id": 123,
"name": "Xynaps Warehouse",
"organizationNumber": "AC111.111.113",
"branchNumber": "2.194.100.999"
},
"role": "Collector"
},
{
"contact": {
"address": {
"streetAddress": "Bakkerstraat",
"postalcode": "1000",
"city": "Brussel",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapsbakeries.com",
"externalId": "6345",
"license": "555",
"name": "A.C.M.E. Bakeries",
"telephoneNumber": "+00 000 00 00"
},
"role": "Treatment Operator"
}
],
"transportExecutions": [
{
"driver": {
"carrier": {
"id": 349527
},
"name": "Stefan G",
"id": 487296,
"externalId": "StefanG123456"
},
"truck": {
"id": 480,
"licensePlate": "1-ABC-123"
},
"trailer": {
"id": 481,
"licensePlate": "1-ABC-124"
}
}
],
"eCmr": true
}
¶ Properties
a) Json:
"properties": {
"documentTypeId": 7,
},
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| documentTypeId | Determines the type of document you are creating | Numeric | ||
| referenceNumber | Number attributed by Xynaps to the document with document status 'Planned' | String |
c) Additional information
The documentType of a waste transportdocument is 7.
PROPERTIES WILL BECOME OBSOLETE/DEPRECATED IN THE FUTURE
¶ Documents
a) Json:
"documents": [
{
"documentTypeId": 7,
"countrylayout" : "BE"
},
{
"documentTypeId": 1,
"countrylayout" : "BE"
}
],
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| documentTypeId | Determines the type of document(s) you are creating | Numeric | ||
| countrylayout | Determines the country layout of the document(s) (other codes "FR", "DE", 'EN', ...) | String | ||
| referenceNumber | Number attributed by eWastra to this specific documentTypeId when the document status is 'Planned' | String |
c) Additional information
The documentTypeId of a waste (IDF) transportdocument is 7.
The documentTypeId of a cmr is 1.
A digid (IDF) document can be created without a cmr. Only send documentTypeId = 7
Determining the country layout of the document will be done by using the 'Countrylayout' parameter.
"BE" will for example generate a Belgian (IDF) document.
"FR" will for example generate a French (IDF) document. (Not yet implemented)
"DE" will for example generate a German (IDF) document. (Not yet implemented)
"EN" will for example generate a English (IDF) document. (Not yet implemented)
In this example Json, a digid and cmr report will be generated as Belgian documents.
When the countrylayout is not specified, it is set to "BE" by default
¶ Additional document Properties
a) Json:
"extraProperties": {
"instructions": "Be carefull with load",
"isTest": "True"
},
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| instructions | Special instructions for the transport | string | ||
| isTest | true or false. Indicate if the transport message is a test message or not | boolean |
c) Additional information
The 'instruction' parameter is visable in the APP for the driver.
The purpose of this document parameter 'isTest', is to allow companies to start onboarding their employees and drivers in production, with the necessity to train employees and create transport documents in production with real production data, but without the generation of an official document number.
This means that on the production (or other) environment(s), you can have a mix of specimen and official document numbers for the same document type (Digid, Cmr or others).
This parameter can ONLY be set by API and remeans the same during the whole lifecycle of the document. It is neither a trigger on which environment of Pionira the transport document will be processed.
THE 'isTest' PARAMETER WILL ONLY BECOME AVAILABLE ON PRODUCTION BY BEGINNING SEPTEMBER 2023
¶ Issuer of the document
a) Json:
"company": {
"id": 123,
"externalId": "To be configured on the eWastra portal"
},
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| Id | Internal Id provided by eWastra | Numeric | ||
| ExternalId | Your (sub)company reference | String |
c) Additional information
The issuer of the document is automatically determined by the authentication.
Including the issuer of the document in the Json is only necessary for specific scenarios.
You can find more information here: https://docs.xynaps.net/en/Integrations/Concepts#tree-structured-organizations
¶ General document information
a) Json
"externalId": "81983fd3-c945-4611-84a0-aa620a3fd371",
"orderNumber": "TEST-89-1635507489",
"dossierNumber": "DOS-1635507489",
"issuedDate": "2021-10-29T09:28:06.789895+00:00",
"issuedPlace": "Beernem",
"orderState": "Draft",
"state": "Draft",
"consignorInstructions": "string",
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| ExternalId | Your unique document reference | String | ||
| OrderNumber | Another reference field, must not be unique | String | ||
| DossierNumber | Another reference field, must not be unique | String | ||
| IssuedDate | ISO 8601 notation | String | ||
| IssuedPlace | City | String | ||
| Orderstate | Status of the transport order (Draft, Planned, DriverAssigned, Started, ArrivedAtPickup, NotExecutedAtPickup,DepartedFromPickup, ArrivedAtDelivery, DepartedfromDelivery) | String | ||
| State | Status of the transport document (Draft, Issued, SignedForPickup, SignedForDelivery, Cancelled) Display description Web (Draft, Planned, Loaded, Delivered, Cancelled) | String | ||
| ConsignorInstructions | Instructions for the driver | String | 500 alphanum |
c) Additional information
When leaving issuedDate empty, the current date is automatically taken.
OrderNumber & DossierNumber can be used in the platform and app to search a document.
ExternalID is the reference number of the transport order in the customer's system.Can be used later to address the transport order with other APIs.
OrderState definition :
Order preparation
- Draft : when the transport order is created, 'orderState' will get this status
- Planned : when the carrier is assigned
- DriverAssigned : when a driver is assigned
Pickup of the goods
- Started : when the driver pushes the button 'Started' in the APP. Is optional
- ArrivedAtPickup : when the driver pushes the button 'Arrived' at the pickup location
- NotExecutedAtPickup : when the driver is not able to do the pickup
- DepartedFromPickup : when the signing process at the loading location is finished
Delivery of the goods
- ArrivedAtDelivery : when the driver pushes the button 'Arrived' at the delivery location
- DepartedFromDelivery : when the signing process at the delivery location is finished
Complete document
- Completed : when the status of the document is put on 'Completed' by API call
¶ Contacts general
Be aware that there are two different and fixed ways of defining contacts. They originate from the difference between an e-Cmr and e-DIGID.
| Contact TYPE 1 | Contact TYPE 2 |
|---|---|
| Consignor, Consignee, pickup, delivery and primaryCarrier/successiveCarriers | Producer, Collector and treatment operator |
¶ Contact Type 1 Overview
a) Json:
"Placeholder": {
"registrationNumbers": {
"OVAM": "123456",
"BRUDALEX": "B123456",
"SPW": "S123456"
},
"responsibleContact": {
"emailAddress": "eve@xynapswarehouse.be",
"mobileNumber": "+31 6 7979979",
"name": "Eve Middleton",
"telephoneNumber": "+31 6 7555555"
},
"extraInformation": {
"openingHoursStart": "2021-10-5T20:00:00Z",
"openingHoursEnd": "2021-10-6T06:00:00Z",
},
"address": {
"additionalLine": "",
"streetAddress": "Warehouselaan 234A",
"postalcode": "9000",
"city": "Gent",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapswarehouse.be",
"id": 123,
"externalId": "81983fd3-c975-4611-84a0-aa624233fd371"
"name": "Xynaps Warehouse",
"license": "555",
"organizationNumber": "AC111.111.113",
"branchNumber": "2.194.100.999",
"telephoneNumber": "+00 000 00 00"
},
b) Short description
| Field | Description | Type | Accepted values | |
|---|---|---|---|---|
| Placeholder | Identifies the role of the contact | String | Consignor, Consignee , Pickup, Delivery , PrimaryCarrier/successiveCarriers |
c) Additional information
The placeholder must be replaced to assign the contact to a specific role on the e-Cmr/e-Digid. The roles are: consignor, consignee, pickup, delivery and primarycarrier/successiveCarriers.
There are additional fields provided in case of a pickup or delivery contact as well for a primary carrier or sub carrier contact.
You can find information about these additional fields on this webpage under Pickup/delivery location section and the Primary carrier/successive carrier section.
¶ RegistrationNumbers
a) Json:
"registrationNumbers": {
"OVAM": "123456",
"BRUDALEX": "B123456",
"SPW": "S123456"
},
b) Short description
| Field | Description | Type | Accepted Values | |
|---|---|---|---|---|
| ANY | ANY key value pair can be used here | String | ANY |
c) Additional information
This field is reserved for saving registration numbers. Any key-value pair can be passed and will be visually shown on the IDF. This implies any combination can be used to meet your specific needs.
Basic manipulation of registrationNumbers:
- To add a registrationNumber simply pass an unknown key with corresponding value.
- To update the value of an existing registrationNumber, simply passe the key with his updated value.
- To delete, you must contact Pionira. Deletion is not possible through API nor by using the platform.
RegistrationNumbers show the following characteristics:
- The registrationNumbers can be passed for any contact ( Consignor, pickup location, collector, Primary carrier etc.)
- The registrationNumbers will only be displayed on the IDF for primary carrier and collector
- All registrationNumbers that are passed are stored. This means when creating a transportdocument and leaving the registrationNumbers blank, any known key-value pair will be automatically completed and shown on the IDF. This means deletion can only be done on request.
- In case no registrationNumbers are passed, the license properties is checked, if the license properties has a value, the value will be displayed with the default label OVAM.
- Carriers should still fill in their transport license under the license properties as this value is displayed on the e-Cmr. For other registrationNumbers to be displayed on the IDF, the registrationNumbers can be used.
Reminder:
In case a key-value pairs no longer applies(due to any reason), please contact support@pionira.be for deletion.
Carriers should use both license and registrationNumbers for the e-Cmr and IDF to be correct
¶ ResponsibleContact
a) Json:
"responsibleContact": {
"emailAddress": "eve@xynapswarehouse.be",
"mobileNumber": "+31 6 7979979",
"name": "Eve Middleton",
"telephoneNumber": "+31 6 7555555"
},
b) Short description
| Field | Description | Type | Accepted Values | |
|---|---|---|---|---|
| EmailAddress | emailAddress | String | ANY | |
| MobileNumber | MobileNumber | String | ANY | |
| Name | First and/or Lastname | String | ANY | |
| TelephoneNumber | Landline | String | ANY |
c) Additional information
This information is displayed in the drivers' app(eWastra) for each pickup and delivery contact. It is meant to be a help for the driver, when no person is present on the plant site when loading/unloading.
There is no validation on the provided contact details. What has been passed is going to be displayed.
¶ Extra Information - OpeningHours slot and ServiceWindow slot, for pickup and delivery
a) Json:
"extraInformation": {
"openingHoursStart": "06:00",
"openingHoursEnd": "20:00",
"serviceWindowStart": "06:00",
"serviceWindowEnd": "20:00",
},
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| openingHoursStart | Start Openinghour as free text, for the pickup and/or delivery location | String | ||
| openingHoursEnd | End Openinghour as free text, for the pickup and/or delivery location | String | ||
| serviceWindowStart | Start ServiceWindow as free text, for the pickup and/or delivery location | String | ||
| serviceWindowEnd | End ServiceWindow as free text, for the pickup and/or delivery location | String |
c) Additional information
This information is displayed on the eWastra platform and on the drivers' app (eWastra) only for pickup and delivery contacts.
¶ Address Information
a) Json:
"address": {
"additionalLine": "",
"streetAddress": "Warehouselaan 234A",
"postalcode": "9000",
"city": "Gent",
"countryCode": "BE",
"country": "Belgium"
},
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| AdditionalLine | Extra address entry | String | ||
| StreetAddress | Streetaddress including house number | String | ||
| Postalcode | Postalcode | String | ||
| City | city | String | ||
| CountryCode | ISO 3166 | String | ||
| Country | Additionel field next to the ISO 3166 | String |
c) Additional information
For the countryCode the ISO 3611 convention is used. It is a 2 letter code for identifying a country in a standardized way. More information on this topic can be found here: https://www.iso.org/iso-3166-country-codes.html
¶ Other
a) Json:
"emailAddress": "info@xynapswarehouse.be",
"id": 123,
"externalId": "81983fd3-c975-4611-84a0-aa624233fd371"
"name": "Xynaps Warehouse",
"license": "555",
"organizationNumber": "AC111.111.113",
"branchNumber": "2.194.100.999",
"telephoneNumber": "+00 000 00 00"
b) Short description
| Field | Description | Type | M/D/O | |
|---|---|---|---|---|
| EmailAddress | Email address | String | ||
| Id | Unique reference provide by Pionira | String | ||
| ExternalId | Self chosen unique reference | String | ||
| Name | Company name | String | ||
| License | License | String | ||
| organizationNumber | Organization Number / VAT-number or simular (max length 15) | String | Optional field, when the address is Belgium, it should be a valid number | |
| branchNumber | Branch Number (vestigingsnummer) | String | Optional field, when the address is Belgium, it should be a valid number | |
| telephoneNumber | TelephoneNumber | String |
c) Additional information
By using the ID provided by Xynaps or the self-chosen externalId, you can reference a contact which will ensure all data is completed. A better understanding of its working can be found on the Concepts page.
The email address is an important field if you want to use the email notifications configuration described in administrator paragraph 'Setting-up e-mail alerts'.
In essence, this functionality provides an automated way for sending emails to particular actors based on achieving a certain state (like Draft, Issued, Signed for Pickup, Signed for Delivery, Completed). For example, the consignee receives an email including the e-CMR and/or e-DGID, when it is signed for delivery.
¶ Pickup/delivery location
a) Json:
"Placeholder": {
"datetime": "2021-10-5T20:00:00Z",
"id": 349525,
"responsibleContact": {
"name": "Bob Gould",
"mobileNumber": "+32 6 7979979",
"telephoneNumber": "+32 6 7555555"
},
"reference": "U-8467487213",
"address": {
"streetAddress": "Bakkerstraat",
"postalcode": "1000",
"city": "Brussel",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapsbakeries.com",
"externalId": "6345",
"name": "A.C.M.E. Bakeries",
"organizationNumber": "AC111.111.111",
"branchNumber": "2.194.100.999",
"telephoneNumber": "+00 000 00 00",
"text": "A.C.M.E. Bakeries\r\nBakkerstraat\r\n1000 Brussel\r\nBE"
},
b) Short description
| Field | Description | Type | Accepted values | |
|---|---|---|---|---|
| Placeholder | Identifies either the pickup or delivery | String | Pickup, Delivery | |
| Datetime | ISO 8601 | String | according to ISO 8601 | |
| Reference | pickup/delivery reference | String | ANY |
c) Additional information
ISO 8601 covention to be added
¶ Primary Carrier
a) Json:
"primaryCarrier": {
"registrationNumbers": {
"OVAM": "123456",
"BRUDALEX": "B123456",
"SPW": "S123456"
},
"address": {
"additionalLine": "",
"streetAddress": "Transportlaan",
"postalcode": "9060",
"city": "Zelzate",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@xynapstransport.be",
"id": 349527,
"externalId": "7894654654"
"license": "555",
"name": "A.C.M.E. Transport",
"organizationNumber": "AC111.111.112"
},
b) Short description
| Field | Description | Type |
|---|---|---|
| License | Transportation license issued by government | String |
c) Additional information
¶ Contact Type 2
a) Json:
"contacts": [
{
"contact": {
"responsibleContact": {
"name": "Eve Middleton",
"mobileNumber": "+31 6 7979979",
"telephoneNumber": "+31 6 7555555",
"emailAddress": "eve@xynapswarehouse.be"
},
"registrationNumbers": {
"OVAM": "4564646"
},
"address": {
"additionalLine": "",
"streetAddress": "Baron de Maerelaan",
"postalcode": "8380",
"city": "Zeebrugge",
"countryCode": "BE",
"country": "Belgium"
},
"emailAddress": "info@pionira.be",
"externalId": "PIONIRA",
"license": "123456789",
"name": "PIONIRA NV",
"organizationNumber": "BE0505688120",
"branchNumber": "2.194.100.999",
"telephoneNumber": "646468486"
},
"role": "Collector"
},
b) Short description
| Field | Description | Type | accepted values |
|---|---|---|---|
| Role | The role of the contact | String | Collector, Producer, Treatment Operator |
c) Additional information
The Json here is more or less the same as the type 1 contacts. Just keep in mind to follow the contact list structure and assign a role using the role definition as shown above.
¶ Goods
a) Json:
"goods": [
{
"packagingDescription": "1 x Rolcontainer >360L <1000L",
"externalId": "01",
"code": "07 01 01*",
"description": "AFVAL, CALFAX DB-45",
"quantity": 1,
"grossWeight": 600.0,
"grossWeightUnit": "kg",
"packagingDetails": [
{
"grossWeight": {
"value": 440.0,
"unit": "kg"
},
"serviceType": "Collect",
"externalId": "extid0057",
"code": "0057",
"description": "Rolcontainer >360L <1000L",
"quantity": 1,
"type" : "Packing"
},
{
"grossWeight": {
"value": 160.0,
"unit": "kg"
},
"serviceType": "Collect",
"externalId": "extid0058",
"code": "0058",
"description": "Container",
"quantity": 1,
"type" : "Packing"
}
],
"wasteInfo": {
"processingNature": "R3",
"processingNatureDescription": "Recyclage/terugwinning van organische stoffen die niet als oplosmiddel worden gebruikt (met inbegrip van compostering en andere biologische omzettingsprocessen)",
"stateOfAggregation": "Vast",
"treatmentTechnique": "Recycleren ..."
}
},
{
"packagingDescription": "1 x Rolcontainer >360L <1000L",
"externalId": "AB-73793",
"code": "06 03 15*",
"description": "AFVAL, F200",
"quantity": 1,
"grossWeight": 440.0,
"grossWeightUnit": "kg",
"packagingDetails": [
{
"grossWeight": {
"value": 440.0,
"unit": "KG"
},
"serviceType": "Exchange",
"externalId": "extid0057",
"code": "0057",
"description": "Rolcontainer >360L <1000L",
"quantity": 1,
"type" : "Packing"
}
],
"wasteInfo": {
"processingNature": "R3",
"processingNatureDescription": "Rrecyclage/terugwinning van organische stoffen die niet als oplosmiddel worden gebruikt (met inbegrip van compostering en andere biologische omzettingsprocessen)",
"stateOfAggregation": "Vast",
"treatmentTechnique": ""
}
}
],
c) Additional information
The goods Json is a list that can contain multiple goods lines. The Json code above, contains only one good and needs to be repeated in case of multiple goods.
¶ Main Goods Info
a) Json:
"packagingDescription": "1 x Rolcontainer >360L <1000L",
"externalId": "01",
"code": "07 01 01*",
"description": "AFVAL, CALFAX DB-45",
"quantity": 1,
"grossWeight": 600.0,
"grossWeightUnit": "kg",
b) Short description
| Field | Description | Type | M/D/O |
|---|---|---|---|
| PackagingDescription | Free text | String | |
| ExternalId | Unique reference of the good | String | |
| code | Eural code | String | |
| Description | Eural code in words | String | |
| Quantity | Number of goods | Numeric | |
| Grossweight | The combined weight of all the goods of this type | Numeric | |
| GrossWeightUnit | Unit of measurement | String |
c) Additional information
You either have the option to submit a packagingDescription using the free text field PackagingDescription, or you could opt for a structured manner using the packagingDetails list.
¶ Packagingdetails
a) Json:
"packagingDetails": [
{
"grossWeight": {
"value": 440.0,
"unit": "kg"
},
"serviceType": "Collect",
"externalId": "extid0057",
"code": "0057",
"description": "Rolcontainer >360L <1000L",
"quantity": 1,
"type" : "Packing"
},
b) Short description
| Field | Description | Type | M/D/O | extra info |
|---|---|---|---|---|
| PackagingDescription | List | |||
| Grossweight | List | |||
| Value | weight | Numeric | ||
| Unit | Unit of measure | String | ||
| ServiceType | Servicetype description | String | no limitation nmbr char | |
| ExternalId | Unique reference of the good packaging | String | Mandatory | |
| code | Packaging code | String | Mandatory | |
| Description | Description of the packaging code | String | 50 alphanum | |
| quantity | Package number | Numeric | ||
| type | "Packing" or "OverPacking" | String | Optional | by default, the type will be considered as a 'Packing' line. "OverPacking" is on the same level of a package and is not related to a specific package. |
c) Additional information
The packagingDetails Json is a list that can contain several different types of packaging. This means you can enter multiple packaging types for one good type. The Json code above, contains only one packaging and needs to be repeated in case of multiple packaging types.
"Package" (like number of crates) and "OverPacking" (like number of pallets used to transport these crates) is not nested on the same packaging.
¶ Waste Info
a) Json:
"wasteInfo": {
"processingNature": "R3",
"processingNatureDescription": "Recyclage/terugwinning van organische stoffen die niet als oplosmiddel worden gebruikt (met inbegrip van compostering en andere biologische omzettingsprocessen)",
"stateOfAggregation": "Vast",
"treatmentTechnique": ""
}
b) Short description
| Field | Description | Type | M/D/O |
|---|---|---|---|
| WasteInfo | |||
| ProcessingNature | R/D code | String | M |
| ProcessingNatureDescription | Description | String | |
| StateOfAggregation | / | String | |
| TreatmentTechnique | / | String |
c) Additional information
This information is added on the individual level of a good.
¶ Goods and/or packaging references
For a good or package(s) of a good, it is possible to add 5 different references. These references can contain the goods or package reference of the document issuer, producer, collector, carrier or treatment operator.
a) Json on goods and/or package level:
Example:
"externalAttributes":
{
"Issuer ref": "Goods Issuer ref 645644",
"Producer ref": "Goods Producer ref 1234",
"Carrier ref": "Goods Carrier ref 5454",
"Treatment operator ref": "Goods Treatment operator ref 225454",
"Collector ref": "Goods Collector ref 8787877"
}
"externalAttributes":
{
"Issuer ref": "Package1 Issuer ref 645644",
"Producer ref": "Package1 Producer ref 1234",
"Carrier ref": "Package1 Carrier ref 5454",
"Treatment operator ref": "Package1 Treatment operator ref 225454",
"Collector ref": "Package1 Collector ref 8787877"
}
b) Short description
| Field | Description | Type |
|---|---|---|
| Key | can contain the following keys (Issuer ref, Producer ref, Collector ref, Carrier ref, Treatment operator ref) | List |
| Value | text reference | String |
c) Additional information
| Reference | Visable on CMR/IDF pdf | Show in APP till (before) status loaded (loading process) | Show in APP after loaded (unloading process) |
|---|---|---|---|
| Issuer ref | false | false | false |
| Producer ref | true | true | false |
| Collector ref | true | true | true |
| Treatment operator ref | true | false | true |
| Carrier ref | false | true | true |
These 5 references are not editable in the APP, and can only be managed by Web or API.
¶ TransportExecutions
a) Json:
"transportExecutions": [
{
"driver": {
"carrier": {
"id": 349527
},
"name": "Stefan G",
"id": 487296,
"externalId": "StefanG123456"
},
"truck": {
"id": 480,
"licensePlate": "1-ABC-123"
},
"trailer": {
"id": 481,
"licensePlate": "1-ABC-124"
}
}
],
b) Short description
| Field | Description | Type |
|---|---|---|
| TransportExecutions | List | |
| Driver | ||
| Carrier | ||
| ID | Unique reference provided by Xynaps | String |
| name | Name of the driver | String |
| ID | Unique reference provided by Pionira | Numeric |
| externalId | Unique reference | String |
| Truck | ||
| ID | Unique reference provided by Pionira | Numeric |
| LicensePlate | Licensplate of the Truck | String |
| Trailer | ||
| ID | Unique reference provided by Pionira | Numeric |
| LicensePlate | Licenseplate of the Trailer | String |
c) Additional information
Drivers are created automatically if we find no match in our database.
To determine if the driver already exist we first take the Carrier and then search for a combination of the driver's name and their externalId.
¶ Empties management by API
Below is a short example on how to add empties by API.
In this case there are two different types of empties : europallets & box
Each empty entry contains 5 fields who are all mandatory:
| Field | Description | Type | ||
|---|---|---|---|---|
| ExternalId | Unique reference of the empty type | String | ||
| Code | Short notation of the empty type | String | ||
| Description | full notation of the empty type | String | ||
| Location | Indicates moment of empty | Pickup OR Delivery | ||
| QuantityDelivered | Integer | Numeric | ||
| QuantityReturned | Integer | Numeric |
You should add the code below when you create or update a document using the following API call:
-> {baseurl}/api/v2/transportdocuments
"empties": [
{
"externalId": "de29d8ed-9311-44e6-adc8-c249d5c5d234",
"code": "EUR",
"description": "EUROPALLET",
"location": "Pickup",
"quantityDelivered": 5,
"quantityReturned": 10
},
{
"externalId": "395d69c2-caa5-4299-89e5-b9089f796b55",
"code": "BO",
"description": "box",
"location": "Pickup",
"quantityDelivered": 12,
"quantityReturned": 10
},
{
"externalId": "6c73328b-3a42-45a9-9b9c-74093982dd61",
"code": "BO",
"description": "box",
"location": "Delivery",
"quantityDelivered": 6,
"quantityReturned": 3
},
{
"externalId": "e3640235-d4a4-4d56-b286-27616368b7a1",
"code": "EUR",
"description": "EUROPALLET",
"location": "Delivery",
"quantityDelivered": 10,
"quantityReturned": 2
}
],
On the report it is displayed like this:
¶ Weights collection on product and packaging
Weight measurements can be added on the level of the product or packaging.
It is not possible to add weights on a package with type = "OverPacking".
Each weight measurement entry contains 5 fields:
| Field | Description | Type | ||
|---|---|---|---|---|
| dateTime | Unique reference of the weight | datetime | ||
| location | String | |||
| value | Weight value | numeric | ||
| unit | Unit of measurement (like kg, ton, ...) | String | ||
| type | Weight type (like gross, net, tare, ...) | String | ||
| measurementtype | Type of the measurement (like estimated weight, producer weight and/or mobile weight, weight destinator driver, weight destinator, weight destinator corrected) | String |
None of these fields are mandatory. If 'dateTime' is not used, the system datetime (UTC 0) is used.
A weight measurement has the following json structure :
{
"dateTime": "2021-09-16T10:00:00Z",
"value": 24000,
"unit": "kg",
"type": "gross",
"measurementType": "estimated weight"
}
To add a measurement to a product use the endpoints below containing the above structure as the body of the request :
- POST {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods/{productId}/weights
- POST {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods[{productIndex}].weights
Note : the first productIndex starts with 0
Use the endpoints below to add a measurement on the level of the packaging :
- POST {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods/{productId}/packagingDetails/{packagingId}/weights
- POST {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods[{productIndex}].packagingDetails[{packagingIndex}].weights
Note : the first productIndex and packagingindex starts with 0
The collection of measurements can be retrieved using the endpoints below :
- GET {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods/{productId}/weights
- GET {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods[{productIndex}].weights
- GET {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods/{productId}/packagingDetails/{packagingId}/weights
- GET {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods[{productIndex}].packagingDetails[{packagingIndex}].weights
Note : the first productIndex and packagingindex starts with 0
Some examples :
- The following endpoint can be used to add measurements to a product(goods) :
- POST {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods/{productId}/weights
example : POST https://portal.ewastra.com/api/v2/transportdocuments/800313/goods/208235/weights
result : for transport documentid 800313 and goodsid 208235, the following weight data was added
{
"dateTime": "2021-09-16T10:00:00Z",
"type": "gross",
"measurementType": "estimated weight",
"value": 24000.0,
"unit": "KGM"
}
The following endpoint can be used to retrieve measurements previously add to a product(goods) :
- GET {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods/{productId}/weights
example : GET https://portal.ewastra.com/api/v2/transportdocuments/800313/goods/208235/weights
result : For transport documentid 800313 and goodsid 208235, the following weight data was retrieved
[
{
"dateTime": "2021-09-16T10:00:00Z",
"type": "gross",
"measurementType": "estimated weight",
"value": 24000.0,
"unit": "KGM"
},
{
"dateTime": "2021-09-17T10:00:00Z",
"type": "gross",
"measurementType": "producer weight",
"value": 23750.0,
"unit": "KGM"
}
]
- The following endpoint can be used to add measurements on packaging level, using product and packagingindex :
- POST {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods[{productIndex}].packagingDetails[{packagingIndex}].weights
example : POST https://apps-dev.xynaps.net/api/v2/transportdocuments/800313/goods[0].packagingDetails[0].weights
result : For transport documentid 800313 and the first product and packagingdetail, the following weight data was added
{
"dateTime": "2021-10-28T11:00:00Z",
"value": 24500,
"unit": "KGM",
"type": "net",
"location" : "Containerpark",
"measurementType": "estimated weight"
}
The following endpoint can be used to retrieve measurements previously add to the first product(goods) and packagingdetail :
- GET {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/goods[{productIndex}].packagingDetails[{packagingIndex}].weights
example : GET https://portal.ewastra.com/api/v2/transportdocuments/800313/goods[0].packagingDetails[0].weights
result : For transport documentid 800313 and the first product and packagingdetail, the following weight data was retrieved
[
{
"dateTime": "2021-10-28T11:00:00Z",
"type": "net",
"measurementType": "estimated weight",
"location": "Containerpark",
"value": 24500.0,
"unit": "KGM"
}
]
Flow of the measurementtypes on Web or in the drivers APP.
| DocumentState | MeasurementType | Description Web | Description APP |
|---|---|---|---|
| Planned | estimated weight, producer weight or mobile weight | these 3 measurementtypes can be updated by the document issuer | the driver can manage the producer and/or mobile weight before finalising the signing process at loading location. ('estimated weight' can't be edited by the driver) |
| Loaded | weight destinator or weight destinator driver | the 'weight destinator can be updated by the document issuer | the driver can manage the 'weight destinator driver' before finalising the signing process at the unloading location. ('weight destinator' can't be edited by the driver) |
| Delivered | weight destinator corrected | can be updated by the document issuer | not editable by the driver |
¶ Weight steering at pickup
Sets the desired weight registration measurement type(s) at pickup for the driver to fill in. Providing an empty list of weight registration measurement types will result in no restrictions on the allowed types (mobile weight and producer weight).
Producer weight = the weight measured at the producer by a weighing equipment of the producer.
Mobile weight = the weight measured at the producer by weighing equipment of the collector (in truck weighing system).
To add or retrieve the weight steering measurementtypes with the following endpoints :
- POST {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/pickupWeightSteering
{ "measurementTypes": ["mobile weight", "producer weight"] } - GET {baseUrl}/api/v2/transportdocuments/{transportDocumentId}/pickupWeightSteering
¶ Creating and inviting a contact using the API
¶ Create a contact within your organisation and send an invite mail
A contact of a transport document can be any entity (like pickup/delivery location, carrier, etc....) of a transport document. A contact can be created automatically when it is provided in the transport document, but can also be added separately from a transport document.
The documentation on creating a contact automatically when creating a transport document can be find here https://docs.xynaps.net/en/Integrations/APIHowTo#contacts-general
This example describes how to create a standard contact, independent from a transport document.
In general you have two options, depending on your company processes, either one may work better for you:
- Creating a new contact and immediately send an invite (within the same API-call)
- Create a new contact in one call and send an invite using a second API-call
There are numerous other ways to create/update and receive information of contacts. Consult the full range of the API calls for contacts for more information by clicking this link https://apps-test.xynaps.net/swagger/ui/index and select V2Contacts
Did you know you can also import a large number of contacts in one API-call using the batch functionality?
Example of an API call to create the contact and send the invite : POST {baseUrl}/api/v2/contacts
{
"registrationNumbers": {
"OVAM" : "OVAM123456",
"Brudalex" : "B123456",
"SPW": "S123456"
},
"responsibleContact": {
"emailAddress": "support@pionira.be",
"mobileNumber": "+32000000",
"name": "support",
"telephoneNumber": "+32000000"
},
"extraInformation": {},
"address": {
"streetAddress": "Street 12 bus 8",
"postalcode": "1000",
"city": "Brussel",
"countryCode": "BE",
"externalId": "adres1",
"additionalLine": "string",
"country": "Belgium"
},
"collaborationSettings": {
"emailAddress": "support@pionira.be",
"contactName": "support",
"message": "Please accept this invite"
},
"emailAddress": "support@pionira.be",
"externalId": "contactextid1",
"faxNumber": "+3200000000",
"license": "1235444",
"mobileNumber": "+320000000",
"name": "Support",
"organizationNumber": "1236542",
"branchNumber": "2.194.100.999",
"telephoneNumber": "+320000000"
}
¶ RegistrationNumbers
a) Json:
"registrationNumbers": {
"OVAM": "OVAM123456",
"BRUDALEX": "B123456",
"SPW": "S123456"
},
b) Short description
| Field | Description | Type | Accepted Values | |
|---|---|---|---|---|
| ANY | ANY key value pair can be used here | String | ANY |
c) Additional information
This field is reserved for saving registration numbers. Any key-value pair can be passed and wil be visually shown on the IDF. This means any combination can be used to meet your specific needs.
Basic adjustments of registrationNumbers:
- To add a registrationNumber simply pass an unknown key with corresponding value
- To update the value of an existing registrationNumber, simply pass the key with his updated value.
- To delete, you must contact Pionira. Deletion is not possible through API nor by using the platform.
RegistrationNumbers show the following characteristics:
- The registrationNumbers can be passed for any contact ( Consignor, pickup location, collector, Primary carrier etc.)
- The registrationNumbers will only be displayed on the IDF for primary carrier and collector
- All registrationNumbers that are passed are stored. This means when creating a transportdocument and leaving the registrationNumbers blanc, any known key-value pair will be automatically completed and shown on the IDF. This implicates deletion can only be done on request.
- In case no registrationNumbers are passed, the license properties is checked, if the license properties has a value, the value will be displayed with the default label OVAM.
Reminder:
In case a key-value pairs no longer applies (for to any reason), please contact support@pionira.be for deletion.
¶ ResponsibleContact
a) Json:
"responsibleContact": {
"emailAddress": "support@pionira.be",
"mobileNumber": "+32000000",
"name": "support",
"telephoneNumber": "+32000000"
},
b) Short description
| Field | Description | Type | Accepted Values | |
|---|---|---|---|---|
| EmailAddress | emailAddress | String | ANY | |
| MobileNumber | MobileNumber | String | ANY | |
| Name | First and/or Lastname | String | ANY | |
| TelephoneNumber | Landline | String | ANY |
c) Additional information
There is no validation on the provided contact details. What has been passed is going to be displayed.
¶ Address Information
a) Json:
"address": {
"streetAddress": "Street 12 bus 8",
"postalcode": "1000",
"city": "Brussel",
"countryCode": "BE",
"externalId": "adres1",
"additionalLine": "string",
"country": "Belgium"
},
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| StreetAddress | Streetaddress including house number | String | ||
| Postalcode | Postalcode | String | ||
| City | city | String | ||
| CountryCode | ISO 3166 | String | ||
| External id | externalid of the address | String | ||
| AdditionalLine | Extra address entry | String | ||
| Country | Additionel field next to the ISO 3166 | String |
c) Additional information
Multiple address can be added for 1 contact.
For the countryCode the ISO 3611 convention is used. It is a 2 lettre code for identifying a country in a standarized way. More information on this topic can be found here: https://www.iso.org/iso-3166-country-codes.html
¶ Collaboration Settings
a) Json:
"collaborationSettings": {
"emailAddress": "support@pionira.be",
"contactName": "support",
"message": "Please accept this invite"
},
b) Short description
| Field | Description | Type | ||
|---|---|---|---|---|
| emailaddress | mailaddress of the contact | String | ||
| ContactName | Name | String | ||
| Message | an additional message that will be displayed in the invitation mail | String |
c) Additional information
This part is used to send an invitation to this contact (user or organisation).
The setting of the Collaborate property indicates whether you want to set up or tear down collaborative sharing with this party. If true, the collaborative connection will be set up by sending an e-mail to the e-mail address supplied by the emailAddress property in this object
When the receiver accepts the invite, your contact will be linked to their user or organisation.
To a specific contact the connection mail can only be sent once. This means, when performing multiple API-calls containing the connection request, only the first time the email will be send, all subsequent request will be ignored.
Be aware that when the connection has already been sent, the call will return value '200', however no new invitation will be sende.
¶ Other general contact information
a) Json:
"emailAddress": "support@pionira.be",
"externalId": "contactextid1",
"faxNumber": "+3200000000",
"license": "1235444",
"mobileNumber": "+320000000",
"name": "Support",
"organizationNumber": "1236542",
"branchNumber": "2.194.100.999",
"telephoneNumber": "+320000000"
b) Short description
| Field | Description | Type | M/D/O | |
|---|---|---|---|---|
| EmailAddress | emailAddress | String | ||
| externalid | external reference (from the user's system) | String | ||
| faxnumber | String | |||
| license | if applicable | String | ||
| MobileNumber | MobileNumber | String | ||
| Name | First and/or Lastname | String | ||
| organisationNumber | String | |||
| branchNumber | Branch number (vestigingsnummer) | String | Optional field, for a Belgium address, it should be valid data | |
| TelephoneNumber | Landline | String |
c) Additional information
This part describes the general information that can be used for your contact.
General notes : Link/reference to the Xynaps portal contact user interface
- Filenumber is the externalid field in the API
- Application Name is not used in the API
- Carrier checkbox is not available in the API, but will be added
- DUNS/EORI numbers need to be added in the AOI under registrationnumbers
¶ Send an invite mail via API
When you already have existing contacts in your organisation, which are not yet linked to other external users/organisations, you have the possibility to send an invite by using the Xynaps portal user interface (click on the 'connect' button of your contact) or you can send the invite by using this API call. This can be done by using the Xynaps contact id or your external contact id.
Example of an API call to send the invite with Xynaps contact id: PUT {baseUrl}/api/v2/contacts/{id}/connect
For example, replacing {id} by 1234, an invite will be sent to the emailaddress of contact id 1234.
¶ Collaboration Settings
a) Json:
{
"emailAddress": "support@pionira.be",
"contactName": "support",
"message": "Please accept this invite"
}
b) Short description
See previously described.
c) Additional information
See previously described.
A mail notification will only be sent when the invite has not yet been accepted.
When the connected has already been accepted, the call will return value '200', but no specific return code for the moment.
¶ Sign transport document by API
A transport document can be signed by API call for he following roles :
- CONSIGNOR
- CONSIGNEE
- PRODUCER
- COLLECTOR
- TREATMENT OPERATOR
The document(s) will be singed as the organization who is authorized when performing the API-call. Should you want to sign in name of one of your suborganizations, you can add the company object.
The driver signature can only be set using eWastra APP, using the signoff call for the driver signature is not possible.
Example of an API call to sign a transport document as the consignor : POST {{baseUrl}}/api/v2/transportdocuments/{{documentId}}/signoff
{
"signatory": {
"name": "John Doe",
"role": "COLLECTOR"
"company":{
"id":45654,
"externalId":"eirupzid"
}
}
}
Consignor or Consignee sign options are for the e-cmr document.
Producer, Collector and Treatment Operator are for the e-digid document.
¶ Managing fleet information (Vehicles and drivers) by API
Fleet information, like drivers and vehicles, can be managed by the API interface.
Updating a transport document with driver and vehicle information is descriped in this paragraph.
¶ Vehicle information
Vehicle information has the following json structure :
{
"externalId": "truck2",
"licensePlate": "truck2",
"name": "truck2",
"truckloadCapacity": {
"value": 22,
"unit": "ton"
},
"truckloadVolume": {
"value": 50,
"unit": "cubic meters"
}
}
| Field | Description | Type | ||
|---|---|---|---|---|
| externalid | external reference of the vehicle | String | ||
| licenseplate | String | |||
| name | Name of the vehicle | String | ||
| truckloadcapacity | ||||
| value | Numeric | |||
| unit | String | |||
| truckloadvolume | ||||
| value | numeric | |||
| unit | String |
Not all the above information is visable in the Xynaps portal (such as truckload information).
Some extra information that can be added in the Xynaps portal can also be retrieved by using the following API call:
GET {baseUrl}/api/v2/fleet/transportmeans/{id}
example : GET {baseUrl}/api/v2/fleet/transportmeans/1328
{
"DisplayName": "truck2",
"LicensePlate": "TRUCKT2",
"Model": "DAF",
"OrganisationId": 487971,
"TypeId": 0,
"TypeName": "None",
"Id": 1328,
"Year": 2020,
"ExternalId": "truck2"
}
| Field | Description | Type | ||
|---|---|---|---|---|
| Displayname | name of the vehicle | String | ||
| licenseplate | String | |||
| Model | vehicle model | String | ||
| organisationid | internal xynaps reference of the organisation | numeric | ||
| type | 0=no type attributed,1=Truck,2=Barge,3=Car,4=Trailer,5=Tankcontainer,7=Tanktrailer | Numeric | ||
| typename | String | |||
| id | Internal Xynaps id of the vehicle | numeric | ||
| year | numeric | |||
| externalid | external reference of the vehicle | String |
Various API calls are possible. For the full API reference on Vehicles, see also API reference (Vehicles section)
¶ Driver information
Driver information has the following json structure :
{
"emailAddress": "support@pionira.be",
"ExternalId": "support",
"GivenName": "test",
"mobileNumber": "+0032000000001",
"password": "String12345!",
"Surname": "support",
"telephoneNumber": "+0032000000002",
"UserName": "testsupport"
}
| Field | Description | Type | ||
|---|---|---|---|---|
| EmailAddress | emailAddress | String | ||
| externalid | external reference | String | ||
| Givenname | first name | String | ||
| MobileNumber | MobileNumber | String | ||
| password | a password can be assigned, but is not mandatory | String | ||
| SurName | Last name | String | ||
| TelephoneNumber | Landline | String | ||
| UserName | Name of the user. Used to access the eWastra portal and/or the Digicmr App | String |
When you add a driver, they will automatically be visible as a user in your organisation with the role 'Driver'.
Various API calls are possible. For the full API reference on Drivers, see also API reference (Drivers section)
The most commonly used calls:
For adding a driver : POST {baseUrl}/v2/fleet/drivers
{
"emailAddress": "support@pionira.be",
"ExternalId": "support",
"GivenName": "test",
"mobileNumber": "+0032000000001",
"password": "String12345!",
"Surname": "support",
"telephoneNumber": "+0032000000002",
"UserName": "testsupport"
}
Get all information of a driver : GET {baseUrl}/v2/fleet/drivers/{id}
Where {id} is the eWastra internal reference for the driver.
example : GET {baseUrl}/v2/fleet/drivers/123456
result :
{
"emailAddress": "support@pionira.be",
"ExternalId": "support",
"GivenName": "test",
"mobileNumber": "+0032000000001",
"Surname": "support",
"telephoneNumber": "+0032000000002",
"UserName": "testsupport"
}
Update information of a driver : PUT {baseUrl}/v2/fleet/drivers/
{
"telephoneNumber": "+0032000000005",
"UserName": "testsupport"
}
Creating Drivers in batch
Drivers can be created in batch, meaning that with 1 api call, multiple drivers can be created.
For adding a multiple drivers in batch : POST {baseUrl}/v2/fleet/drivers/batch
[
{
"emailAddress": "{{$randomEmail}}",
"ExternalId": "{{$guid}}",
"GivenName": "Driver1",
"mobileNumber": "04710000",
"password": "Driver12345!!",
"Surname": "FLEET",
"telephoneNumber": "502874962",
"UserName": "Driver1"
},
{
"emailAddress": "{{$randomEmail}}",
"ExternalId": "{{$guid}}",
"GivenName": "Driver2",
"mobileNumber": "048800011",
"password": "Driver22345!!",
"Surname": "FLEET",
"telephoneNumber": "502874962",
"UserName": "Driver2"
}
]
Authentication to create drivers within an organisation, can be done with OAuth 2.0 by using 'Client credentials' or 'Authorisation code grant' methods.
¶ Updating a transport document with carrier/subcontractor/driver/vehicle information
¶ Updating a transport document with carrier/subcontractor information
It is possible to update a transport document with the carrier information.
example of updating a transport document : PUT {baseUrl}/api/v2/transportdocuments/{id}/carriers/{contactrole}
Where {id} is the Xynaps internal transport document reference and {contactrole} is the primary carrier or sub contractor.....
Simple example for adding the primary carrier : PUT {baseUrl}/api/v2/transportdocuments/12345/carriers/primaryCarrier
{
"id": 12344
}
By doing this call, the existing primary carrier with eWastra id 12344, will be added to eWastra document id 12345.
Simple example for adding a sub contractor : PUT {baseUrl}/api/v2/transportdocuments/12345/carriers/subContractor
{
"id": 1234411
}
By doing this call, the existing sub contractor (subCarrier) with eWastra id 1234411, will be added to eWastra document id 12345.
The externalid of the carrier/subcontractor can also be used to add the primary carrier or subcontractor to the transport document.
A new carrier or subcontractor can also be created and added to the transport document when using this API call.
| Field | Description | Type | ||
|---|---|---|---|---|
| isSuccessiveCarrier | true or false | boolean | ||
| licensePlate | Do not use here | String | ||
| trailerLicensePlate | Do not use here | String | ||
| registrationNumbers, responsibleContact, address, collaborationSettings and other contact information | see https://docs.xynaps.net/en/Integrations/APIHowTo#creating-and-inviting-a-contact-using-the-api |
For the full description of the PUT API call, see also our API reference (Transportdocuments - carriers section)
¶ Updating a transport document with driver/vehicle information
It is possible to update a transport document with driver and vehicle information.
A frequently used update of the transport document is assigning a driver to that document once the carrier is known, together with the license plate of the truck and/or trailer.
example of updating a transport document : PUT {baseUrl}/api/v2/transportdocuments/{id}/driver
Where {id} is the eWastra internal transport document reference.
{
"driver": {
"carrier": {
"id": 0,
"externalId": "string"
},
"name": "string",
"id": 0,
"externalId": "string"
},
"truck": {
"externalId": "string",
"id": 0,
"licensePlate": "string",
"name": "string"
},
"trailer": {
"externalId": "string",
"id": 0,
"licensePlate": "string",
"name": "string"
},
}
| Field | Description | Type | ||
|---|---|---|---|---|
| driver | ||||
| carrier | ||||
| id | eWastra reference of the carrier | Numeric | ||
| externalid | external reference of the carrier | String | ||
| name | name of the driver | String | ||
| id | eWastra reference of the carrier | Numeric | ||
| truck | ||||
| externalid | external reference of the truck | String | ||
| id | eWastra reference of the truck | Numeric | ||
| licensePlate | Licenseplate of the truck | String | ||
| Name | Name of the truck | String | ||
| trailer | ||||
| externalid | external reference of the trailer | String | ||
| id | eWastra reference | Numeric | ||
| licensePlate | Licenseplate of the trailer | String | ||
| Name | Name of the trailer | String |
For the full description of the PUT API call, see also API reference (Transportdocuments - Driver section)
¶ Updating the delivery locations of a transport document, between the signing for pickup and signing for delivery steps
DOCUMENTATION IN PROGRESS.
The business case when this functionality can be used by the transport planner or its backoffice system, is that after the loading process, the delivery locations of the document need to be changed.
Using this specific change button (Update delivery locations) on the WEB or via an API-call, it is possible to update the Treatment Operator and/or Delivery location on a transport order. The change will only be possible if the document is signedforpickup and not yet signedfordelivery.
If these conditions are met, after the change, the Digid pdf is automatically recreated, and visable on the WEB and on the APP of the driver. On the IDF pdf, the changed Treatment Operator is visable. And in the addendum page(s) of the Digid pdf, the Treatment Operator is visable from the previous value and the new value.
If the waste document is originally created with the option to also create the cmr document, after each change, a new cmr pdf (numbered .._1, .._2, etc) is created.
What is changed on the new cmr pdf :
The previous cmr number is added together with a new cmr number.
The new Recipient (name, address, State) is added in BOX 2 on the cmr pdf
The new Delivery (place, State, date/time) is added in BOX 4 on the cmr pdf
All other information (like signature BOX 14 and 15) is kept from the previous cmr pdf.
All cmr pdf's linked to the waste document, are visable on the WEB and in the APP of the driver.
After signing for delivery, the signature for the 'Treatment Operator' is on the IDF pdf. For a waste document, with and e-cmr, the latest cmr pdf will contain a signature in BOX 16.
example of such an update : PUT {baseUrl}/api/v2/transportdocuments/{id}/delivery/change
Where {id} is the eWastra internal transport document reference.
{
"treatmentOperator": {
"registrationNumbers": {
"OVAM": "OVAMTEST"
},
"address": {
"streetAddress": "straat 1",
"postalcode": "9999",
"city": "Damme",
"countryCode": "BE"
},
"emailAddress": "nieuweverwerker@emailupdate.be",
"externalId": "Nieuwe verwerker 1",
"name": "Nieuwe verwerker 1 name",
"organizationNumber": "BE123456789",
"telephoneNumber": "0455889966"
},
"deliveryLocation": {
"registrationNumbers": {
"test reg nmbr key": "Nieuwe los locatie"
},
"extraInformation": {
"test extra info key": "Nieuwe los locatie extra info",
"openingHoursStart": "13:13",
"openingHoursEnd": "14:14",
"serviceWindowStart": "11:11",
"serviceWindowEnd": "12:12"
},
"address": {
"streetAddress": "Petegemplein 3, bus 3",
"postalcode": "9790",
"city": "Petegem-aan-de-Schelde",
"countryCode": "BE"
},
"datetime": "2023-06-28T12:26:00",/* is mandatory */
"emailAddress": "nieuweloslocatie@deliveryupdate.be",
"externalId": "Nieuwe los locatie 3",
"name": "Nieuwe los locatie 3",
"organizationNumber": "BE555666999",
"telephoneNumber": "0477885522",
"reference": "Nieuwe los locatie 3 reference"
},
"consignee": {
"address": {
"streetAddress": "Petegemplein 4, bus 4",
"postalcode": "9790",
"city": "Petegem-aan-de-Schelde",
"countryCode": "BE"
},
"emailAddress": "Nieuwe los locatie 4@deliveryupdate.be",
"externalId": "Nieuwe los locatie 4",
"name": "Nieuwe los locatie 4",
"branchNumber": "branch",
"organizationNumber": "BE555666999",
"telephoneNumber": "0477885522"
}
}
¶ ADR - Updating a transport document with ADR information, between the signing for pickup and signing for delivery steps
Using this specific change button (Update ADR) on the WEB or via an API-call, it is possible to update the ADR information of goods, on a transport order. The change will only be possible if the document is signedforpickup and not yet signedfordelivery.
If these conditions are met, after the change, the Digid/CMR pdf is automatically recreated, and visable on the WEB and on the APP of the driver. On the IDF pdf, the updated ADR information is visable on the good(d). And in the addendum page(s) of the Digid pdf, the ADR information is visable from the previous values and the new values.
example of such an update : PUT {baseUrl}/api/v2/transportdocuments/{id}/goods/dangerousGoodsDescription/change
Where {id} is the eWastra internal transport document reference.
[
{
"productId": 1009711,
"dangerousGoodsDescriptions": [
{
"language": "nl",
"description": {
"adrDescription": "UN 1230, afvalstof, methanol, 3,(6.1), II (D/E)",
"environmentallyHazardous": "Milieugevaarlijk 1",
"specialProvisions": "131 De geflegmatiseerde stof moet beduidend minder gevoelig zijn dan droog PETN",
"specialProvisionsForCarriage": "vervoer volgens 4.1.10",
"carriageUnderDerogation": "vervallen stoffen – 1-malig verplaatsen van A naar B Verwijzing naar Multilaterale akkoorden"
}
},
{
"language": "fr",
"description": {
"adrDescription": "UN 1230, déchets, méthanol, 3,(6.1), II (D/E)",
"environmentallyHazardous": "Dangereux pour l'environnement 2",
"specialProvisions": "131 Le tissu flegmatisé devrait être nettement moins sensible que le PETN",
"specialProvisionsForCarriage": "transport selon 4.1.10",
"carriageUnderDerogation": "substances périmées – transférer une fois de A à B. Référence aux accords multilatéraux"
}
},
{
"language": "de",
"description": {
"adrDescription": "UN 1230, déchets, méthanol, 3,(6.1), II (D/E)",
"environmentallyHazardous": "Dangereux pour l'environnement",
"specialProvisions": "131 Le tissu flegmatisé devrait être nettement moins sensible que le PETN sec testde",
"specialProvisionsForCarriage": "transport selon 4.1.10 testde",
"carriageUnderDerogation": "substances périmées – transférer une fois de A à B. Référence aux accords multilatéraux"
}
}
]
}
]
NOTE : Do not use 'dangerousGoodsInfo' (customer specific).