Send transport order to carrier

Descrip­tion of adding new trans­port order to select­ed car­ri­er for assign­ment of dri­ver and vehi­cle.

Scenario

  • car­ri­er is select­ed and present on Trans.eu Plat­form
  • car­ri­er’s Tran­sId is stored in exter­nal TMS and can be sent via API
  • con­di­tions of coop­er­a­tion have been agreed upon
  • car­ri­er is using Trans.eu Plat­form only, with no addi­tion­al freight man­age­ment soft­ware involved
  • both freight for­warder and car­ri­ers have exist­ing and valid Trans.eu account
  • car­ri­er has to assign vehi­cle and dri­ver
  • com­plet­ed order with vehi­cle and dri­ver is down­loaded from Trans.eu API

Diagram

Authorize access

Before it is pos­si­ble to send any request, user needs to autho­rize access.

  • client app was reg­is­tered using reg­is­tra­tion form
  • exter­nal app was grant­ed api keys (client_id and client_secret)
  • autho­riza­tion process has been imple­ment­ed in exter­nal app

Create new transport order

Each trans­port must con­sist of:

  • car­ri­er’s infor­ma­tion
  • load­ing loca­tion and time
  • unload­ing loca­tion and time
  • required truck body type
  • sum­ma­ry of freight’s loads weight
  • ftl/ltl para­me­ter

Endpoint:

POST https://api.platform.trans.eu/ext/orders-api/v1/orders-created

Request example: 

Exam­ple of trans­port order post­ing request:

{
  "freight": {
    "requirements": {
      "is_ftl": true,
      "required_truck_bodies": [
        "curtainsider",
        "box"
      ],
      "vehicle_size_id": "bus"
    },
    "carrier": {
      "company_id": 111111
    },
    "capacity": 20,
    "loads": [],
    "spots": [
      {
        "name": null,
        "spot_order": 1,
        "place": {
          "address": {
            "locality": "Kraków",
            "postal_code": "31-001",
            "country": "PL"
          }
        },
        "operations": [
          {
            "operation_order": 1,
            "loads": [],
            "type": "loading",
            "timespans": {
              "begin": "2021-08-22T11:00:00+0200",
              "end": "2021-08-22T12:00:00+0200"
            }
          }
        ]
      },
      {
        "spot_order": 2,
        "place": {
          "address": {
            "locality": "Dąbrowa Środkowa",
            "postal_code": "59-330",
            "country": "PL"
          }
        },
        "operations": [
          {
            "type": "unloading",
            "loads": [],
            "operation_order": 1,
            "timespans": {
              "begin": "2021-08-23T11:00:00+0200",
              "end": "2021-08-23T11:00:00+0200"
            }
          }
        ]
      }
    ]
  },
  "payment": {
    "days": 30,
    "price": {
      "type": "km",
      "value": 1500,
      "currency": "pln"
    }
  },
  "monitoring": {
    "required": true
  }
}

Response:

Con­fir­ma­tion of cre­at­ing new trans­port order

{
  "additional_terms": null,
  "created_at": "2021-08-03T10:46:47.095Z",
  "freight": {
    "carrier": {
      "assignee": null,
      "legal_name": "Firma Testowa Przewoźnik",
      "vat_id": "1111111111"
    },
    "id": "",
    "reference_number": null,
    "requirements": {
      "is_ftl": true,
      "other_requirements": [],
      "required_adr_classes": [],
      "required_truck_bodies": [
        "curtainsider",
        "box"
      ],
      "required_ways_of_loading": [],
      "shipping_remarks": null,
      "temperature": null,
      "vehicle_size_id": "bus"
    },
    "shipper": {
      "assignee": {
        "account_id": 749989,
        "email": "api@trans.eu",
        "family_name": "Kowalski",
        "fax": null,
        "given_name": "Adam",
        "telephone": "0048 1111111",
        "trans_id": "2222222-1"
      },
      "legal_name": "Firma Testowa Spedycja",
      "vat_id": "222222222"
    },
    "spots": [
      {
        "description": null,
        "name": null,
        "operations": [
          {
            "loads": [],
            "operation_order": 1,
            "time_window": null,
            "time_window_reason": null,
            "timespans": {
              "begin": "2021-08-22T09:00:00.000Z",
              "end": "2021-08-22T10:00:00.000Z"
            },
            "type": "loading"
          }
        ],
        "place": {
          "address": {
            "country": "pl",
            "description": null,
            "locality": "Kraków",
            "number": null,
            "postal_code": "31-001",
            "street": null
          },
          "coordinates": null
        },
        "spot_order": 1
      },
      {
        "description": null,
        "name": null,
        "operations": [
          {
            "loads": [],
            "operation_order": 1,
            "time_window": null,
            "time_window_reason": null,
            "timespans": {
              "begin": "2021-08-23T09:00:00.000Z",
              "end": "2021-08-23T09:00:00.000Z"
            },
            "type": "unloading"
          }
        ],
        "place": {
          "address": {
            "country": "pl",
            "description": null,
            "locality": "Dąbrowa Środkowa",
            "number": null,
            "postal_code": "59-330",
            "street": null
          },
          "coordinates": null
        },
        "spot_order": 2
      }
    ]
  },
  "id": "a988c5a6-6111-49e8-ae5b-225727bdbfbb",
  "invoice": null,
  "monitoring": {
    "required": true
  },
  "number": "2021/08/03/2",
  "payment": {
    "days": 30,
    "price": {
      "currency": "pln",
      "type": "km",
      "value": 1500
    }
  },
  "related": [],
  "status": {
    "value": "proposal-waiting"
  }
}

