Obter credenciais de upload de arquivos

post

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

Gera as credenciais assinadas temporárias necessárias para fazer upload de um arquivo (imagem ou documento) no armazenamento da Fracttal. É o primeiro passo do processo para anexar arquivos a um registro, e é genérico: pode ser reutilizado a partir de qualquer módulo que aceite anexos.

Parâmetros de entrada

Obrigatórios

Parâmetro	Tipo	Obrigatório	Descrição
`name`	texto	Sim	Nome do arquivo, incluindo sua extensão (por exemplo `informe.pdf`). A extensão deve estar na lista de extensões permitidas. O valor final com o qual o arquivo fica armazenado é devolvido em `data.key`.

Opcionais

Parâmetro	Tipo	Obrigatório	Descrição
`size`	inteiro	Não	Tamanho do arquivo em bytes. É necessário enviá-lo se depois for associar o arquivo a um registro; caso contrário, essa etapa responde `FILE_NOT_FOUND`. Deve caber na capacidade de armazenamento disponível da empresa.

Extensões 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.

Tamanho máximo por arquivo: 100.490.000 bytes (aproximadamente 100 MB).

Como fazer o upload do arquivo (passo 2)
Este serviço não faz o upload do arquivo: apenas entrega as credenciais. Para fazer o upload:

Chame este serviço com o name e o size do arquivo.

Com a resposta, faça uma requisição POST do tipo multipart/form-data para a URL indicada em host, enviando os campos da tabela a seguir. O campo file, com o conteúdo do arquivo, deve ir sempre por último.

As credenciais expiram 2 horas após serem geradas. Depois desse prazo é necessário solicitar novas.

O valor de key é o que se usa depois para associar o arquivo ao registro correspondente (por exemplo, em Associar anexos a uma solicitação de trabalho).

Campo do formulário	Valor
`key`	Valor de `key` da resposta.
`acl`	Valor de `acl` da resposta.
`policy`	Valor de `policy` da resposta.
`x-amz-credential`	Valor de `credential` da resposta.
`x-amz-algorithm`	`AWS4-HMAC-SHA256`
`x-amz-date`	Valor de `date` da resposta.
`x-amz-signature`	Valor de `signature` da resposta.
`success_action_status`	`200`
`file`	Conteúdo do arquivo. Deve ser o último campo.

Parâmetros de saída

Parâmetro	Tipo	Descrição
`success`	booleano	Indica se a operação foi bem-sucedida.
`message`	texto	Resultado da operação (`ACTION_DONE` se bem-sucedida).
`data`	objeto	Credenciais de upload. Ver estrutura na tabela a seguir.
`total`	inteiro	Quantidade de elementos devolvidos.

Estrutura de data:

Parâmetro	Tipo	Descrição
`key`	texto	Caminho do arquivo no armazenamento (`company_<id>/<name>`). É o valor usado depois para associá-lo a um registro.
`bucket`	texto	Contêiner de armazenamento de destino.
`host`	texto	URL para a qual a requisição de upload deve ser enviada.
`public_key`	texto	Chave pública de acesso.
`credential`	texto	Credencial da assinatura. Enviada no campo `x-amz-credential`.
`signature`	texto	Assinatura do upload. Enviada no campo `x-amz-signature`.
`policy`	texto	Política de upload assinada, em base64. Expira após 2 horas.
`acl`	texto	Nível de acesso com o qual o arquivo é armazenado.
`redirect`	texto	Campo adicional devolvido pelo serviço. Não é necessário para o upload.
`date`	texto	Data de geração da assinatura. Enviada no campo `x-amz-date`.

Erros

Código	Causa
`400`	`FILE_NOT_ALLOWED`: a extensão do arquivo não é permitida, ou `name` está vazio.
`400`	`INSUFFICIENT_STORAGE_CAPACITY`: a empresa não tem capacidade de armazenamento suficiente.
`400`	`body is required`: o corpo da requisição não foi enviado.
`400`	`The request is poorly formed`: a requisição não inclui o cabeçalho `Authorization`.
`401`	`INVALID_TOKEN`: o token é inválido.

Quando a operação falha, a resposta inclui success: false e o código de erro em message.

Exemplo

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 — Extensão não permitida (`400`)

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

Response — Capacidade de armazenamento 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": "3-pt"
  },
  "servers": [
    { "url": "https://app.fracttal.com/api/s3_object" }
  ],
  "security": [{}],
  "paths": {
    "/": {
      "post": {
        "summary": "Obter credenciais de upload de arquivos",
        "description": "",
        "operationId": "obter-credenciais-de-upload-de-arquivos",
        "deprecated": false,
        "security": []
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": false,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}

Language

Loading…