Cloud Storage (Files)

Suppa API integrates with Google Cloud Storage (GCS) for file management. The process involves getting a pre-signed upload URL and then "attaching" the uploaded file to a specific entity record.

Uploading a File

The upload flow consists of 3 main steps.

Step 1: Get Upload Link

Endpoint: POST /core/cloud-storage/get-upload-links

Request Body:

[
  {
    "fileName": "receipt_photo.jpg",
    "entityId": 45,
    "recordId": 1234,
    "mimeType": "image/jpeg",
    "size": 524288
  }
]

Parameters:

• entityId: The system ID of the entity type (e.g., Products, Receipts). You can obtain this ID using the Entity Metadata endpoint.
• recordId: The ID of the specific record (instance) to which you want to attach the file.

Response Body:

[
  {
    "uploadUrl": "https://storage.googleapis.com/...",
    "fileName": "receipt_photo.jpg",
    "filePath": "59/2141/53f47904-14e5-44fa-947a-1b6824ed9a71"
  }
]

Step 2: Upload to GCS

Perform a PUT request directly to the uploadUrl provided in Step 1.

Header	Value
Content-Type	image/jpeg (matching mimeType)
x-upload-content-length	524288 (matching size)

Step 3: Attach to Record

After the file is successfully uploaded to GCS, use this endpoint to link it to the entity field.

Endpoint: POST /core/files/attach

Request Body:

{
  "entityId": 59,
  "recordId": 2141,
  "entityFieldName": "image",
  "files": [
    {
       "uploadUrl": "https://storage.googleapis.com/...",
       "filePath": "59/2141/53f47904-14e5-44fa-947a-1b6824ed9a71",
       "fileName": "receipt_photo.jpg",
       "mimeType": "image/jpeg",
       "size": 524288
    }
  ]
}

Parameters:

• entityFieldName: The name of the field in the entity where the file should be stored (e.g., image for the Products entity, frontalPhotos for Receipts).
• files: An array of file objects. These are the exact objects received in the response from Step 1: Get Upload Link.

Downloading a File

Step 1: Get Download Link

Endpoint: POST /core/cloud-storage/get-download-links

Request Body:

[
  {
    "fileName": "receipt_photo.jpg",
    "filePath": "entities/Receipts/1234/receipt_photo.jpg"
  }
]

Response Body:

[
  {
    "downloadUrl": "https://storage.googleapis.com/...",
    "fileName": "receipt_photo.jpg"
  }
]

Step 2: Download

Perform a GET request to the returned URL.

Remove Files

Delete one or more files from the system.

Endpoint: POST /core/data/Files/remove

Request Body:

{
  "conditions": {
    "operator": "and",
    "filters": [
      {
        "field": "id",
        "comparator": "in",
        "value": [10, 11]
      }
    ]
  }
}