Saloodo! API for Carrier (1.0.0)

Download OpenAPI specification:Download

Introduction

Saloodo! offers to companies instant access to trusted road freight providers for on-demand shipments, with the freedom of choice of a marketplace and the security and convenience of a digital freight forwarder. We simplify your daily business by providing a single and convenient interface for tracking, documentation, and payment – giving you end-to-end control to your shipment processes within a single platform.

With saloodo! API documentation, customers are able to retrieve and push data to saloodo! platform. Any application can request data from saloodo!, if you require assistance or more information about how to connect please write an email to support@saloodo.com

I am a Carrier

I am a Shipper

Authentication

This is a short-lived (JWT Bearer-Token) authentication token which should be provided in request headers and should be refreshed.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer
Bearer format	"JWT"

Elm-Api-Key

This is a long-lived api key that should be provided in request headers.

Security Scheme Type	API Key
Header parameter name:	Elm-Api-Key

Shipments

A shipment request, which is done by the shipper, is the non-binding collection of information, in particular, for the purpose of submitting an offer, which is done by the carrier. The shipment request includes all necessary information about the cargo and its conditions such as:

number and type of cargo items
dimensions and weight
special conditions like hazardous or stackable
pick-up and drop-off locations
pick-up and drop-off dates and times

Get a list of shipments

Get the list of the open shipment requests posted by Saloodo! shippers. According to the customer needs, filters can be applied to obtain only the suitable shipment requests. Location predicate example:

/shipments?type=single&filter=active-offers&shipmentFilter[shipmentFilterPredicates][0][predicateType]=location&shipmentFilter[shipmentFilterPredicates][0][countryCode]=DE&shipmentFilter[shipmentFilterPredicates][0][locationKind]=pickup&&shipmentFilter[shipmentFilterPredicates][0][postalCodes][0][zipCode]=50&shipmentFilter[shipmentFilterPredicates][0][postalCodes][1][zipCode]=69

Content predicate example:

/shipments?type=single&filter=active-offers&shipmentFilter[shipmentFilterPredicates][0][predicateType]=content&shipmentFilter[shipmentFilterPredicates][0][minWeight]=0&shipmentFilter[shipmentFilterPredicates][0][maxWeight]=5000&shipmentFilter[shipmentFilterPredicates][0][isHazardous]=0

Combined example:

/shipments?type=bundle&filter=active-offers&shipmentFilter[shipmentFilterPredicates][0][predicateType]=location&shipmentFilter[shipmentFilterPredicates][0][countryCode]=DE&shipmentFilter[shipmentFilterPredicates][0][locationKind]=pickup&&shipmentFilter[shipmentFilterPredicates][0][postalCodes][0][zipCode]=10&shipmentFilter[shipmentFilterPredicates][1][predicateType]=location&shipmentFilter[shipmentFilterPredicates][1][locationKind]=dropoff&&shipmentFilter[shipmentFilterPredicates][1][countryCode]=CZ&shipmentFilter[shipmentFilterPredicates][1][postalCodes][0][zipCode]=20&shipmentFilter[shipmentFilterPredicates][2][predicateType]=content&shipmentFilter[shipmentFilterPredicates][2][minWeight]=0&shipmentFilter[shipmentFilterPredicates][2][maxWeight]=15000&shipmentFilter[shipmentFilterPredicates][2][minLoadingMeters]=5.4&shipmentFilter[shipmentFilterPredicates][2][maxLoadingMeters]=16

query Parameters

