Skip to content

Document

In many logistic operations documents are an important part of the data flow. Documents can serve multiple purposes, such as proving some package was delivered with help of a photo, or some scanned document that establishes that the transferred goods are accepted on handover. Documents in OTM come in two flavors, either you provide the content of the document directly as a base64 encoded string, or you provide a link to the document where it can be accessed online.

Operations

Get a specific Document by its UUID

Request

Security
BearerToken
Path
UUIDstring, (uuid)required

The unique UUID of this Document

curl -i -X GET \
  'https://otm-api-spec.redocly.app/_mock/api/5.9/otm/api/v5/documents/{UUID}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Returned the entity with the provided UUID

Bodyapplication/json
entityTypestring
Value:"document"
Example:"document"
idstring

Uniquely identifies this entity. A URI can be assigned by the client to indicate where more information can be retrieved. Note that every entity always has a unique EntityId. However since, OTM5.2 it is not required to send it in the request. One can be generated for you by the server.

Example:"cf32da57-5edc-4c46-9a97-58c97ae27cf8"
namestring

Name of the entity. For display purposes and search only.

Example:"Photo of the PoD"
creationDatestring, (date-time)

The creation date of this entity.

lastModifiedstring, (date-time)

The last modified date of this entity. If none is given the creation date is used instead.

contextEventsArray of any(event)

The context events provides some optional information about the events that can provide additional information on the current state of this entity.

For example: your system might send ETA information for the arrival of a vehicle on a location. To make it clear what caused this ETA to be updated, we can include some information about what caused this ETA update by including an event as context. If your ETA update was caused by a location update, this event can be included as context. If the ETA was caused by a traffic accident on the route of the vehicle, you can include that event in the context.

contentany(content)required
Example:
{
  "uri": "https://link-to-the-actual-document.org/1234",
  "contentType": "link"
}
externalAttributesobject

External attributes are a simple way to add information in an OpenTripModel message that could not fit into one of the OTM fields otherwise. The externalAttributes member is meant for additional meta data and/or additional ID's of an entity. This can also help to identify an OTM entity in a system by the ID of that system.

Please, use this with caution: having too many external attributes can be a sign of not using OpenTripModel as it was intended.

Example:
{
  "externalID": "photo1234"
}
externalIdentifiersArray of objects(externalIdentifiers)

Standardized identifiers of this entity as known in external systems. Use this to exchange repeatable partner or system specific identifiers without overloading externalAttributes.

Example:
[
  {
    "id": "AAA",
    "scheme": "CAS"
  }
]
documentTypestring

The type of the document, such as a photo, text document, PDF etc.

Example:"photo"
filenamestring

The name of the file.

Example:"my_photo.JPG"
mimeTypestring

The official MIME type of the file. See Wikepedia for more information.

Example:"image/jpeg"
descriptionstring

The description of the file, for example what purpose it serves.

Example:"Proof that the goods are delivered by providing the photo that captures the moment"
creatorany
Example:
{
  "uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
  "entityType": "actor",
  "associationType": "reference"
}
ownerany
Example:
{
  "uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
  "entityType": "actor",
  "associationType": "reference"
}
Response
{
  "id": "cf32da57-5edc-4c46-9a97-58c97ae27cf8",
  "name": "Photo of the PoD",
  "content": {
    "uri": "https://link-to-the-actual-document.org/1234",
    "contentType": "link"
  },
  "externalAttributes": {
    "externalID": "photo1234"
  },
  "documentType": "photo",
  "filename": "my_photo.JPG",
  "mimeType": "image/jpeg",
  "description": "Proof that the goods are delivered by providing the photo that captures the moment",
  "creator": {
    "uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
    "entityType": "actor",
    "associationType": "reference"
  },
  "owner": {
    "uuid": "655a2a4e-79b1-4637-9f13-b904730022ef",
    "entityType": "actor",
    "associationType": "reference"
  }
}