MercuryGate APIs: Frequently Asked Questions (beta)
When viewing schemas in the documentation, anything marked with a red asterisk (*) is required. Note however, that required fields inside an optional data element are only required if that object is present. For example, a LocationCode is typically not required, but if you have a LocationCode, it must include scheme and code.
All data elements should have some validation on them, typically a maximum value or maximum length. These can be found in the OpenApi specification, and viewed in the RapiDoc or Swagger viewers.
There are additional restrictions which cannot be captured in an OpenApi specification, such as when one field is conditionally required based on the value of another field. These are documented in the field descriptions as often as possible.
There is a documentation supplement with definitions of values found in "enum" data elements in the API. The definitions are intended to help developers unfamiliar with a particular term in a transportation context. The definitions may therefore be simplistic and not capture the full meaning of a value across all modes of transportation.
There are currently some values missing documentation; this documentation will continue to grow over time. If you have any specific questions, corrections, or additions, please let us know.
Generally speaking, any amount that can be derived or calculated from other data that is already available in the API model is not included. This prevents discrepancies between provided and calculated totals.
There are natural exceptions to this rule, such as distances, where there may be multiple methods used to calculate a value. You may also see field names which imply a calculated amount, but are traditionally provided by transportation vendors instead of being calculated.
The MercuryGate TMP supports many different modes of transport, countries, and regulations. Some API endpoints may be customized for a particular use in one or more of those categories, but most APIs are agnostic of Mode or location.
This means that a customer may send a request using a data type or format with which you are unfamiliar. Generally speaking, the best practice in these cases is to respond by not moving forward in the process. For example, returning no rates or rejecting a booking request. If a customer asks for a rate with a service or equipment you cannot provide, returning a rate implies that you can provide that service or equipment for the given rate.
This best practice is not absolute. For instance, a location may be fully populated, but also include a location code with a coding scheme you do not understand. If there is enough information in the location to continue, it would be ok to continue.
Shipping units are the pieces being shipped -- the level of packaging directly handled by a carrier.
Items are the individual items inside shipping units and may or may not be provided by the shipper.
Many carriers only need to know there are a number of pallets, boxes, or other containers of items to pick up or drop, and only broad classifications, dimensions, and total weights of each container are important.
Knowing the breakdown of each individual item is often not necessary, however there are circumstances where the contents do matter. The most obvious of these are for moves that involve customs or tariffs.
Often rating calls are made only with shipping units when the final contents have not yet been determined, so it is possible to perform rating only with shipping unit information, but then receive item information when processing a booking [tender] request associated with the rate.
MercuryGate re-used internal API models externally. This means that some requests that pass through an internal system where ids are generated initially do not contain the id. We are working to resolve this to avoid future confusion.
When you receive a request with a corresponding UUID-based id value, the id will be populated when your system is called, even though the id is not marked as required.