type required	string Enum: "single" "bundle" Whether `single` or `bundle` shipments should be listed
filter required	string Enum: "active-offers" "open-offers" "accepted-offers" "new-deals" "accepted-offers-archived" "in-clarification" "incomplete-archived" "pe-check" "shipment-with-deals" "shipment-without-deals" Filter Options: active-offers: returns all the shipments with active offers. open-offers: returns all the shipments don't have active offers by carrier. accepted-offers: returns all the shipments with deals where pod not yet confirmed or not in clarification. new-deals: returns all the shipments with deals( deals created today) where pod not yet confirmed or not in clarification. accepted-offers-archived: returns all the shipments(ARCHIVED) with deals and pod confirmed or not in clarification. in-clarification: returns all the shipments with deals and in clarification. incomplete-archived: returns all the shipments(ARCHIVED) and its clarification status is complete-cancellation/dead-frieght. pe-check: returns all the shipments with deals where payment was done and pallet exchange check true. shipment-with-deals: returns all the shipments with deals( deal got updated in last month) where pod not yet confirmed. shipment-without-deals: returns all the shipments with both active offers and open for new offers.
page	integer Example: page=1 The page number
pageSize	integer Example: pageSize=20 How many items per page
orderBy	string Example: orderBy=untilDate The sort column. Allowed columns: id, untilDate, elmId, updatedAt, totalWeight, loadingMeters, pickup.fromDate, pickup.postalCode, pickup.countryCode, dropoff.fromDate, dropoff.postalCode, dropoff.countryCode
order	string Enum: "ASC" "DESC" The sort order
	object (Shipment Filter) Shipment Filter

Responses

Response samples

200
400
403

Content type

application/json


{"list": 
[
{"type": "single",
"salesRate": 100,
"shipmentElmId": "5XQBQ5R",
"validFromDate": "2022-01-01T00:00:00+00:00",
"validUntilDate": "2022-01-02T14:11:41+00:00",
"message": "Important message!",
"externalShipmentId": "string",
"distance": 1000040,
"transactionCurrency": 
{"name": "EUR",
"symbol": "€"
},
"customClearance": false,
"cargos": 
[
{"unitType": "pallet",
"units": 1,
"length": 120,
"width": 80,
"height": 120,
"weight": 120,
"fragile": false,
"hazardous": false,
"unNumber": 2094,
"adrClass": 2,
"adrDescription": "ADR description",
"loadingEquipmentExchange": false,
"furtherCargoDescription": "More details about cargo detailes",
"palletExchange": false
}
],
"pickupLocation": 
{"establishment": "DHL Packstation",
"countryCode": "DE",
"postalCode": "53111",
"city": "Bonn",
"street": "Dorotheenstraße",
"streetNo": "103",
"streetNoAddition": "string",
"timezone": "Europe/Berlin",
"tourOrder": 1,
"nextLocationRange": 1,
"geo": 
{"location": 
{"lat": 50.74049,
"lng": 7.08929
},
"location_type": "ROOFTOP",
"viewport": 
{"northeast": 
{"lat": 52.5052,
"lng": 13.3535
},
"southwest": 
{"lat": 52.5025,
"lng": 13.3508
}
}
},
"locationTypes": 
["com_with_ramp"
],
"fromDate": "2022-01-01T08:45:32+01:00",
"untilDate": "2022-01-02T17:45:32+01:00",
"fixedSlot": true,
"addressLine1": "Lützowplatz 17",
"addressLine2": "null",
"area": "10785",
"locationName": "Hotel Berlin Berlin",
"userInputAddress": "Hotel Berlin Berlin, Lützowpl. 17, 10785 Berlin, Germany",
"areaPlaceId": "string",
"cityPlaceId": "string"
},
"dropOffLocation": 
{"establishment": "DHL Packstation",
"countryCode": "DE",
"postalCode": "53111",
"city": "Bonn",
"street": "Dorotheenstraße",
"streetNo": "103",
"streetNoAddition": "string",
"timezone": "Europe/Berlin",
"tourOrder": 1,
"nextLocationRange": 1,
"geo": 
{"location": 
{"lat": 50.74049,
"lng": 7.08929
},
"location_type": "ROOFTOP",
"viewport": 
{"northeast": 
{"lat": 52.5052,
"lng": 13.3535
},
"southwest": 
{"lat": 52.5025,
"lng": 13.3508
}
}
},
"locationTypes": 
["com_with_ramp"
],
"fromDate": "2022-01-01T08:45:32+01:00",
"untilDate": "2022-01-02T17:45:32+01:00",
"fixedSlot": true,
"addressLine1": "Lützowplatz 17",
"addressLine2": "null",
"area": "10785",
"locationName": "Hotel Berlin Berlin",
"userInputAddress": "Hotel Berlin Berlin, Lützowpl. 17, 10785 Berlin, Germany",
"areaPlaceId": "string",
"cityPlaceId": "string"
},
"loadingMeters": 13.6,
"totalWeight": 0
}
],
"countOpen": 1,
"countActive": 0,
"countDeals": 0,
"countNewDeals": 0,
"countClarification": 0,
"countIncompleteArchived": 0,
"countArchived": 0,
"countPeCheck": 0,
"countOfferBots": 0,
"countShipmentsWithDeals": 0,
"countShipmentsWithoutDeals": 0,
"totalCount": 1
}

