1. Trans.eu Api
  2. Use cases
  3. Integration scenarios
  4. Uploading files and adding files as an attachment to an order

Uploading files and adding files as an attachment to an order

Descrip­tion of usage of APIs to upload a file, attach­ing it to an order, down­load­ing an order attach­ment, as well as delet­ing an attach­ment from an order. 

Scenario

  • Car­ri­er and ship­per are both present on Trans.eu plat­form
  • The Ship­per has assigned an Order to a Car­ri­er
  • The Order is not can­celled nor archived

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

Uploading attachments

Before a file can be added to an order as an attach­ment, it has to be uploaded via the fol­low­ing end­point to be iden­ti­fied with a media_id.

Endpoint

PUT https://api.platform.trans.eu/ext/media-storage-api/v1/assets

The endpoint’s con­tent type is mul­ti­part/­form-data, and the avail­able file types are list­ed below:

  • JPG, GIF, PNG, BMP, PDF, ODT, DOC, TXT, DOCX, TIFF, ODS, XLS, XLSX, PPT, RTF

Response:

{
    "id": "3e7272cd-e805-42c5-bd55-dd9b9a43bc38",
    "path": "https://api.media-storage.service/v1/assets/3e7272cd-e805-42c5-bd55-dd9b9a43bc38",
    "ttl": {
        "validTime": "not specified",
        "expirationDate": null
    },
    "file": {
        "etag": "\"1a9f3ffe9b03568b7d65b5436431a38f\"",
        "size": 43543,
        "type": "image/jpeg",
        "name": "cargo_photo.jpg",
        "hash": {
            "md5": "1a9f3ffe9b03568b7d65b5436431a38f",
            "sha256": "390e2f4af92946e773fe0cdef6c25f694ae6844290cfb411daea8f677237b072"
        },
        "permissions": {
            "isPublic": true,
            "acl": {
                "1158167": "OWNER",
                "public": "READER",
                "guest": "READER"
            }
        },
        "image": {
            "width": 363,
            "height": 471
        }
    }
}

Adding uploaded attachment to order

The uploaded file can be added as an attach­ment to the order via the fol­low­ing end­point. The end­point has the orderId as a path vari­able — the orderId can be obtained from the response of the end­point here (if ship­per) and here (if car­ri­er).

Endpoint

POST https://api.platform.trans.eu/orders-api/v1/orders/{orderId}/attachments

Example of use

https://api.platform.trans.eu/orders-api/v1/orders/{b093cdfe-12cf-4958-a5da-0170141e9c71}/attachments

Request example

{
  "media_id": "3e7272cd-e805-42c5-bd55-dd9b9a43bc38",
  "media_name": "damaged pallet",
  "type_id": "cargo_photo",
  "visible_to_contractor": true,
  "description": "goods damaged on pallet due to accident"
}

Downloading attachments

Any attach­ment of an order can be down­loaded by pro­vid­ing the medi­aId path vari­able with the fol­low­ing end­point.

Endpoint

GET https://api.platform.trans.eu/ext/media-storage-api/v1/assets/{mediaId}

The file will be pro­vid­ed in the response.

Deleting order attachments

To delete an attach­ment of an order, use the fol­low­ing end­point. This end­point requires two path vari­ables — orderId and attach­men­tId, which is the same val­ue as the afore­men­tioned media_id.

Endpoint

DELETE https://api.platform.trans.eu/orders-api/v1/orders/:orderId/attachments/:attachmentId

Example of use

https://api.platform.trans.eu/orders-api/v1/orders/{b093cdfe-12cf-4958-a5da-0170141e9c71}/attachments/{3e7272cd-e805-42c5-bd55-dd9b9a43bc38}

Impor­tant — only the user from the author com­pa­ny can remove attach­ments — for exam­ple, if a ship­per attached a file to an order, the car­ri­er is for­bid­den from remov­ing the attach­ment as well as vice ver­sa. This will result in a 403 error (For­bid­den).

Getting attachmentId

If the attach­men­tId is unknown to the user, the infor­ma­tion can be found in the response of one of the two end­points:

For ship­per:

GET https://api.platform.trans.eu/ext/orders-api/v1/orders-created/{order-id}

For car­ri­er:

GET https://api.platform.trans.eu/ext/orders-api/v1/orders-received/{order-id}

Response example

With­in the response for either of these end­points, the fol­low­ing infor­ma­tion can be found:

    "attachments": [
        {
            "author": null,
            "company": {
                "legal_name": "(P3DT) CargoON Test",
                "company_id": 1079411
            },
            "created_at": "2026-05-15T13:55:59.514Z",
            "description": "goods damaged on pallet due to accident",
            "media_id": "3e7272cd-e805-42c5-bd55-dd9b9a43bc38",
            "media_name": "damaged pallet",
            "protected": false,
            "source": "orders",
            "source_id": null,
            "type_id": "cargo_photo",
            "visible_to_contractor": true
        }
    ],

The media_id val­ue cor­re­sponds to the attach­men­tId val­ue.