Update fixed contract - Trans.eu Api

Updating fixed contract not yet accepted by carrier.

Updating contract overwrites completely contract data. If any value is not set and allowed as null, it will be considered as null value and overwritten.

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

PUT
 /ext/contracts-api/v2/contracts/fixed/{contract-id}

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/contracts/fixed/{contract-id} 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
carrier	Object		Yes	Carrier invited to the get contract
carrier.company	Object		Yes	Carrier company details
carrier.company.id	Int	456745	Yes	Carrier company Id
carrier.contact_persons	Array of Objects		No	Carrier persons invited to get contract
carrier.contact_persons.employee	Object		No	Contact person details
carrier.contact_persons.employee.account_id	Int	123321	No	Contact person internal Id
config	Object		Yes	Contract configuration
config.send_to_carrier	Boolean	True	Yes	If `True`, created contract will be automatically send to carrier.
order_terms	Object		Yes	Order terms
order_terms.additional_terms	String	“additional terms text”	No	Additional terms for contract
order_terms.automatic_order_sending	Boolean	True	No	Set `True` will result in automatic creation of a confirmed order when the carrier accepts the freight
order_terms.insurance	Object		No	Insurance requirements
order_terms.insurance.load	Object		No	Value of loads
order_terms.insurance.load.currency	String	“eur”	No	Loads value currency
order_terms.insurance.load.value	Int	12000	No	Value of loads
order_terms.insurance.third_party	Object		No	Required insurance value
order_terms.insurance.third_party.currency	String	“eur”	No	Insurance value currency
order_terms.insurance.third_party.value	Int	20000	No	Insurance value
order_terms.monitoring	Object		No	GPS monitoring
order_terms.monitoring.monitoring	Boolean	True	No	Asking for GPS monitoring if technically possible
order_terms.payment_period	Object		Yes	Payment period
order_terms.payment_period.days_type	String	“CALENDAR”	No	Type of days in the period. Available values: `WORK`, `CALENDAR`
order_terms.payment_period.value	Int	20	Yes	Number of days
order_terms.silent_confirmation
order_terms.silent_confirmation.enabled
order_terms.silent_confirmation.is_enabled
order_terms.silent_confirmation.time
order_terms.silent_confirmation.time.begin
order_terms.silent_confirmation.time.end
order_terms.silent_confirmation.time.unit_code
order_terms.silent_confirmation.time.user_unit_code
order_terms.silent_confirmation.time.value
period	Object		Yes	Cooperation period
period.from	String	“2027–01-01T00:00:00.000Z”	Yes	Start of cooperation
period.timezone	String	“2027–12-31T23:59:59.000Z”	Yes	Time zone
period.to	String	“Europe/Warsaw”	No	End of cooperation. Possible value `null` for indefinitely.
planned_shipments	Object		No	Planned shipments in the contract
planned_shipments.periods	Array of Objects		No	Periods list
planned_shipments.periods.from	String	“2027–01-01T00:00:00.000Z”	No	Start of period
planned_shipments.periods.to	String	“2027–12-31T23:59:59.000Z”	No	End of period
planned_shipments.periods.value	Int	50	No	Number of shipments in period
planned_shipments.type	String	“required”	Yes	Type of shipments. Available values: `required`, `expected`, `no_more_than`.
planned_shipments.unit	String	“shipment”	Yes	Unit of shipments. Available values: `shipment`, `ton`, `km`.
planned_shipments.value	String	100	Yes	Total number of shipments in the contract
pricing	Object		No	Pricing for contract
pricing.negotiable	Boolean	True	No	Enabling price negotiation with carrier
pricing.price	Object		No	Price for negotiations. Required for all pricing type except “pallets”.
pricing.price.currency	String	“eur”	No	Price currency for negotation
pricing.price.value	Float	145	No	Price value.
pricing.price_list	Array of Objects		No	Price list. Required for pricing type “pallets”.
pricing.price_list.price	Object		No	Price for negotiations
pricing.price_list.price.currency	String	“eur”	No	Price currency
pricing.price_list.price.value	Float	234.34	No	Price value
pricing.price_list.range	Object		No	Range of pallets for negotiation
pricing.price_list.range.from	Int	1	No	Min value of pallets
pricing.price_list.range.to	Int	6	No	Max value of pallets
pricing.settlement_basis	String	“distance_from_gps”	No	Surcharge basis. Required for pricing types: “km”, “ton”. Available values for “km”: `distance_declared_in_order_terms`, `distance_declared_by_carrier`, `distance_from_gps` Available values for “ton”: `loading`, `unloading`
pricing.type	String	“route”	Yes	Type of pricing. Available values: `route`, `km`, `ton`, `pallets`, `linear`. Settlement per `ton` is only available for routes with vehicles handling bulk materials. Settlements based on the `pallet` price list is only possible for routes with pallets loads.
reference_number	String	“Kontrakt 23/2”	No	External reference number
route	Object		Yes	Route for new contract
route.id	String	“3fa85f64-5717–4562-b3fc-2c963f66afa6”	Yes	Route Id
surcharges	Array of Objects		No	Surcharges
surcharges.currency	String	“eur”	Yes	Surcharges currency
surcharges.data
surcharges.description	String	“additional text”	No	Surcharge description
surcharges.id	String	“a1ebb289-e665-4b30-a580-d263552ef88c”		Surcharge Id
surcharges.is_active	Boolean	True		Surcharge activation status
surcharges.is_global	Boolean	False		If `True`, surcharge is from template
surcharges.kind	String	“grid”		Kind of surcharge. Available values: `grid`, `linear`, `value`
surcharges.schedules	Array of Objects			Surcharge schedules
surcharges.schedules.data	Object			Surcharge data
surcharges.schedules.data.matrix	Array of Objects			Data object for `additional_stop`, `baf`, `pallets_exchange` surcharge types.
surcharges.schedules.data.matrix.unit	String	“percentage”		Unit of data. Available values: `percentage`, `value`.
surcharges.schedules.data.matrix.value	Int	5		Data value
surcharges.schedules.data.currency	String	“eur”		Currency for data
surcharges.schedules.data.unit	String	“percentage”		Unit of data for `week_days` surcharge type. Available values: `percentage`, `value`.
surcharges.schedules.data.week_days	Array of Objects			Data object for `week_days` surcharge types.
surcharges.schedules.data.week_days.id	String	“1_monday”		Week day Id
surcharges.schedules.data.week_days.operations	Array of Objects			List of operations
surcharges.schedules.data.week_days.operations.type	String	“loading”		Operation type. Available values: `loading`, `unloading`
surcharges.schedules.data.week_days.operations.value	Int	5		Data Value
surcharges.schedules.timespan	Object			Surcharge schedule period
surcharges.schedules.timespan.from	String	“2026–04-30T15:30:00+02:00”		Start of schedule
surcharges.schedules.timespan.to	String	“2026–05-28T02:00:00+02:00”		End of schedule
surcharges.type	String	“baf”		Surcharge type. Available values: `additional_stop`, `baf`, `pallets_exchange`, `week_day`