Offers

An offer, which is submitted by the carrier, is the submission of a binding price and a description of the associated conditions relating to a particular shipment request, which is done by the shipper.

Make an Offer

Carriers can use this endpoint to make an offer on one of the shipment requests published by saloodo! shippers. Saloodo! carrier can provide one offer per shipment request with specific validity time. If you want to post two or more offers per shipment request please contact support@saloodo.com

Request Body schema: application/json

Make Offer

type required	string Enum: "single" "bundle" Offer Type
shipmentElmId required	string Saloodo! shipment identifier
shipmentRequestId	integer Saloodo! shipment request identifier
offerSource	string Enum: "web" "whatsapp_notification" Offer Source
externalOfferId	string External carrier offer identifier
price required	number <integer> Price in the smallest monetary unit in specified currency, e.g. for EUR currency in cents
currency required	string 3 letter currency code as defined in ISO 4217. Default value is EUR
validUntil required	string Ending time for offer lifespan in localtime formatted according to RFC-3339 and expressed with timezone offset
truckTypes required	Array of strings Items Enum: "curtainsider" "standard_box_trailer" "mega_trailer" "tautliner" "combination_truck_curtain" "combination_truck_swap_body" "cooler_truck" "7,5_ton_truck" "12_ton_truck" "van_curtain" "se_trailer_truck" "link_truck" "se_trailer_link_truck" "trailer_link_truck" Truck type curtainsider: Full Curtainsider standard_box_trailer: Standard Box Trailer mega_trailer: Mega Trailer tautliner: Tautliner combination_truck_curtain: Combination Truck Curtain combination_truck_swap_body: Combination Truck Swap Body cooler_truck: Cooler Truck 7,5_ton_truck: 7,5 ton Truck 12_ton_truck: 12 ton Truck van_curtain: Van Curtain se_trailer_truck: SE Trailer link_truck: Link Truck se_trailer_link_truck: SE Trailer + Link Truck trailer_link_truck: Trailer + Link Truck \| For more truck details, please contact support@saloodo.com
truckBodyTypes	Array of strings Items Enum: "tail_lift" "no_tail_lift" Truck body type tail_lift: Tail lift no_tail_lift: No tail lift
pickupFrom required	string Starting time for pickup date
pickupUntil required	string Starting time for pickup until date
dropoffFrom required	string Starting time for dropoff date
dropoffUntil required	string Starting time for dropoff until date
additionalInformation	string Additional Information regarding the offer
driverAdrAllowed	boolean Capability of carrying hazardous cargo elements
additionalRequirementsFulfilled	Array of strings

Responses

Request samples

Payload

Content type

application/json


