Descargar archivos de entrada

Una vez que los archivos de entrada se han subido y finalizado, puedes volver a descargarlos a través de la API.

Se da por supuesto que tienes un bundle con archivos de entrada finalizados y que dispones del ámbito read:bundle.

---

Cómo funciona

El endpoint de descarga devuelve URLs firmadas listas para usar. Descarga los bytes de los archivos directamente desde CDN/S3 sin cabecera Authorization en el GET, el mismo patrón usado para las descargas de archivos de escaneo.

sequenceDiagram
  participant Client as RCAPI client
  participant RCAPI as RCAPI
  participant CDN as CDN / S3

  Client->>RCAPI: GET input-files (page, limit)
  RCAPI-->>Client: items with signed urls + total
  loop for each item
    Client->>CDN: GET url
    CDN-->>Client: file bytes
  end

RCAPI firma el prefijo de entrada del bundle una vez por solicitud. La url de cada elemento es esa firma con un comodín reemplazado por la ruta de almacenamiento del archivo, de modo que todas las URLs de una misma respuesta comparten la misma caducidad.

Endpoint

Método	Ruta	Ámbito	Propósito
GET	/v1/bundles/{bundleId}/input-files	read:bundle	Listar las URLs de descarga firmadas de los archivos de entrada finalizados

Listar las URLs de descarga de los archivos de entrada

GET {api_url}/v1/bundles/{bundleId}/input-files?page=1&limit=20
Authorization: Bearer {access_token}

Parámetros de consulta

Parámetro	Tipo	Descripción
page	number	Índice de página en base 1 (predeterminado 1)
limit	number	Tamaño de página (predeterminado 20, máximo 20)
sessionId	uuid	Opcional. Limita los resultados a los archivos de una sesión de subida

No se ofrece ordenación. Los archivos se devuelven en un orden de almacenamiento estable.

Respuesta

Una lista paginada ({ items, total }):

{
  "items": [
    {
      "fileName": "scan.las",
      "url": "https://cdn…/bundles/…/scan.las?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    },
    {
      "fileName": "panorama/2024-07-scan-idx40.jpg",
      "url": "https://cdn…/bundles/…/panorama/2024-07-scan-idx40.jpg?X-Amz-…",
      "sessionId": "6ebf0fe5-4428-4b26-a7e4-e3274980123b"
    }
  ],
  "total": 28
}

Campo	Significado
fileName	El nombre del archivo de entrada (la ruta sustituida en el prefijo firmado)
url	URL de descarga firmada, lista para hacer GET sin cabecera de autenticación
sessionId	Sesión de subida a la que pertenece el archivo
total	Total de archivos de entrada finalizados en todas las páginas

Descargar los bytes

Para cada elemento, haz GET directamente a la url. No se requiere token bearer; la firma está incrustada en la cadena de consulta.

import requests

response = requests.get(item["url"])
response.raise_for_status()

with open(local_path, "wb") as handle:
    handle.write(response.content)

URLs caducadas

Todas las URLs de una respuesta comparten una única caducidad de firma (unas 24 horas, coherente con otros enlaces firmados de la API). Si una descarga devuelve 403 Forbidden, la URL ha caducado. Solicita una página nueva al endpoint de listado y vuelve a intentarlo.

Paginar bundles grandes

Cuando total supera a limit, recorre los resultados por páginas:

import requests

API_URL = "https://<your-regional-api-url>"
TOKEN = "<access_token>"
BUNDLE_ID = "<bundleId>"
LIMIT = 20

headers = {"Authorization": f"Bearer {TOKEN}"}
base = f"{API_URL}/v1/bundles/{BUNDLE_ID}/input-files"

page = 1
while True:
    listing = requests.get(
        base, headers=headers, params={"page": page, "limit": LIMIT}
    ).json()

    for item in listing["items"]:
        local_name = item["fileName"].replace("/", "_")
        data = requests.get(item["url"])
        data.raise_for_status()
        with open(local_name, "wb") as handle:
            handle.write(data.content)
        print(f"Downloaded {item['fileName']}")

    if page * LIMIT >= listing["total"]:
        break
    page += 1

Cuándo usar este endpoint

Caso de uso	Notas
Archivado	Copia las capturas sin procesar en tu propio almacenamiento tras la subida
Reprocesamiento	Descarga las entradas localmente y luego súbelas a un nuevo bundle
Auditoría / verificación	Confirma qué archivos llegaron al bundle antes del procesamiento
Pruebas de integración	Subida y descarga de ida y vuelta en pipelines de CI

Este endpoint devuelve solo los archivos de entrada (lo que subiste). Las salidas procesadas (HLODs, nubes de puntos estandarizadas, etc.) se exponen como enlaces firmados de los componentes del bundle en GET /v1/site/{siteId}/bundles/{bundleId}. Consulta Recuperar las salidas procesadas.

Casos de error

Estado	Causa
403 Forbidden	Falta el ámbito read:bundle o no hay permiso de lectura sobre el bundle
404 Not Found	bundleId desconocido

Un array items vacío con total: 0 significa que el bundle aún no tiene archivos de entrada finalizados. Completa primero una sesión de subida; consulta Subir datos a un Data Bundle.