Assets (Admin)

Assets are media resources that can be used inside commerce entities ecosystem, like images or videos.

We don't export an endpoint to upload assets directly by our api as we use some 3rd party service provider like Cloudinary to maintain that assets in the web. So, to upload some asset and use it into your products, you must create an asset upload request using this module which will give to you all needed informations to upload your media asset directly using the Cloudinary API.

Assets are maintained by commerce service and have its lifecycle. So, when you request to upload some asset, you must keep in mind some things:

• The signature that you will receive to upload expires in 1 hour.

  • After that time, if you don't upload anything to Cloudinary using that signature, your asset will be expired and you will need to get a new asset signature.

• Uploaded assets must be associated to some product at maximum 3 days after the upload.

  • If the uploaded asset was not associated, it will be automatically removed and the asset will expire

• Assets that are unassociated from all products (after some time of use) are automatically removed

  • If you have more than one product associated to the same asset, don't worry. We just remove assets that are not associated to anything.

Asset Model (Example)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2022-11-04T10:31:50.112Z",
  "updatedAt": "2022-11-04T10:31:50.112Z",
  "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "type": "image",
  "status": "waiting_upload",
  "provider": "cloudinary",
  "directLink": "https://dummyimage.com/200x200/fff/000",
  "providerUploadParams": {
    "apiKey": "000000000000",
    "timestamp": 1666215568,
    "publicId": "commerce/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "signature": "bfd09f95f331f558cbd1320e67aa8d488770583e",
    "signedParams": "filename_override=false&public_id=commerce/3fa85f64-5717-4562-b3fc-2c963f66afa6&timestamp=1666215568&unique_filename=true",
    "queryParams": {
      "filename_override": "false",
      "public_id": "commerce/3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "timestamp": "1666215568",
      "unique_filename": "true"
    }
  }
}

Service Methods

Create asset and get upload request signature

Remember to inform all signed query params into your Cloudinary request, otherwise your signature will be not valid.

Rest API reference:

post

Creates a new request to upload some asset (image or video) in our service. You must use this endpoint response to upload assets using the specific provider apis (ex: Cloudinary)

Authorizations

bearerx-w3block-api-keyx-w3block-idx-w3block-secret

Path parameters

companyIdstringRequired

Body

typestring · enumRequiredDefault: imageExample: imagePossible values:

targetstring · enumRequiredExample: productPossible values:

Responses

201

Asset upload request successfully created!

application/json

401

User doesn't have any of the expected roles: administrator, admin, superAdmin, integration

post

HTTPcURLJavaScriptPython

POST /admin/companies/{companyId}/assets HTTP/1.1
Host: commerce.w3block.io
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "type": "image",
  "target": "product"
}

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "createdAt": "2025-07-15T21:31:13.390Z",
  "updatedAt": "2025-07-15T21:31:13.390Z",
  "companyId": "123e4567-e89b-12d3-a456-426614174000",
  "company": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "createdAt": "2025-07-15T21:31:13.390Z",
    "updatedAt": "2025-07-15T21:31:13.390Z",
    "name": "text"
  },
  "type": "image",
  "status": "associated",
  "provider": "cloudinary",
  "directLink": "https://dummyimage.com/200x200/fff/000",
  "target": "product",
  "providerUploadParams": {
    "apiKey": "000000000000",
    "timestamp": 1666215568,
    "publicId": "commerce/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "signature": "bfd09f95f331f558cbd1320e67aa8d488770583e",
    "signedParams": "filename_override=false&public_id=commerce/3fa85f64-5717-4562-b3fc-2c963f66afa6&timestamp=1666215568&unique_filename=true",
    "queryParams": {
      "filename_override": "false",
      "public_id": "commerce/3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "timestamp": "1666215568",
      "unique_filename": "true"
    }
  }
}