File Upload

Endpoints

Method	Endpoint	Description
POST	/api/v202206/files	Upload an attachment file to ShipSage storage and get a reusable URL

[NEW] v202608 Patch (2026-09): This documentation page is new. The endpoint itself is a v202206 utility that was previously not listed in this API directory; it is now documented here because every attach-file API (POST /asn-docs, POST /vas-docs, POST /transfer-docs, and POST /transfers embedded shipments.documents) requires the url returned from this endpoint.
Purpose: The url parameter accepted by all attach-file APIs must first be produced by this endpoint. Any external / third-party URL will be rejected.

Header

Key	Value
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...
Content-Type	multipart/form-data

POST /api/v202206/files (Upload attachment file)

Upload a single file to the ShipSage public storage bucket and receive a publicly reachable URL that can be persisted. The returned URL can be used as the url field in the ASN / VAS / Transfer attach-doc endpoints.

Storage & accessibility notes:

The file lands under the company 0 public directory. The returned URL resolves through the "public file redirect to signed S3" path — anyone holding the URL (no auth token needed) can download the file. This is exactly what lets the warehouse print it days later.

The URL is long-lived; it does not expire, so it is safe to persist.

If you need stronger privacy for private storage, contact ShipSage. This endpoint is intended for "share-by-URL" attachments (files meant to be attached to ASN / VAS / Transfer orders and read by the warehouse).

Request

Params

Type	Name	Description	Required/Optional	Schema
query	api	The API type Available Values: store.by-upload	required	enum
formData	file	The file to upload (`file` part in `multipart/form-data`, binary stream)	required	file
formData	file_name	Custom storage file name. If omitted, the original file name is used. Use this to avoid collisions or normalise naming.	optional	string

Constraints:

Request header Content-Type must be multipart/form-data

The file field carries the binary file stream, not a base64 string

Allowed extensions and file-size limits follow the global ShipSage server configuration (contact ShipSage if a file is rejected)

Request Example

POST /api/v202206/files?api=store.by-upload
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="bol.pdf"
Content-Type: application/pdf

<binary PDF content>
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file_name"

bol-transfer-12345.pdf
------WebKitFormBoundary7MA4YWxkTrZu0gW--

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
url	The absolute URL of the uploaded file. The domain is under ShipSage (`.shipsage.com` / `.shipsage.cn` / `.gaatu.com` / `.jootop.com`) and the path starts with `/uploads/`. Pass this URL as-is to the `url` parameter of `POST /asn-docs` / `POST /vas-docs` / `POST /transfer-docs`.	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "url": "https://app.shipsage.com/uploads/0/2026/09/bol-transfer-12345.pdf"
    }
}

Typical Usage Flow

Attaching a BOL to a Transfer order takes two steps:

Step 1: Upload the file, receive a URL

POST /api/v202206/files?api=store.by-upload
Content-Type: multipart/form-data
(`file` field carries the bol.pdf binary)

Response:
{ "errcode": 0, "errmsg": "ok", "data": { "url": "https://app.shipsage.com/uploads/0/2026/09/bol.pdf" } }

Step 2: Attach the URL to the Transfer order

POST /api/v202608/transfer-docs?api=store.by-default
Content-Type: application/json

{
    "transfer_id": 12345,
    "type_id": 3,
    "url": "https://app.shipsage.com/uploads/0/2026/09/bol.pdf",
    "doc_name": "bol.pdf"
}

Why ShipSage storage is mandatory: These attachments are printed by the warehouse days later (BOL, carton labels, etc.). If they pointed to a customer's own server or a third-party link, the link could be down or broken by then — ShipSage cannot foresee or fix it, and would only discover the problem at print time. To avoid that failure mode, attachments must be pre-uploaded to ShipSage storage where they will remain accessible via a long-lived public URL.

Endpoints#

Header#

POST /api/v202206/files (Upload attachment file)#

Request#

Params#

Request Example#

Response#

Data Properties#

Response Example#

Typical Usage Flow#