Create fixed contract

Cre­at­ing a new fixed con­tract in select­ed route.

After suc­cess­ful­ly exe­cut­ing the method, you receive in response the con­tract details with the unique con­tract iden­ti­fi­ca­tion num­ber id assigned when cre­at­ing the new con­tract.

POST
/ext/contracts-api/v2/contracts/fixed

Request Authorization

Every request MUST include a valid access token obtained dur­ing the user autho­riza­tion process, pro­vid­ed using the Bear­er token scheme in the Autho­riza­tion head­er.

Successful Response
Request Header
POST  /ext/contracts-api/v2/contracts/fixed 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 for create flexible contract
AttributeTypeExam­pleManda­to­ryDescrip­tion
car­ri­erObjectYesCar­ri­er invit­ed to the get con­tract
carrier.companyObjectYesCar­ri­er com­pa­ny details
carrier.company.idInt456745YesCar­ri­er com­pa­ny Id
carrier.contact_personsArray of ObjectsNoCar­ri­er per­sons invit­ed to get con­tract
carrier.contact_persons.employeeObjectNoCon­tact per­son details
carrier.contact_persons.employee.account_idInt123321NoCon­tact per­son inter­nal Id
con­figObjectYesCon­tract con­fig­u­ra­tion
config.send_to_carrierBooleanTrueYesIf True, cre­at­ed con­tract will be auto­mat­i­cal­ly send to car­ri­er.
order_termsObjectYesOrder terms
order_terms.additional_termsString“addi­tion­al terms text”NoAddi­tion­al terms for con­tract
order_terms.automatic_order_sendingBooleanTrueNoSet True will result in auto­mat­ic cre­ation of a con­firmed order when the car­ri­er accepts the freight
order_terms.insuranceObjectNoInsur­ance require­ments
order_terms.insurance.loadObjectNoVal­ue of loads
order_terms.insurance.load.currencyString“eur”NoLoads val­ue cur­ren­cy
order_terms.insurance.load.valueInt12000NoVal­ue of loads
order_terms.insurance.third_partyObjectNoRequired insur­ance val­ue
order_terms.insurance.third_party.currencyString“eur”NoInsur­ance val­ue cur­ren­cy
order_terms.insurance.third_party.valueInt20000NoInsur­ance val­ue
order_terms.monitoringObjectNoGPS mon­i­tor­ing
order_terms.monitoring.monitoringBooleanTrueNoAsk­ing for GPS mon­i­tor­ing if tech­ni­cal­ly pos­si­ble
order_terms.payment_periodObjectYesPay­ment peri­od
order_terms.payment_period.days_typeString“CALENDAR”NoType of days in the peri­od. Avail­able val­ues: WORK, CALENDAR
order_terms.payment_period.valueInt20YesNum­ber 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
peri­odObjectYesCoop­er­a­tion peri­od
period.fromString“2027–01-01T00:00:00.000Z”YesStart of coop­er­a­tion
period.timezoneString“2027–12-31T23:59:59.000Z”YesTime zone
period.toString“Europe/Warsaw”NoEnd of coop­er­a­tion. Pos­si­ble val­ue null for indef­i­nite­ly.
planned_shipmentsObjectNoPlanned ship­ments in the con­tract
planned_shipments.periodsArray of ObjectsNoPeri­ods list
planned_shipments.periods.fromString“2027–01-01T00:00:00.000Z”NoStart of peri­od
planned_shipments.periods.toString“2027–12-31T23:59:59.000Z”NoEnd of peri­od
planned_shipments.periods.valueInt50NoNum­ber of ship­ments in peri­od
planned_shipments.typeString“required”YesType of ship­ments. Avail­able val­ues: required, expected, no_more_than.
planned_shipments.unitString“ship­ment”YesUnit of ship­ments. Avail­able val­ues: shipment, ton, km.
planned_shipments.valueString100YesTotal num­ber of ship­ments in the con­tract
pric­ingObjectNoPric­ing for con­tract
pricing.negotiableBooleanTrueNoEnabling price nego­ti­a­tion with car­ri­er
pricing.priceObjectNoPrice for nego­ti­a­tions.
Required for all pric­ing type except “pal­lets”.
pricing.price.currencyString“eur”NoPrice cur­ren­cy for nego­ta­tion
pricing.price.valueFloat145NoPrice val­ue.
pricing.price_listArray of ObjectsNoPrice list.
Required for pric­ing type “pal­lets”.
pricing.price_list.priceObjectNoPrice for nego­ti­a­tions
pricing.price_list.price.currencyString“eur”NoPrice cur­ren­cy
pricing.price_list.price.valueFloat234.34NoPrice val­ue
pricing.price_list.rangeObjectNoRange of pal­lets for nego­ti­a­tion
pricing.price_list.range.fromInt1NoMin val­ue of pal­lets
pricing.price_list.range.toInt6NoMax val­ue of pal­lets
pricing.settlement_basisString“distance_from_gps”NoSur­charge basis. Required for pric­ing types: “km”, “ton”.
Avail­able val­ues for “km”: distance_declared_in_order_terms, distance_declared_by_carrier, distance_from_gps
Avail­able val­ues for “ton”: loading, unloading
pricing.typeString“route”YesType of pric­ing. Avail­able val­ues: route, km, ton, pallets, linear.
Set­tle­ment per ton is only avail­able for routes with vehi­cles han­dling bulk mate­ri­als.
Set­tle­ments based on the pallet price list is only pos­si­ble for routes with pal­lets loads.
reference_numberString“Kon­trakt 23/2”NoExter­nal ref­er­ence num­ber
routeObjectYesRoute for new con­tract
route.idString“3fa85f64-5717–4562-b3fc-2c963f66afa6”YesRoute Id
sur­chargesArray of ObjectsNoSur­charges
surcharges.currencyString“eur”YesSur­charges cur­ren­cy
surcharges.data
surcharges.descriptionString“addi­tion­al text”NoSur­charge descrip­tion
surcharges.idString“a1eb­b289-e665-4b30-a580-d263552e­f88c”Sur­charge Id
surcharges.is_activeBooleanTrueSur­charge acti­va­tion sta­tus
surcharges.is_globalBooleanFalseIf True, sur­charge is from tem­plate
surcharges.kindString“grid”Kind of sur­charge.
Avail­able val­ues: grid, linear, value
surcharges.schedulesArray of ObjectsSur­charge sched­ules
surcharges.schedules.dataObjectSur­charge data
surcharges.schedules.data.matrixArray of ObjectsData object for additional_stop, baf, pallets_exchange sur­charge types.
surcharges.schedules.data.matrix.unitString“per­cent­age”Unit of data. Avail­able val­ues: percentage, value.
surcharges.schedules.data.matrix.valueInt5Data val­ue
surcharges.schedules.data.currencyString“eur”Cur­ren­cy for data
surcharges.schedules.data.unitString“per­cent­age”Unit of data for week_days sur­charge type. Avail­able val­ues: percentage, value.
surcharges.schedules.data.week_daysArray of ObjectsData object for week_days sur­charge types.
surcharges.schedules.data.week_days.idString“1_monday”Week day Id
surcharges.schedules.data.week_days.operationsArray of ObjectsList of oper­a­tions
surcharges.schedules.data.week_days.operations.typeString“load­ing”Oper­a­tion type. Avail­able val­ues: loading, unloading
surcharges.schedules.data.week_days.operations.valueInt5Data Val­ue
surcharges.schedules.timespanObjectSur­charge sched­ule peri­od
surcharges.schedules.timespan.fromString“2026–04-30T15:30:00+02:00”Start of sched­ule
surcharges.schedules.timespan.toString“2026–05-28T02:00:00+02:00”End of sched­ule
surcharges.typeString“baf”Sur­charge type.
Avail­able val­ues: additional_stop, baf, pallets_exchange, week_day
Example Request Body for create fixed contract
{
  "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 for created fixed contract

The response con­tains exact­ly the same list of fields as the Get con­tract 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": "Firma Testowa Przewoźnik IIT 2"
        },
        "contact_persons": [
            {
                "id": "5a528dde-dee2-4a78-b1a9-4a1a333893d0",
                "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-01T00:00:00+00:00",
        "to": null
    },
    "percentage_share": 0,
    "planned_shipments": {
        "periods": [
            {
                "value": 100,
                "from": "2027-01-01T00:00:00+00:00",
                "to": "2027-12-31T23:59:59+00:00"
            }
        ],
        "type": "required",
        "unit": "shipment",
        "value": 100
    },
    "pricing": {
        "negotiable": false,
        "type": "route",
        "price": {
            "value": 1500,
            "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": "PL Wrocław",
                "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
        },
        "loads": [
            {
                "name": null,
                "type_of_load": "2_europalette",
                "amount": null,
                "width": {
                    "value": 0.8,
                    "unit_code": "m"
                },
                "height": null,
                "length": {
                    "value": 1.2,
                    "unit_code": "m"
                },
                "volume": null,
                "weight": {
                    "min": null,
                    "max": null
                },
                "pallets": {
                    "is_stackable": false,
                    "is_exchangeable": 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": 0,
                "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": []
    },
    "status": "registered",
    "_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": false
    },
    "surcharges": []
}

Clients errors (code 400)

HTTP 4xx sta­tus codes indi­cate client errors, mean­ing that the request could not be processed due to an issue on the client side. Below is a list of request-spe­cif­ic 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

Incor­rect pric­ing type

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Bad Request",
    "status": 400,
    "detail": "Contracted route with id: '7eae0ff7-a20e-4378-98df-f1efc2a32de1' does not support pricing by: 'ton'"
}
Example error 3

Incor­rect set­tle­ment basis

{
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "title": "Unprocessable Entity",
    "status": 422,
    "detail": "Failed Validation",
    "validation_messages": {
        "pricing": {
            "settlement_basis": {
                "isSettlementBasis": "settlement_basis must be a valid settlement basis from the dictionary or a settlement basis transport_price_type not matching the contract pricing_type"
            }
        }
    }
}