Securely Uploading .p7m file(s)

POST /api/v1/presigned-url

The /api/v1/presigned-url endpoint of the Cauzioni Smart platform is designed to facilitate the secure upload of digitally signed files for guarantees. This endpoint generates a presigned URL, allowing for a direct and secure file upload to the platform’s storage solution without exposing sensitive credentials or storage details.

Purpose

Before creating a digital guarantee, the signed document must be uploaded to the Cauzioni Smart platform. This endpoint automates the generation of a secure, temporary URL for this purpose. It streamlines the process, ensuring both security and efficiency in handling the digital guarantees.

Requesting a Presigned URL

To generate a presigned URL for uploading a file, send a POST request to the /api/v1/presigned-url endpoint. This request must include the Authorization header with your API key and a JSON payload specifying the type of file you intend to upload. The Content-Type header should be set to application/json to indicate the nature of the request body.

Headers:

• Authorization: YOUR_API_KEY

Request Body:

The request body must include a fileType field specifying the type of the file. For example, to generate a presigned URL for a p7m file, the fileType should be set to p7m.

{
  "fileType": "p7m"
}

Response

The response from this endpoint includes the presigned URL, additional required fields for the upload, the file type, and the key associated with the upload session. Below is a description of each component in the response:

• presignedUrl: The URL to which the file should be uploaded.
• fields: Additional fields required by the storage service to accompany the upload request.
• fileType: Indicates the type of file that is expected to be uploaded. In the production environment, this will always be .p7m.
• key: The unique identifier for the uploaded file in the storage system.

Example Response

{
  "statusCode": 200,
  "body": {
    "presignedUrl": "https://example-url.com/upload",
    "fields": {
      "Policy": "xyz",
      "X-Amz-Algorithm": "AWS4-HMAC-SHA256"
    },
    "fileType": ".p7m",
    "key": "unique-file-key"
  },
  "headers": {
    "Content-Type": "application/json"
  }
}

File Upload Requirements

• Staging Environment: There are no restrictions on the type of files that can be uploaded. This flexibility facilitates testing and development processes.
• Production Environment: Only files with a .p7m extension are accepted. This requirement ensures that only properly signed and secure documents are processed for digital guarantees.

Uploading a File

Once you receive the presigned URL and additional fields, you can proceed to upload your file. Ensure the file type meets the environment-specific requirements to prevent any errors during the upload process.

For detailed instructions on how to upload files using a presigned URL, refer to the AWS S3 documentation on presigned URLs.

JavaScript Example Using Axios

const formData = new FormData();

// Assuming 'data' is the response from the `/api/v1/presigned-url` or /api/v2/presigned-url endpoint
Object.keys(data.fields).forEach((key) => {
  formData.append(key, data.fields[key]);
});

// Append the file to be uploaded with the key 'file'
formData.append('file', file); // 'file' is your file object

await axios.post(data.presignedUrl, formData, {
  headers: { 'Content-Type': 'multipart/form-data' }
});

In this example, data represents the JSON response received from the presigned URL endpoint, and file is the file object you wish to upload. This method involves iterating over the fields provided in the response and appending them to a FormData object along with the file.

cURL Example

To upload a file using cURL, you need to construct a similar multipart/form-data request. Here’s an example based on the fields and presigned URL received:

curl -X POST 'PRESIGNED_URL_RECEIVED_FROM_API' \
  -F 'key=VALUE_FROM_FIELDS' \
  -F 'X-Amz-Algorithm=VALUE_FROM_FIELDS' \
  -F 'X-Amz-Credential=VALUE_FROM_FIELDS' \
  -F 'X-Amz-Date=VALUE_FROM_FIELDS' \
  -F 'Policy=VALUE_FROM_FIELDS' \
  -F 'X-Amz-Signature=VALUE_FROM_FIELDS' \
  -F 'file=@/path/to/your/file.jpeg' \
  -H 'Content-Type: multipart/form-data'