{"type": "single",
"shipmentElmId": "YPR12YP",
"shipmentRequestId": 1000039,
"offerSource": "web",
"externalOfferId": "YPR12YP",
"price": 50000,
"currency": "EUR",
"validUntil": "2022-01-01T17:45:32+01:00",
"truckTypes": 
["curtainsider"
],
"truckBodyTypes": 
["tail_lift"
],
"pickupFrom": "2022-01-01 16:00:00",
"pickupUntil": "2022-01-01 16:00:00",
"dropoffFrom": "2022-01-01 16:00:00",
"dropoffUntil": "2022-01-01 16:00:00",
"additionalInformation": "string",
"driverAdrAllowed": true,
"additionalRequirementsFulfilled": 
["tail_lift"
]
}

Response samples

200
400

Content type

application/json


{"success": true,
"offerElmId": "YPR12YP"
}

Cancel Offer

By using the generated offerElmId after the offer is submitted, carriers can use this endpoint to cancel one of his open offers. Saloodo! carriers cannot cancel the offer when this is in the process of being booked or it is already booked by the shipper.

path Parameters

offerElmId

required

any

Offer identifier

Responses

Response samples

200
400
403
404

Content type

application/json


{"success": true,
"offerElmId": "BM6XDL8"
}

Orders

A deal is concluded when the Shipper accepts the Carrier's offer together with its conditions, which is related to the former shipment request. The deal is binding.

Get a list of transport orders

It allows the carries to get the list of all their transport orders (deals) booked by the shipper. If needed, filters can be applied to get specific transport orders.

query Parameters

type required	string Enum: "single" "bundle" Whether `single` or `bundle` transport orders should be listed
page	integer Example: page=1 The page number
pageSize	integer Example: pageSize=20 How many items per page
shipmentElmId	string Example: shipmentElmId=Y4QXQPY Filter orders by Shipment Elm Id

Responses

Response samples

200
400
403

Content type

application/json


{"list": 
[
{"orderElmId": "FRBYB7X",
"offerElmId": "ZRBYB7X",
"shipmentElmId": "Y4QXQPY",
"consignor": 
{"company": "Some Company name.",
"name": "Same Doe",
"email": "smaildoe@gm.com",
"phone": "022447456389",
"refno": "ref30"
},
"consignee": 
{"company": "Some Company name.",
"name": "Dame Doe",
"email": "smailjoe@gm.com",
"phone": "022447456309",
"refno": "ref31"
},
"fulfillmentStatus": "DRIVER_ASSIGNED",
"inClarification": false,
"clarificationStatus": null
}
],
"currentPage": 1,
"nextPage": 2,
"pageSize": 3,
"totalResults": 10
}

Update Order Fulfillment status

After the shipment is booked by the shipper, Carrier can use this endpoint to update the milestones of this transportation.

path Parameters

orderElmID

required

string

Example: K4XBX5N

The "orderElmID" is the identification of a booked shipment. To fetch the orderElmID click here

Request Body schema: application/json

One of

status required	string Value: "DRIVER_ASSIGNED" Available fulfillment status types
phoneNumber required	string Driver phone number is in format of /^[0+][0-9-\s]{2,40}+$/ regex
driverName required	string Driver name and surname
date	string
vehiclePlateNumber	string

Responses

Request samples

Payload

Content type

application/json

Example


{"status": "DRIVER_ASSIGNED",
"phoneNumber": "+491781112233",
"driverName": "Peter Alexander",
"date": "2022-02-02 17:07:33",
"vehiclePlateNumber": "3737373"
}

Response samples

200
400
403

Content type

application/json


{"status": true,
"message": "status updated"
}

Upload transportation document

During transportation, Saloodo! carriers can upload directly on saloodo! the transportation documents (Proof of delivery, Pallet exchange Statements, Shipment photos)

Request Body schema: multipart/form-data

Upload Transport documents

file0 required	string <binary>
file1	string <binary>
type required	string Enum: "pallet-exchange" "pallet-exchange-counterstatement" "photo" "pod" The document type

Responses

Response samples

200
400
403

Content type

application/json


{"success": true,
"message": "Transport document file is added successfully"
}

Download transportation document

