Archivos

Toda URL de archivo que entrega Praxsuite apunta al gateway, nunca al proveedor de almacenamiento que está debajo. El contenido se transmite por estas rutas, así que nada de tu producto queda atado a la nube de turno, y un "copiar dirección de la imagen" nunca filtra una URL del proveedor.

Auth: API key o JWT de usuario final — con dos excepciones en la descarga, abajo.

Listar

GET /{workspaceId}/files

{
  "files": [
    { "id": "…", "name": "factura-2026-01", "extension": ".pdf", "createdDate": "2026-01-14T09:22:11Z" }
  ]
}

Más recientes primero, tope de 500, y no hay paginación. Para algo más grande, lleva tu propio índice en una tabla.

Subir

POST /{workspaceId}/files/upload
Content-Type: multipart/form-data

Un solo campo, llamado file.

curl -X POST https://gateway.praxsuite.com/{workspaceId}/files/upload \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@factura.pdf"

{
  "id": "…",
  "name": "factura",
  "extension": ".pdf",
  "size": 48213,
  "createdDate": "2026-01-14T09:22:11Z"
}

Guárdate el id: es lo que almacena una columna de tipo File, como valor uuid[] en una mutación.

El tamaño lo topea el plan del workspace, y pasarse es un 400 que nombra el límite en MB.

La extensión se contrasta contra una lista fija, y cualquier otra cosa es 400:

.pdf .doc .docx .xls .xlsx .ppt .pptx · .txt .csv .json .xml .html .htm · .png .jpg .jpeg .gif .webp .svg .ico · .zip .rar .7z .tar .gz · .mp4 .mov .avi .mp3 .wav .ogg · .py .js .ts .cs .java .go .rs .rb

El nombre visible se deriva del archivo subido, sin la ruta y cortado a 100 caracteres.

Descargar

GET /{workspaceId}/files/{blobId}

Devuelve los bytes, transmitidos, con el content type almacenado y el nombre original. No es una redirección.

Tres maneras de pasar, y alcanza con cualquiera:

1. El blob está marcado como público. Se sirve con Cache-Control: public, max-age=300.

2. El enlace viene firmado — ?exp=…&sig=… en la URL. Esto es lo que hace usable un archivo desde un <img src>, un correo o un webhook, ninguno de los cuales puede mandar una cabecera de autenticación.

3. Quien llama está autenticado de la forma habitual. Se sirve con Cache-Control: private, max-age=60.

Si no, 401.

Obtener una URL para repartir

GET /{workspaceId}/files/{blobId}/url?expiresMinutes=60

{
  "id": "…",
  "name": "factura",
  "url": "https://gateway.praxsuite.com/{workspaceId}/files/{blobId}?ttl=60&exp=…&sig=…",
  "expiresAt": "2026-01-14T10:22:11Z",
  "ttlMinutes": 60
}

expiresMinutes se acota a 5–1440 (24 horas); el valor por defecto es 60. El techo de un día es a propósito: una firma que sobrevive a la revocación de un acceso deja de ser revocable en la práctica.

La URL devuelta es una URL de Praxsuite. La puedes guardar en una fila o pegarla en un documento — es la dirección estable del archivo, y lo que vence es la firma que lleva encima.

Borrar

DELETE /{workspaceId}/files/{blobId}

{ "deleted": true, "id": "…" }

Elimina el objeto almacenado y su registro. No hay deshacer ni papelera.

Errores

La forma plana —{ "error": "…" }.