Receiv­ing updat­ed trans­port order:

GET https://api.platform.trans.eu/ext/orders-api/orders-created/a988c5a6-6111-49e8-ae5b-225727bdbfbb

Response exam­ple:

{
  "additional_terms": null,
  "archived_at": null,
  "attachments": [],
  "can_archive": false,
  "cancellation": null,
  "cooperation": {
    "status": "ACTIVE"
  },
  "created_at": "2021-07-01T08:54:07.008Z",
  "driver": {
    "account_id": 771476,
    "contact_phone": {
      "number": "11111111111",
      "prefix": "0048"
    },
    "email": "trans@trans.eu",
    "employee_id": 999446,
    "family_name": "Driver",
    "full_name": "Jan Driver",
    "given_name": "Jan",
    "identity_document_number": null,
    "phone": null
  },
  "freight": {
    "carrier": {
      "assignee": null,
      "legal_name": "Test Company",
      "vat_id": "11111111111"
    },
    "id": "",
    "reference_number": null,
    "requirements": {
      "is_ftl": true,
      "other_requirements": [
        "lift",
        "hds"
      ],
      "required_adr_classes": [
        "adr_1"
      ],
      "required_truck_bodies": [
        "cooler",
        "isotherm"
      ],
      "required_ways_of_loading": [
        "top"
      ],
      "shipping_remarks": "Shipping remarks",
      "temperature": {
        "max": 100,
        "min": 10
      },
      "vehicle_size_id": "bus"
    },
    "shipper": {
      "assignee": {
        "account_id": 749989,
        "email": "test@trans.eu",
        "family_name": "Kowalski",
        "fax": null,
        "given_name": "Krzysztof",
        "telephone": "0048 111111111",
        "trans_id": "1007374-1"
      },
      "legal_name": "Test spedition company",
      "vat_id": "222222222222"
    },
    "spots": [
      {
        "description": "Example description",
        "name": "Magazine 1",
        "operations": [
          {
            "loads": [],
            "operation_order": 1,
            "time_window": null,
            "time_window_reason": null,
            "timespans": {
              "begin": "2021-06-22T09:00:00.000Z",
              "end": "2021-06-22T10:00:00.000Z"
            },
            "type": "loading"
          }
        ],
        "place": {
          "address": {
            "country": "pl",
            "description": null,
            "locality": "Kraków",
            "number": "5",
            "postal_code": "31-001",
            "street": "Wawel"
          },
          "coordinates": {
            "latitude": 50.06143,
            "longitude": 19.93658
          }
        },
        "spot_order": 1
      },
      {
        "description": null,
        "name": null,
        "operations": [
          {
            "loads": [],
            "operation_order": 1,
            "time_window": null,
            "time_window_reason": null,
            "timespans": {
              "begin": "2021-06-23T09:00:00.000Z",
              "end": "2021-06-23T09:00:00.000Z"
            },
            "type": "unloading"
          }
        ],
        "place": {
          "address": {
            "country": "pl",
            "description": null,
            "locality": "Dąbrowa Środkowa",
            "number": "34",
            "postal_code": "59-330",
            "street": "Średnia"
          },
          "coordinates": {
            "latitude": 51.41828,
            "longitude": 16.33485
          }
        },
        "spot_order": 2
      }
    ]
  },
  "id": "da012de9-faca-4b14-b380-9b94aadff6fa",
  "invoice": null,
  "is_archived_permanently": false,
  "legacy_freight_id": null,
  "monitoring": {
    "providers": [
      "trans_task",
      "external_telematics"
    ],
    "required": true
  },
  "number": "2021/07/01/1",
  "payment": {
    "days": 30,
    "price": {
      "currency": "pln",
      "type": "km",
      "value": 1500
    }
  },
  "related": [],
  "source": {
    "author_account_id": 749989,
    "source_date": "2021-07-01T08:54:07.008Z",
    "source_id": null,
    "type": "api"
  },
  "status": {
    "comment": null,
    "value": "waiting-for-confirmation"
  },
  "vehicle": {
    "semi_trailer": {
      "dispatcher_id": 54083,
      "id": 501737,
      "kind": "4_semi_trailer",
      "registration_plate_number": "PL1111111",
      "type": "5_tent"
    },
    "truck": {
      "dispatcher_id": 41483,
      "id": 236503,
      "kind": "5_truck",
      "registration_plate_number": "DW1111111",
      "revision": 1,
      "type": null
    }
  }
}