[API FE COL] Nuevos enlaces de descarga para el ZIP de tus documentos — ya disponible en sandbox

Estamos cambiando la forma en que la API entrega los archivos descargables de
los documentos electrónicos (facturas, notas crédito, notas débito y documentos
equivalentes). El cambio ya puede probarse en el ambiente sandbox y llegará
a producción el 30 de septiembre.

Qué cambia

• El campo files.zip de las respuestas de creación y consulta pasará de una
  URL prefirmada de S3 a un enlace firmado de la API. El enlace se abre
  igual que hoy y dura 60 minutos; la diferencia es que resuelve el archivo en
  el momento de abrirse: si el ZIP ya no está almacenado, se regenera
  automáticamente antes de entregarse (la primera descarga de un documento
  antiguo puede tardar unos segundos).
• El ZIP contiene, como hasta ahora, el AttachedDocument (ad<consecutivo>.xml,
  el XML firmado junto con la respuesta de aceptación de la DIAN) y la
  representación gráfica en PDF (ad<consecutivo>.pdf).
• La URL pública directa del PDF (la que apunta al bucket de S3) dejará de
  estar disponible para documentos nuevos. Si hoy construyes o guardas esa URL,
  migra a los enlaces de files.zip o consulta el documento para obtener un
  enlace vigente.
• El endpoint GET /{tipo-de-documento}/{id}/files/{fileType} pasa a ser
  legacy: seguirá funcionando, pero recomendamos migrar a los enlaces de
  files.zip, que son el mecanismo soportado hacia adelante.

Qué no cambia

• Los contratos de creación y consulta: mismos campos, mismos formatos. Solo
  cambia el valor del enlace.
• El XML firmado y el AttachedDocument siguen almacenados y disponibles como
  siempre.

Qué debe verificar tu integración

1. Que tu cliente HTTP siga redirecciones (HTTP 302). El enlace nuevo
   responde 302 hacia la URL del archivo. En un navegador no hay que hacer
   nada; algunos clientes HTTP no siguen redirecciones por defecto:

   Cliente	Configuración
   PHP cURL	curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
   curl (CLI)	flag -L
   Java HttpClient (11+)	.followRedirects(HttpClient.Redirect.NORMAL)
   Python httpx	follow_redirects=True

   requests (Python), axios/fetch (Node.js) y los navegadores siguen el
   302 por defecto.

2. No reenvíes el header Authorization a la URL de destino. El enlace no
   requiere credenciales (el token de la query string es la autorización) y el
   destino de la redirección es S3, que rechaza la petición si llega con un
   Authorization ajeno. Si tu cliente añade ese header globalmente, exclúyelo
   al seguir la redirección.

3. No almacenes las URLs de descarga; solicítalas al momento de usarlas. El
   enlace de files.zip dura 60 minutos y la URL del Location de la
   redirección dura unos 5 minutos. Un enlace vigente siempre está a una
   consulta del documento de distancia.

Cómo probarlo

El comportamiento nuevo ya está activo en sandbox: lo que pruebes ahí es
exactamente lo que correrá en producción el 30 de septiembre. Emite o
consulta un documento, abre el enlace de files.zip y verifica los tres puntos
anteriores con tu propio cliente HTTP durante la semana de verificación.