Get file upload credentials

post

https://app.fracttal.com/api/s3_object/

Generates the temporary signed credentials required to upload a file (image or document) to Fracttal storage. This is the first step of the process to attach files to a record, and it is generic: it can be reused from any module that supports attachments.

Input parameters

Required

Parameter	Type	Required	Description
`name`	text	Yes	File name, including its extension (for example `informe.pdf`). The extension must be in the list of allowed extensions. The final value under which the file is stored is returned in `data.key`.

Optional

Parameter	Type	Required	Description
`size`	integer	No	File size in bytes. It must be sent if you later want to associate the file with a record; otherwise, that step responds `FILE_NOT_FOUND`. It must fit within the company's available storage capacity.

Allowed extensions: json, swf, flv, f4v, sldprt, sldasm, csv, pdf, gif, jpg, jpeg, jpe, jif, bmp, tif, tiff, png, mp4, mov, wmv, avi, mp3, doc, docx, xml, xls, xlsx, txt, ppt, pptx, dwg, eml, msg, iam, ipt, cad, rar, zip, 7z.

Maximum size per file: 100,490,000 bytes (approximately 100 MB).

How to upload the file (step 2)
This service does not upload the file: it only returns the credentials. To upload it:

Call this service with the file's name and size.

With the response, send a POST request of type multipart/form-data to the URL given in host, including the fields in the table below. The file field, with the file content, must always be last.

The credentials expire 2 hours after being generated. After that, you must request new ones.

The key value is the one used afterwards to associate the file with the corresponding record (for example, in Associate attachments to a work request).

Form field	Value
`key`	`key` value from the response.
`acl`	`acl` value from the response.
`policy`	`policy` value from the response.
`x-amz-credential`	`credential` value from the response.
`x-amz-algorithm`	`AWS4-HMAC-SHA256`
`x-amz-date`	`date` value from the response.
`x-amz-signature`	`signature` value from the response.
`success_action_status`	`200`
`file`	File content. It must be the last field.

Output parameters

Parameter	Type	Description
`success`	boolean	Indicates whether the operation was successful.
`message`	text	Result of the operation (`ACTION_DONE` if successful).
`data`	object	Upload credentials. See structure in the following table.
`total`	integer	Number of elements returned.

Structure of data:

Parameter	Type	Description
`key`	text	Path of the file in storage (`company_<id>/<name>`). It is the value used afterwards to associate it with a record.
`bucket`	text	Destination storage container.
`host`	text	URL to which the upload request must be sent.
`public_key`	text	Public access key.
`credential`	text	Signature credential. Sent in the `x-amz-credential` field.
`signature`	text	Upload signature. Sent in the `x-amz-signature` field.
`policy`	text	Signed upload policy, in base64. It expires after 2 hours.
`acl`	text	Access level with which the file is stored.
`redirect`	text	Additional field returned by the service. It is not needed for the upload.
`date`	text	Signature generation date. Sent in the `x-amz-date` field.

Errors

Code	Cause
`400`	`FILE_NOT_ALLOWED`: the file extension is not allowed, or `name` is empty.
`400`	`INSUFFICIENT_STORAGE_CAPACITY`: the company does not have enough storage capacity.
`400`	`body is required`: the request body was not sent.
`400`	`The request is poorly formed`: the request does not include the `Authorization` header.
`401`	`INVALID_TOKEN`: the token is invalid.

When the operation fails, the response includes success: false and the error code in message.

Example

Request body

{
  "name": "informe-mantenimiento.pdf",
  "size": 245760
}

Response `200`

{
  "success": true,
  "message": "ACTION_DONE",
  "data": {
    "key": "company_1234/informe-mantenimiento.pdf",
    "bucket": "ejemplo-bucket",
    "host": "https://ejemplo-bucket.s3.amazonaws.com",
    "public_key": "EXAMPLEPUBLICKEY123",
    "credential": "EXAMPLEPUBLICKEY123/20261013/us-east-1/s3/aws4_request",
    "signature": "3f1c0b7a9d2e4c5f8a6b1d0e9c7a5b3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b",
    "redirect": "",
    "acl": "private",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0xMC0xM1QxNDowMDowMFoifQ==",
    "date": "20261013T000000Z"
  },
  "total": 0
}

Response — File extension not allowed (`400`)

{
  "success": false,
  "message": "FILE_NOT_ALLOWED",
  "data": [],
  "total": 0
}

Response — Insufficient storage capacity (`400`)

{
  "success": false,
  "message": "INSUFFICIENT_STORAGE_CAPACITY",
  "data": [],
  "total": 0
}

Response — Invalid token (`401`)

{
  "success": false,
  "message": "INVALID_TOKEN",
  "data": [],
  "total": 0
}

OpenAPI definition

{
  "openapi": "3.1.0",
  "info": {
    "title": "s3_object",
    "version": "2-En"
  },
  "servers": [
    { "url": "https://app.fracttal.com/api/s3_object" }
  ],
  "security": [{}],
  "paths": {
    "/": {
      "post": {
        "summary": "Get file upload credentials",
        "description": "",
        "operationId": "get-file-upload-credentials",
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}

Language

Loading…