Baixando Arquivos de Entrada

Depois que os arquivos de entrada são enviados e finalizados, você pode baixá-los novamente pela API.

Este guia pressupõe que você tem um bundle com arquivos de entrada finalizados e possui o escopo read:bundle.

---

Como funciona

O endpoint de download retorna URLs assinadas prontas para uso. Baixe os bytes do arquivo diretamente do CDN/S3 sem cabeçalho Authorization no GET, o mesmo padrão usado para downloads de arquivos de scan.

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

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

A RCAPI assina o prefixo de entrada do bundle uma vez por requisição. A url de cada item é essa assinatura com um curinga substituído pelo caminho de armazenamento do arquivo, de modo que todas as URLs de uma única resposta compartilham a mesma expiração.

Endpoint

Método	Caminho	Escopo	Finalidade
GET	/v1/bundles/{bundleId}/input-files	read:bundle	Listar URLs de download assinadas para arquivos de entrada finalizados

Listar URLs de download de arquivos 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	Descrição
page	number	Índice de página baseado em 1 (padrão 1)
limit	number	Tamanho da página (padrão 20, máximo 20)
sessionId	uuid	Opcional. Limita os resultados a arquivos de uma sessão de envio

Não há ordenação disponível. Os arquivos são retornados em uma ordem de armazenamento estável.

Resposta

Uma 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	O nome do arquivo de entrada (o caminho substituído no prefixo assinado)
url	URL de download assinada, pronta para GET sem cabeçalho de autenticação
sessionId	Sessão de envio à qual o arquivo pertence
total	Total de arquivos de entrada finalizados em todas as páginas

Baixar os bytes

Para cada item, faça o GET da url diretamente. Nenhum token bearer é necessário; a assinatura está embutida na query string.

import requests

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

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

URLs expiradas

Todas as URLs de uma resposta compartilham uma única expiração de assinatura (cerca de 24 horas, consistente com outros links assinados da API). Se um download retornar 403 Forbidden, a URL expirou. Solicite uma nova página no endpoint de listagem e tente novamente.

Paginando bundles grandes

Quando total excede limit, percorra os resultados página por página:

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

Quando usar este endpoint

Caso de uso	Observações
Arquivamento	Copie capturas brutas para seu próprio armazenamento após o envio
Reprocessamento	Baixe as entradas localmente e depois envie para um novo bundle
Auditoria / verificação	Confirme quais arquivos chegaram ao bundle antes do processamento
Testes de integração	Faça o ciclo completo de envio e download em pipelines de CI

Este endpoint retorna apenas arquivos de entrada (o que você enviou). As saídas processadas (HLODs, nuvens de pontos padronizadas e assim por diante) são expostas como links assinados de componentes de bundle em GET /v1/site/{siteId}/bundles/{bundleId}. Consulte Recuperando saídas processadas.

Casos de erro

Status	Causa
403 Forbidden	Escopo read:bundle ausente ou sem permissão de leitura no bundle
404 Not Found	bundleId desconhecido

Um array items vazio com total: 0 significa que o bundle ainda não tem arquivos de entrada finalizados. Conclua uma sessão de envio primeiro; consulte Enviando Dados para um Data Bundle.