Obtener credenciales de subida de archivos

post

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

Genera las credenciales firmadas temporales necesarias para subir un archivo (imagen o documento) al almacenamiento de Fracttal. Es el primer paso del proceso para adjuntar archivos a un registro, y es genérico: puede reutilizarse desde cualquier módulo que admita adjuntos.

Parámetros de entrada

Requeridos

Parámetro	Tipo	Requerido	Descripción
`name`	texto	Sí	Nombre del archivo, incluida su extensión (por ejemplo `informe.pdf`). La extensión debe estar en la lista de extensiones permitidas. El valor final con el que queda almacenado el archivo se devuelve en `data.key`.

Opcionales

Parámetro	Tipo	Requerido	Descripción
`size`	entero	No	Tamaño del archivo en bytes. Es necesario enviarlo si después va a asociar el archivo a un registro; de lo contrario, ese paso responde `FILE_NOT_FOUND`. Debe caber en la capacidad de almacenamiento disponible de la compañía.

Extensiones permitidas: 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.

Tamaño máximo por archivo: 100.490.000 bytes (aproximadamente 100 MB).

Cómo subir el archivo (paso 2)
Este servicio no sube el archivo: solo entrega las credenciales. Para subirlo:

Llame a este servicio con el name y el size del archivo.

Con la respuesta, haga una petición POST de tipo multipart/form-data a la URL indicada en host, enviando los campos de la tabla siguiente. El campo file, con el contenido del archivo, debe ir siempre al final.

Las credenciales expiran a las 2 horas de ser generadas. Pasado ese tiempo es necesario solicitar unas nuevas.

El valor de key es el que se usa después para asociar el archivo al registro correspondiente (por ejemplo, en Asociar adjuntos a una solicitud de trabajo).

Campo del formulario	Valor
`key`	Valor de `key` de la respuesta.
`acl`	Valor de `acl` de la respuesta.
`policy`	Valor de `policy` de la respuesta.
`x-amz-credential`	Valor de `credential` de la respuesta.
`x-amz-algorithm`	`AWS4-HMAC-SHA256`
`x-amz-date`	Valor de `date` de la respuesta.
`x-amz-signature`	Valor de `signature` de la respuesta.
`success_action_status`	`200`
`file`	Contenido del archivo. Debe ser el último campo.

Parámetros de salida

Parámetro	Tipo	Descripción
`success`	booleano	Indica si la operación fue exitosa.
`message`	texto	Resultado de la operación (`ACTION_DONE` si fue exitosa).
`data`	objeto	Credenciales de subida. Ver estructura en la tabla siguiente.
`total`	entero	Cantidad de elementos devueltos.

Estructura de data:

Parámetro	Tipo	Descripción
`key`	texto	Ruta del archivo en el almacenamiento (`company_<id>/<name>`). Es el valor que se usa después para asociarlo a un registro.
`bucket`	texto	Contenedor de almacenamiento destino.
`host`	texto	URL a la que se debe enviar la petición de subida.
`public_key`	texto	Llave pública de acceso.
`credential`	texto	Credencial de la firma. Se envía en el campo `x-amz-credential`.
`signature`	texto	Firma de la subida. Se envía en el campo `x-amz-signature`.
`policy`	texto	Política de subida firmada, en base64. Expira a las 2 horas.
`acl`	texto	Nivel de acceso con el que se almacena el archivo.
`redirect`	texto	Campo adicional devuelto por el servicio. No es necesario para la subida.
`date`	texto	Fecha de generación de la firma. Se envía en el campo `x-amz-date`.

Errores

Código	Causa
`400`	`FILE_NOT_ALLOWED`: la extensión del archivo no está permitida, o `name` está vacío.
`400`	`INSUFFICIENT_STORAGE_CAPACITY`: la compañía no tiene capacidad de almacenamiento suficiente.
`400`	`body is required`: no se envió el cuerpo de la petición.
`400`	`The request is poorly formed`: la petición no incluye el encabezado `Authorization`.
`401`	`INVALID_TOKEN`: el token es inválido.

Cuando la operación falla, la respuesta incluye success: false y el código de error en message.

Ejemplo

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 — Extensión no permitida (`400`)

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

Response — Capacidad de almacenamiento insuficiente (`400`)

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

Response — Token inválido (`401`)

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

OpenAPI definition

{
  "openapi": "3.1.0",
  "info": {
    "title": "s3_object",
    "version": "1-Es"
  },
  "servers": [
    { "url": "https://app.fracttal.com/api/s3_object" }
  ],
  "security": [{}],
  "paths": {
    "/": {
      "post": {
        "summary": "Obtener credenciales de subida de archivos",
        "description": "",
        "operationId": "obtener-credenciales-de-subida-de-archivos",
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}

Language

Loading…