Example Request Body

{
  "route": {
    "id": "7eae0ff7-a20e-4378-98df-f1efc2a32de1"
  },
  "config": {
    "send_to_carrier": false
  },
  "carrier": {
    "company": {
      "id": 1013865
    },
    "contact_persons": [
      {
        "employee": {
          "account_id": 771476
        }
      }
    ]
  },
  "period": {
    "from": "2027-01-01T00:00:00.000Z",
    "to": null,
    "timezone": "Europe/Warsaw"
  },
  "order_terms": {
    "monitoring": {
      "required": true
    },
    "additional_terms": "Additional terms text",
    "insurance": {
      "load": {
        "value": 4000,
        "currency": "EUR"
      },
      "third_party": {
        "value": 3000,
        "currency": "EUR"
      }
    },
    "automatic_order_sending": true,
    "payment_period": {
      "days_type": "CALENDAR",
      "value": 31
    }
  },
  "planned_shipments": {
    "periods": [
      {
        "from": "2027-01-01T00:00:00.000Z",
        "to": "2027-12-31T23:59:59.000Z",
        "value": 100
      }
    ],
    "type": "required",
    "unit": "shipment",
    "value": 100
  },
  "pricing": {
    "type": "route",
    "negotiable": false,
    "price": {
      "value": 1500,
      "currency": "EUR"
    },
    "settlement_basis": "loading"
  },
  "reference_number": "CONTRACT-2024-001"
}

