Archivos por el Gateway

Tu workspace guarda archivos, y tu app necesita ponerlos ahí y recuperarlos. El gateway expone cuatro operaciones para eso, bajo una sola ruta:

https://gateway.praxsuite.com/{workspaceId}/files

Se autentican como todo lo demás del gateway: una API key, o el JWT de un usuario final.

Las cuatro operaciones

Subir devuelve el blob id, y ese id es el punto entero: es lo que ponés en una columna de tipo File cuando escribís una fila.

{
  "refs": { "Documentos": "…" },
  "mutation": {
    "type": "insert",
    "table": "Documentos",
    "values": [{ "Titulo": "Contrato", "Adjunto": "<blob-id>" }]
  }
}

Un archivo no necesita pertenecer a una fila para existir. Subí primero, adjuntá después, o nunca — un blob huérfano es algo perfectamente válido mientras un usuario todavía está completando un formulario.

Dos cosas que el gateway rechaza

Archivos de otro workspace. Toda operación resuelve el blob dentro del workspace de la ruta, así que un id válido de otro lado responde 404, no 403. No hay acceso cross-workspace a archivos que se pueda configurar mal.

URLs crudas del almacenamiento. El backend hace de proxy de todo el contenido. Quienes te llaman nunca reciben una dirección que apunte al almacenamiento subyacente, lo que significa que el acceso se puede revocar y no se puede compartir por accidente.

Las subidas además se contrastan con el límite de tamaño de tu plan y una lista de extensiones permitidas, y los dos rechazos dicen el límite real en vez de fallar sin explicación.

Cómo vuelven las URLs de archivo en los resultados

Cuando una consulta devuelve una columna File o Image, lo que recibís depende del FileUrlMode de la credencial que llama:

Proxy mantiene todo acceso a archivo detrás del mismo chequeo de permisos que la fila que lo referenció. Es el default seguro, y es lo que querés para cualquier cosa privada.

SasUrl lo cambia por URLs que un navegador puede cargar sin credenciales — necesario para una galería pública, y exactamente equivocado para un contrato o el escaneo de un documento de identidad, porque cualquiera con la URL puede abrirla hasta que venza.

FileSasExpiryMinutes viene en 60, con piso de 5 minutos y techo de 7 días. Mantenelo corto. Una vez que una URL prefirmada sale de tu página, su vencimiento es lo único que la sigue limitando.

Esto se define por credencial, así que una key pública de solo lectura puede servir imágenes directo mientras tu key de backend mantiene todo por proxy.

Cómo elegir

¿Te molestaría que esta URL se reenviara a alguien que no está logueado? Si sí, quedate en Proxy.

Fotos de producto, avatares y material público de marketing están bien en SasUrl. Cualquier cosa que una persona subió sobre sí misma, no.

Siguiente

• Credenciales y Principales — dónde se configura FileUrlMode.

• Mutaciones — escribir un blob id en una fila.