Introduction
Systems Involved
- TOTVS Otimização Logística / TOTVS Roteirização e Entrega
- External System: ERPs that connect or intend to connect with TOL/TRE
Scope
Installation/Deployment/Usage Prerequisites
Minimum versions
- TOL/TRE: 6.4.0
- Protheus: ?
- Datasul: ?
- This integration requires no additional installations or updates.
Requisition Layout
createOrders/updateOrders/deleteOrders: SOAP Integration, Synchronous | |||||
---|---|---|---|---|---|
Name | Type | Mandatory | Size | Description | Observation |
regionSourceId | String | Yes | 30 | Regional identifier; | Must be a valid regional; |
identifier (order) | String | Yes | 30 | transport order ID; | The transport order ID must be unique per shipper; |
code | String | Yes | 255 | Transport order code ("description" of the transport order); | Does not exist in TRE (R2); |
shipperId | String | Yes | 255 | Shipper ID; | Does not exist in TRE (R2); This field must be from a valid shipper; |
orderTypeSourceId | String | Yes | 30 | Order type code; | This field must be the sourceId of a valid order type; |
orderSubTypeSourceId | String | No | 30 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively, use an order classification. |
priority | Inteiro | Yes | 2 | Transport request priority; | Does not exist in TRE (R2); This field must be a number between 0 and 10; the higher the number, the higher the priority; |
pickupStart | Date/hour (String) | Yes | 29 | Start date/time of departure window; | PickupStart must always be less than deliveryEnd; pickupStart must always be less than pickupEnd (when this is informed); When there is no time in the external system, always send 00:01 start of the day; |
pickupEnd | Date/hour (String) | No | 29 | End date/time of boarding window; | PickupEnd (when informed) must always be less than or equal to deliveryEnd; |
deliveryStart | Date/hour (String) | No | 29 | Delivery window start date/time; | DeliveryStart (when informed) must always be less than or equal to deliveryEnd; When there is no time in the external system, always send 23:59 end of the day; |
deliveryEnd | Date/hour (String) | Yes | 29 | End date/time of the delivery window; | |
billingLimit | Date/hour (String) | No | 29 | Deadline date/time for billing; | Does not exist in TRE (R2); |
destinationId | String | Yes | 30 | Transport order destination locality ID (main delivery address); | The informed locality must have the logistical role of "destination" or "both" (It cannot be just "origin"); if the delivery address to be considered is the alternative one, a "dummy" code can be sent in this field (this only applies to the transport order creation operation); |
addressCountryAcronym | String | No | 2 | Acronym of the country of the transport request (alternative delivery address); | It must be a valid acronym; If zip code is not informed, this field is mandatory; |
addressStateAcronym | String | No | 2 | Acronym of the status of the transport order (alternative delivery address); | It must be a valid acronym; If zip code is not informed, this field is mandatory; |
addressCity | String | No | 50 | City of transport request (alternative delivery address); | If zip code is not informed, this field is mandatory; |
addressDistrict | String | No | 50 | District of the transportation request (alternative delivery address); | |
addressStreet | String | No | 200 | Transport order Street (alternative delivery address); | |
addressNumber | String | No | 30 | Transport order number (alternative delivery address); | |
addressComplement | String | No | 30 | Complement of the transport order address (alternative delivery address); | |
addressZipCode | String | No | 10 | Zip code of the transport order address (alternative delivery address); | The value cannot be invalid; if the state and city are not informed, this field is mandatory; |
addressLatitude | Float | No | 13 | Latitude of the transportation request (alternative delivery address); | If this field is provided, the longitude of the locality must also be provided; the value of this field must be in the range -90.0 to 90.0; Observations:- The TOL/TRE can be configured to allow the automatic geocoding of the localitys in the integration; if this behavior is enabled, the geo-coordinates will be obtained automatically via a GIS service during the acquisition process itself; |
addressLongitude | Float | No | 13 | Longitude of the transportation request (alternative delivery address); | If this field is provided, the latitude of the locality must also be provided; the value of this field must be in the range -180.0 to 180.0; Observations:- The TOL/TRE can be configured to allow the automatic geocoding of the localitys in the integration; if this behavior is enabled, the geo-coordinates will be obtained automatically via a GIS service during the acquisition process itself; |
integrationDataSource | String | Yes | 30 | data source ID; | Does not exist in TRE (R2); This field must be from a valid data source; |
modal | Inteiro | No | 1 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively, use an order classification. |
passingHubUsageType | String | No | 10 | Type of use of the pass-through hub; | Does not exist in TRE (R2); MANDATORY / OPTIONAL/ INVALID |
possiblePassingHubsIds | Lista <String> | No | 30 | List of branch IDs of localitys that can be pass-through hubs; | Does not exist in TRE (R2); This field should have a list of branch IDs from localitys that are valid gateway hubs; |
destinationHubUsageType | String | No | 10 | Type of use of the destination hub; | Does not exist in TRE (R2); MANDATORY / OPTIONAL/ INVALID |
possibleDestinationHubsIds | Lista <String> | No | 30 | List of locality branch IDs that can be destination hubs; | Does not exist in TRE (R2); This field should have a list of branch IDs from localitys that are valid destination hubs; |
allowedVehicleIds | Lista <String> | No | 255 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); There is no default alternative. Each case will be assessed individually. |
forbiddenVehicleIds | Lista <String> | No | 255 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); There is no default alternative. Each case will be assessed individually. |
deliveryExclusivity | Boolean | No | 1 | Flag indicating if the order is for exclusive delivery; | Does not exist in TRE (R2); If an order has this flag checked, trips will be assembled in such a way that only orders from the same customer of this order will be grouped in the same load; Example: suppose the following requests: Comments: |
incoterm | Inteiro | No | 1 | Incoterm of the transportation request; | Does not exist in TRE (R2); 0=FOB; 1=CIF; 2=FOBT; 3=OP |
erpCreationDt | Date/hour (String) | No | 29 | Date of creation of the transport request in the external system; | Does not exist in TRE (R2); This field's requirement may vary by shipper (OrderSysParams parameters); |
reference (order) | String | No | 500 | Free text field; | |
observations | String | No | 500 | Free text field; | |
auxiliary1 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary2 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary3 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary4 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary5 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary6 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary7 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary8 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary9 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); Alternatively use a request attribute. |
auxiliary10 | String | No | 500 | Do not use. It will be removed in future releases. | Does not exist in TRE (R2); |
classifications | classifications [] | No | N/A | Grouping element of all classifications of an order; | |
attributes | attributes[] | No | N/A | Grouping element of all the attributes of an order; | |
items | orderitem[] | Yes | N/A | Grouping element of all items of an order; | |
deliveryUnits | deliveryUnit[] | No | N/A | Grouping element of all delivery units of an order; | Does not exist in TRE (R2); |
orderitem, data type used in TOL/TRE integrations | |||||
---|---|---|---|---|---|
Name | Type | Mandatory | Size | Description | Observation |
orderId | String | Yes | 30 | transport order ID; | Same value as the identifier field (order); |
sourceId | String | Yes | 30 | Transport order item ID; | Order item list Cannot contain repeating sourceIds; the sourceId will uniquely identify the item of an order; the sourceId of an item Cannot be repeated even between other requests; |
orderItemClassificationSourceId | String | No | 30 | Do not use. It will be removed in future releases. | Alternatively, use an order item classification. |
productId | String | Yes | 30 | ID do SKU; | This field must be from a valid SKU; if the palletization parameter in the order is enabled and the destination locality supports palletization, this SKU must have an associated pallet already defined; |
originId | String | Yes | 30 | ID of the place of origin of the order item; | This field must be from a valid locality, must have the logistical role of "origin" and must be different from the destination locality of the transport request (see field "destinationId"); |
proportionalityId | String | No | 255 | proportionality key | Indicator of which products must be kept in the same proportion within a load (example: 1 pot = 1 lid + 1 bottle); SKUs that must have this proportionality respected must have the same value in this field; |
shipmentUnitWrapperCode | String | Yes | 30 | Shipping unit enclosure code; | This field must be from a valid UE wrapper sourceId and cannot be a composite wrapper. |
price | Float | No | 13 | Total value of product units in all shipment units of this item; | Scenario 1: Shipping Wrap is per product; This field will be "overwritten" by the respective value registered in the product; Scenario 2: Shipping Wrap is per item; The value informed in the item will be used; |
height | Float | No | 13 | Height of shipping envelope (unit); | Scenario 1: Shipping Wrap is per product; Scenario 2: Shipping Wrap is per item; |
length | Float | No | 13 | Length of shipping envelope (unit); | Scenario 1: Shipping Wrap is per product; Scenario 2: Shipping Wrap is per item; |
width | Float | No | 13 | Width of the shipping envelope (unit); | Scenario 1: Shipping Wrap is per product; Scenario 2: Shipping Wrap is per item; |
weight | Float | No | 13 | Weight of the shipping envelope (unit); | Scenario 1: Shipping Wrap is per product; Scenario 2: Shipping Wrap is per item; |
volume | Float | No | 13 | Do not use. It will be removed in future releases. | Not necessary. The system will calculate the volume automatically based on the dimensions and enclosure of the shipping unit. |
quantity | Float | Yes | 13 | Total quantity of product units in all shipment units of this item; | This field must be greater than zero; if the container category is not of the "non-unitizable bulk" type, this field must have an integer value; |
quantityInShipmentUnits | Float | Yes | 13 | Number of shipping units; | This field must be greater than zero; if the enclosure category is of the "bundle of tubes" type, the division of "quantity" by this field must not leave a remainder (i.e., the "quantity" field must be divisible by this field); if the container category is of the "pallet" type, and the system is not enabled to work with fractional shipment units (UE), this field must have an integer value; |
palletFractionationForbidden | Boolean | No | 1 | Do not use. It will be removed in future releases. | Alternatively, use an order item classification. |
hlwAllow | Boolean | No | 1 | Flag indicating whether the shipping envelope can be tipped in the ACL orientation; | A=Height; L=Width; C=Length; see possible orientations of a SKU; a shipping envelope cannot be tipped in all its orientations; |
hwlAllow | Boolean | No | 1 | Flag indicating whether the shipping envelope can be overturned in the ALC orientation; | A=Height; L=Width; C=Length; see possible orientations of a SKU; a shipping envelope cannot be tipped in all its orientations; |
lhwAllow | Boolean | No | 1 | Flag indicating whether the shipping envelope can be tipped in the CAL orientation; | A=Height; L=Width; C=Length; see possible orientations of a SKU; a shipping envelope cannot be tipped in all its orientations; |
lwhAllow | Boolean | No | 1 | Flag indicating whether the shipping envelope can be tipped in the CLA orientation; | A=Height; L=Width; C=Length; see possible orientations of a SKU; a shipping envelope cannot be tipped in all its orientations; |
whlAllow | Boolean | No | 1 | Flag indicating whether the shipping envelope can be overturned in the LAC orientation; | A=Height; L=Width; C=Length; see possible orientations of a SKU; a shipping envelope cannot be tipped in all its orientations; |
wlhAllow | Boolean | No | 1 | Flag indicating whether the shipping envelope can be tipped in the LCA orientation; | A=Height; L=Width; C=Length; see possible orientations of a SKU; a shipping envelope cannot be tipped in all its orientations; |
MIT | String | No | 50 | "Merge in Transit"; | Order items that have the same MIT will be transported in the same cargo; order items that have different MITs may be transported in the same cargo; this restriction is applied only in the last leg of the "web" (i.e., when the actual delivery to the customer will be made); if DSK is provided, order items with the same DSK must have the same MITs, which in turn must be different from all other order items' MITs; |
DSK | String | No | 50 | "Delivery Schedule Key"; | Order items that have the same DSK will be transported in the same load; order items that have different DSKs will be transported in different loads; this restriction is applied only in the last leg of the "web" (i.e., when the actual delivery to the customer will be made); if MIT is given, order items with the same DSK must have the same MITs, which in turn must be different from all other order items' MITs; |
reference (order item) | String | No | 255 | Free text field; | |
classifications | classifications [] | No | N/A | Grouping element of all classifications of an order item; | |
attributes | attributes[] | No | N/A | Grouping element of all attributes of an order item; |
deliveryUnit, data type used in TOL/TRE integrations | |||||
---|---|---|---|---|---|
Name | Type | Mandatory | Size | Description | Observation |
deliveryUnitShipmentUnitsQuantity | Inteiro | Yes | 10 | Do not use. It will be removed in future releases. | |
shipmentUnitWrapperCode | String | Yes | 30 | Do not use. It will be removed in future releases. | |
orderItems | List <String> | Yes | N/A | Do not use. It will be removed in future releases. | Orderitem OrderitemSourceid |
orderItemShipmentUnitsQuantity | Inteiro | Yes | 10 | Do not use. It will be removed in future releases. |
classifications, data type used in TOL/TRE integrations | |||||
---|---|---|---|---|---|
Name | Type | Mandatory | Size | Description | Observation |
type | String | Yes | 255 | Order classification type; | |
value | String | Yes | 255 | Order classification value; |
attributes, data type used in TOL/TRE integrations | |||||
---|---|---|---|---|---|
Name | Type | Mandatory | Size | Description | Observation |
name | String | Yes | 255 | Order attribute name; | |
value | String | Yes | 255 | Order attribute value; |
Answer Layout
ordersResponse, data type used in TOL/TRE integrations | |||||
---|---|---|---|---|---|
Name | Type | Mandatory | Size | Description | Observation |
result | result[] | Yes | N/A | Grouping element of all results | There must be at least 1 result in this list; |
sucess | Boolean | Yes | 1 | Success or failure flag |
result, data type used in TOL/TRE integrations | |||||
---|---|---|---|---|---|
Name | Type | Mandatory | Size | Description | Observation |
errorCodes | String | No | 30 | List of error codes | |
errorMessage | String | No | 255 | Error messages | |
identifier | String | No | 30 | Error table identifier | |
sucess | Boolean | Yes | 1 | Success or failure flag |
Error catalog
Code | Message | Description |
Incoterm
FOB:
- They represent orders that will be picked up by customers at the plants (the customer is responsible for shipping);
- FOB orders are never mixed with CIF orders in the same trip;
- As these orders are picked up by customers at the plants, they are never distributed to carriers (The trips for these orders are born with the status "Created" and not with the status "Distributed");
CIF:
- Represent orders that will be delivered to customers by the Shipper (shipper is responsible for freight)
- CIF orders are never mixed with FOB orders in the same trip;
- As these orders are delivered by the Shipper, they need to be distributed to carriers that will make the delivery (The trips of these orders are born with the status "Distributed" and not with the status "Created");
FOBT:
- It is equivalent to a FOB order with the difference that the carrier that will collect it is already known. The cargo is automatically linked to this carrier;
- FOBT orders will never be mixed with FOB orders;
OP:
Equivalent to a CIF application;
OP orders will never be mixed with CIF orders;
Attachments