Response Fields

The response contains exactly the same list of fields as the Get contract details response.

Response Body for create fixed contract

{
    "id": "d6c337b2-4690-4885-aba1-cd2cacbcca85",
    "base_contract_id": "d6c337b2-4690-4885-aba1-cd2cacbcca85",
    "type": "fixed",
    "position": null,
    "carrier": {
        "company": {
            "id": 1013865,
            "name": "Carrier IIT 2"
        },
        "contact_persons": [
            {
                "id": "6ae8de62-3a6b-4f10-8429-1c5474246e05",
                "employee": {
                    "id": 999446,
                    "account_id": 771476,
                    "given_name": "Jan",
                    "family_name": "Nowak",
                    "trans_id": "1013865-3",
                    "email": "jnowak@mail.eu",
                    "telephone": "(0048) 12345678"
                },
                "channels": [
                    "email",
                    "push",
                    "web-push",
                    "messenger"
                ],
                "reported_by": {
                    "company": {
                        "id": 1007374
                    }
                }
            }
        ],
        "cooperation_status": "active"
    },
    "deactivations": [],
    "order_terms": {
        "monitoring": {
            "required": true
        },
        "additional_terms": "Additional terms text",
        "insurance": {
            "load": {
                "value": 4000,
                "currency": "eur"
            },
            "third_party": {
                "value": 3000,
                "currency": "eur"
            }
        },
        "automatic_order_sending": true,
        "payment_period": {
            "value": 31
        },
        "silent_confirmation": {
            "enabled": false,
            "time": null
        },
        "autoresponder": {
            "enabled": false,
            "time": null
        }
    },
    "period": {
        "from": "2027-01-02T00:00:00+00:00",
        "to": "2027-12-31T23:59:59+00:00"
    },
    "percentage_share": 0,
    "planned_shipments": {
        "periods": [
            {
                "value": 40,
                "from": "2027-01-02T00:00:00+00:00",
                "to": "2027-12-31T23:59:59+00:00"
            }
        ],
        "type": "required",
        "unit": "shipment",
        "value": 100
    },
    "pricing": {
        "negotiable": false,
        "type": "km",
        "settlement_basis": "distance_from_gps",
        "price": {
            "value": 260,
            "currency": "eur"
        },
        "fuel_base_price": {
            "value": null,
            "currency": "eur"
        }
    },
    "reference_number": "CONTRACT-2024-001",
    "route": {
        "id": "7eae0ff7-a20e-4378-98df-f1efc2a32de1",
        "unique_key": null,
        "name": "API5",
        "publication_scenario": {
            "type": "parallel"
        },
        "spots": [
            {
                "id": "e3ee48f9-2fcd-4580-8906-b6b18b0cc20f",
                "name": "Koniec trasy PL 33-300",
                "type": "loading",
                "place": {
                    "address": {
                        "locality": "Nowy Sącz",
                        "postal_code": "33-300",
                        "country": "pl",
                        "street": "Nowa",
                        "number": "16",
                        "location_id": 1248258,
                        "detailed_location_id": null,
                        "foreign_id": null,
                        "radius": null
                    },
                    "coordinates": {
                        "latitude": 49.62177,
                        "longitude": 20.69705
                    }
                }
            },
            {
                "id": "ca170110-0fdb-47ce-b742-1682a301d965",
                "name": "Początek PL 50-002",
                "type": "unloading",
                "place": {
                    "address": {
                        "locality": "Wrocław",
                        "postal_code": "50-002",
                        "country": "pl",
                        "street": "Nowa",
                        "number": "2",
                        "location_id": 2513724,
                        "detailed_location_id": null,
                        "foreign_id": null,
                        "radius": null
                    },
                    "coordinates": {
                        "latitude": 51.1,
                        "longitude": 17.03333
                    }
                }
            }
        ],
        "distance": {
            "declared": null,
            "calculated": {
                "value": 378,
                "unit_code": "km"
            }
        },
        "suggested_calculated_route_id": "1cd3f0d8-7a7b-4c64-94d9-e30aecda05ce",
        "distance_match": {
            "min": null,
            "max": null
        },
        "is_roundtrip": false,
        "requirements": {
            "required_truck_bodies": [],
            "required_adr_classes": [],
            "required_ways_of_loading": [],
            "additional_requirements": [],
            "shipping_remarks": null,
            "freight_type": null,
            "vehicle_size": "solo",
            "width": null,
            "height": null,
            "length": null,
            "volume": null,
            "capacity": {
                "min": null,
                "max": null
            },
            "exemption_from_adr": false
        },
        "balancing": {
            "type": "manual",
            "allowed_types": [
                "manual",
                "contract_condition",
                "freight_limit",
                "percentage_share",
                "price_ascending"
            ],
            "data": {
                "freight_limit": {
                    "min": null,
                    "max": null
                }
            }
        },
        "status": "active",
        "shipments_summary": {
            "amount": 0,
            "weight": {
                "value": 0,
                "unit_code": "t"
            },
            "distance": {
                "value": 0,
                "unit_code": "km"
            },
            "price": [
                {
                    "amount": null,
                    "currency": null
                }
            ]
        },
        "position": 253,
        "_stats": {
            "contracts": {
                "fixed": 1,
                "flexible": 0
            },
            "transports": {
                "realized": {
                    "average_price": null,
                    "count": 0
                },
                "awaiting": {
                    "median_price": null,
                    "count": null
                },
                "cheapest_carrier_offer": null
            }
        }
    },
    "shipper": {
        "company": {
            "id": 1007374,
            "name": "Forwarder IIT"
        },
        "contact_persons": [
            {
                "id": "2cfdbf44-c807-4c75-8405-6cdd7b988f6b",
                "employee": {
                    "id": 993848,
                    "account_id": 765361,
                    "given_name": "Jan",
                    "family_name": "Kowalski",
                    "trans_id": "1007374-5",
                    "email": "jkowalski@mail.eu",
                    "telephone": null
                },
                "channels": [
                    "email",
                    "push",
                    "web-push",
                    "messenger"
                ],
                "reported_by": {
                    "company": {
                        "id": 1007374
                    }
                }
            }
        ]
    },
    "status": "waiting_for_acceptance",
    "_stats": {
        "transports": {
            "realized": null,
            "average_per_month": null,
            "awaiting": null
        },
        "offers": {
            "accepted": null,
            "total": null,
            "acceptance_rate": null
        },
        "base_contract": {
            "registered": 1,
            "waiting_for_acceptance": 0,
            "waiting_for_initial_carrier_offer": 0,
            "waiting_for_shipper_offer": 0,
            "waiting_for_carrier_offer": 0,
            "refused": 0,
            "accepted": 0,
            "active": 0,
            "finished": 0
        }
    },
    "_meta": {
        "is_copy": false,
        "is_parent": false,
        "has_been_sent_to_carrier": true
    },
    "surcharges": []
}

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

Invalid route id

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": "Contracted route with ID: 3fa85f64-5717-4562-b3fc-2c963f66afa6 not found!",
    "service_code": 5404
}

Example error 2

Contract is accepted

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": "Contract is not updatable"
}

Example error 3

Incorrect contract type

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "Failed Validation",
    "validation_messages": {
        "pricing": {
            "type": {
                "type_excluded": "type = 'no_rate' not allowed on fixed contract"
            }
        }
    }
}