Balancing contracts in the route

Setting balancing type for route.

The route-id identification number in request can be obtained when creating the route or by downloading the routes list.

POST
/ext/contracts-api/v2/routes/{route-id}/balance

Request Authorization

Every request MUST include a valid access token obtained during the user authorization process, provided using the Bearer token scheme in the Authorization header.

Request Header

POST  /ext/contracts-api/v2/routes/{route-id}/balance HTTP/1.1 
Host: api.platform.trans.eu 
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token) 
Api-key: {unique_app_api-key}

Request Parameters

Attribute	Type	Example	Mandatory	Description
balancing_type	String	“MANUAL”	Yes	Balancing type selected for route. Available values: MANUAL, CONTRACT_CONDITION, PERCENTAGE_SHARE, PRICE_ASCENDING, FREIGHT_LIMIT
contracts	Array of Objects		Yes for PERCENTAGE_SHARE	Percentage of orders among carriers
contracts.contract_id	String	“0dfc855d-ae8d-4d08-a8d4-a3375f8b78f9”	No	Carrier contract id
contracts.percentage_share	Float	81	No	Percentage share for carrier contract. All percentages must add up to 100.
freight_limit	Object		Yes for FREIGHT_LIMIT	Transport limits for `FREIGHT_LIMIT` type of balancing.
freight_limit.max	Int	30	Yes	Max limit in %
freight_limit.min	Int	70	yes	Min limit in %

Example Request Body

{
  "type": "in_order"
  "data": {
    "publication_time": {
      "value": 32000,
      "unit_code": "s",
      "user_unit_code": "min"
    },
    "order": "next_recipient"
  }
}

Response Fields

Attribute	Type	Example	Description
balancing_type	String	“MANUAL”	Balancing type choosen in request
contracted_route_id	String	“3a378345-1939–48c1-bc71-639e0add8048”	Route Id choosen in request
freight_limit	Object		Transport limits for `FREIGHT_LIMIT` type of balancing.
freight_limit.max	Int	30	Max limit in %
freight_limit.min	Int	70	Min limit in %
load_id	String	“3090941d-a16f-475f-9f8b-26db0ccc4a5d”
name	String	“Route no 1”	Contracted route name

Response Body

{
    "contracted_route_id": "3a378345-1939-48c1-bc71-639e0add8048",
    "load_id": "3090941d-a16f-475f-9f8b-26db0ccc4a5d",
    "balancing_type": "FREIGHT_LIMIT",
    "name": "trasa2 API",
    "freight_limit": {
        "min": 30,
        "max": 70
    }
}

Clients errors (code 400)

HTTP 4xx status codes indicate client errors, meaning that the request could not be processed due to an issue on the client side. Below is a list of request-specific errors.

Example error 1

Not valid route id

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": "Route with ID: 2f13c8bd-2160-4ea6-a7e5-6929b5eb2692 not found!",
    "service_code": 5404
}

Example error 2

No required ‘balancing_type’ field

{
    "message": [
        "balancing_type must be one of the following values: MANUAL, CONTRACT_CONDITION, PERCENTAGE_SHARE, PRICE_ASCENDING, FREIGHT_LIMIT"
    ],
    "error": "Bad Request",
    "statusCode": 400,
    "service_code": 5404
}

Example error 3

Not allowed balancing type

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "BalancingTypeException",
    "status": 420,
    "detail": "Chosen balancing type is not allowed for this contracted-route."
}

Example error 4

Wrong contract ids for the route

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Conflict",
    "status": 409,
    "detail": "Contracts are not compatible"
}

Example error 5

For PERCENTAGE_SHARE balancing type summary share must be 100

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "Failed Validation",
    "validation_messages": {
        "contracts": {
            "contractsPercentageShare": "Contracts summary percentage share must be equal 100 and contains only unique contract ids"
        }
    }
}