Documents specific to the transport order can be downloaded (Proof of delivery, Pallet exchange statements and counterstatements, Shipment photos, Credit notes, etc).

path Parameters

orderElmId required	string Example: K4XBX5N The order Elm id
fileType required	sting Enum: "transport-order" "pallet-exchange" "pallet-exchange-counterstatement" "pod" "photo" the document type to download

Responses

Response samples

403
404

Content type

application/json


{"status": 403,
"message": "Access Denied"
}

Carrier Webhooks

If carriers wants to get notified directly on their application, saloodo! webhooks delivers data to other applications in real time. Those notifications include being notify for new interesting shipment requests, offer cancelations, new bookings and information about the shipment.

Notify carrier if new shipment is created

Request Body schema: application/json

Shipment Requests

One of

id required	string Saloodo! Shipment Identifier
loadingMeters	number <double> Total Loading meter for the shipment
totalWeight	number <double> Deprecated Total weight of the shipment in kilograms.
distance	number <integer> Distance between pickup and drop off locations in meters.
required	Array of objects (CargoRequest) Cargo list
required	object (LocationRequest) Pickup/DropOff location request
required	object (LocationRequest) Pickup/DropOff location request
message	string Additional message about shipment

Responses

Request samples

Payload

Content type

application/json


{"id": "K4XBXZN",
"loadingMeters": 13.6,
"totalWeight": 13.6,
"distance": 1000040,
"cargos": 
[
{"unitType": "pallet",
"units": 1,
"length": 120,
"width": 80,
"height": 120,
"weight": 120,
"fragile": false,
"hazardous": false,
"unNumber": "0009",
"adrClass": "Explosive substances and articles",
"furtherRequirement": "Additional description regarding the dangerous goods",
"furtherCargoDescription": "Additional goods / commodity description for both non-ADR or for ADR",
"palletExchange": false
}
],
"pickup": 
{"address": 
{"establishment": "DHL Packstation",
"countryCode": "DE",
"postalCode": "53111",
"city": "Bonn",
"street": "Dorotheenstraße",
"streetNo": "103",
"geo": 
{"location": 
{"lat": 50.74049,
"lng": 7.08929
},
"location_type": "ROOFTOP",
"viewport": 
{"northeast": 
{"lat": 52.5052,
"lng": 13.3535
},
"southwest": 
{"lat": 52.5025,
"lng": 13.3508
}
}
}
},
"tourOrder": "1",
"locationTypes": 
["com_with_ramp"
],
"fromDate": "2022-01-22 08:45:32",
"untilDate": "2022-01-23 17:45:32",
"fixedSlot": true
},
"dropOff": 
{"address": 
{"establishment": "DHL Packstation",
"countryCode": "DE",
"postalCode": "53111",
"city": "Bonn",
"street": "Dorotheenstraße",
"streetNo": "103",
"geo": 
{"location": 
{"lat": 50.74049,
"lng": 7.08929
},
"location_type": "ROOFTOP",
"viewport": 
{"northeast": 
{"lat": 52.5052,
"lng": 13.3535
},
"southwest": 
{"lat": 52.5025,
"lng": 13.3508
}
}
}
},
"tourOrder": "1",
"locationTypes": 
["com_with_ramp"
],
"fromDate": "2022-01-22 08:45:32",
"untilDate": "2022-01-23 17:45:32",
"fixedSlot": true
},
"message": "Important message!"
}

Notify carrier if offer is booked

Request Body schema: application/json

Offer Booking Request

One of

shipmentId required	string Saloodo! Shipment Identifier
offerId required	string Saloodo! Offer Identifier
dealId required	string Saloodo! Deal Identifier
transportOrderUrl required	string Link for downloading transport order file

Responses

Request samples

Payload

Content type

application/json


{"shipmentId": "K4XBXZN",
"offerId": "YPR54T",
"dealId": "DL54DL",
"transportOrderUrl": "https://my.saloodo.com/deals/DL54DL/documents/transport-order.zip"
}

Notify carrier if offer is rejected

Request Body schema: application/json

Offer Rejection Request

One of

customerId	integer Customer Identifier
event	string Value: "OFFER_CANCELLED" Event name
time	integer Timestamp
date	object Date in local time which includes timezone and type
shipment	object Shipment which includes shipment identifier, elmid and reference number. Inside shipment payload there is branchcode and external customer id
data	object Data contains Shipment offer identifier and offer elmid

Responses

Request samples

Payload

Content type

application/json


{"customerId": 1053207,
"event": "OFFER_CANCELLED",
"time": 1673248279,
"date": 
{"date": "2023-01-09 07:11:19.061809",
"timezone_type": 3,
"timezone": "UTC"
},
"shipment": 
{"id": 4149633,
"elmId": "K4XBXZN",
"reference": "00013366239",
"payload": 
{"controllerBranchCode": "BUH-001",
"externalCustomerId": "20027460.RO0001"
}
},
"data": 
{"offerID": 5521579,
"offerElmId": "Z5BRP4B"
}
}

Notify carrier if pod is approved

Request Body schema: application/json

POD Approval Request

One of

shipmentId required	string Saloodo! Shipment Identifier
dealId required	string Saloodo! Deal Identifier
creditNoteUrl required	string Link for downloading credit note file

Responses

Request samples

Payload

Content type

application/json


{"shipmentId": "K4XBXZN",
"dealId": "DL54DL",
"creditNoteUrl": "https://my.saloodo.com/deals/DL54DL/documents/credit-note.zip"
}

Notify carrier if pod is rejected

Request Body schema: application/json

POD Rejection Request

One of

shipmentId required	string Saloodo! Shipment Identifier
dealId required	string Saloodo! Deal Identifier

Responses

Request samples

Payload

Content type

application/json


{"shipmentId": "K4XBXZN",
"dealId": "DL54DL"
}

Notify rate card carrier if offer is booked

Request Body schema: application/json

Rate Card Offer Booking Request

One of

shipmentId required	string Saloodo! Shipment Identifier
dealId required	string Saloodo! Deal Identifier
transportOrderUrl required	string Downloadable link for transport file
required	Array of objects (Rate Card Cargo Request) Cargo list
required	object (Rate Card Pickup/DropOff Location request) Rate Card Pickup/DropOff Location request
required	object (Rate Card Pickup/DropOff Location request) Rate Card Pickup/DropOff Location request
required	object (Rate Card Offer Request) Rate Card Offer Request

Responses

Request samples

Payload

Content type

application/json


{"shipmentId": "K4XBXZN",
"dealId": "DL54DL",
"transportOrderUrl": "http://my.saloodo.com/deals/REG213/documents/transport.pdf",
"cargos": 
[
{"unitType": "pallet",
"units": 1,
"length": 120,
"width": 80,
"height": 120,
"weight": 120,
"fragile": false,
"hazardous": false,
"palletExchange": false
}
],
"pickupLocation": 
{"locationTypes": 
["com_with_ramp"
],
"establishment": "DHL Packstation",
"countryCode": "DE",
"postalCode": "53111",
"city": "Bonn",
"street": "Dorotheenstraße",
"streetNo": "103",
"fromDate": "2022-02-02T17:45:32+01:00",
"untilDate": "2022-02-02T17:45:32+01:00"
},
"dropoffLocation": 
{"locationTypes": 
["com_with_ramp"
],
"establishment": "DHL Packstation",
"countryCode": "DE",
"postalCode": "53111",
"city": "Bonn",
"street": "Dorotheenstraße",
"streetNo": "103",
"fromDate": "2022-02-02T17:45:32+01:00",
"untilDate": "2022-02-02T17:45:32+01:00"
},
"offer": 
{"bodyTypes": 
["curtain_with_tail_lift"
],
"truckTypes": 
["single"
],
"priceWithMargin": 50000,
"currency": "EUR"
}
}