Enlaces de descarga

Las respuestas de creación y consulta de facturas, notas crédito, notas débito y documentos equivalentes traen un campo files con los archivos del documento. El enlace de files.zip es un enlace firmado que emite la API, no una dirección fija de un archivo almacenado.

La ruta y el token vienen juntos en la respuesta, y el token no puede generarse por fuera de la API. Tu integración no arma el enlace: lo recibe y lo abre.

🚧

Disponibilidad

El comportamiento descrito aquí ya opera en sandbox. En producción entra el 30 de septiembre; hasta entonces files.zip entrega en producción URLs prefirmadas de S3.

Cómo se usa

Emite o consulta el documento y abre el enlace tal como llega:

{
  "id": "01K9ZGBPMG5RAM4KHBQHVHWG2R",
  "number": "SETP990000001",
  "files": {
    "zip": "https://api.alegra.com/e-provider/col/v1/files/download?token=eyJhbGciOiJIUzI1NiJ9..."
  }
}

No necesitas credenciales: el token de la query string es la autorización. Está limitado a un documento y a un archivo por sus claims, y en el tiempo por su expiración.

Qué debe cumplir tu cliente HTTP

Son tres puntos. Si tu integración ya los cumple, no tienes que hacer nada.

1. Seguir redirecciones

El enlace responde 302 hacia la URL del archivo. Los navegadores, requests (Python) y axios/fetch (Node.js) lo siguen por defecto. Otros clientes necesitan que lo habilites:

2. No reenviar el encabezado Authorization al destino

El destino de la redirección es S3, que rechaza la petición si llega con un Authorization ajeno. Como el enlace no requiere credenciales, ese encabezado no hace falta en ningún momento. Si tu cliente lo añade de forma global a todas las peticiones, exclúyelo al seguir la redirección.

3. No almacenar las URLs

El enlace de files.zip dura 60 minutos, y la URL del Location de la redirección dura unos 5 minutos. Guardar cualquiera de las dos produce un enlace vencido más adelante.

Consulta el documento cuando necesites el archivo: un enlace vigente siempre está a una consulta de distancia.

Qué contiene el ZIP

Dos archivos, los mismos de siempre:

Por qué la primera descarga puede tardar

El ZIP se conserva 15 días desde la emisión. Pasado ese plazo el enlace sigue sirviendo, pero el archivo se regenera en el momento de abrirlo, así que la primera descarga de un documento antiguo puede tardar unos segundos. Las siguientes son inmediatas.

Lo mismo ocurre en el otro extremo: si el documento se acaba de emitir y sus archivos aún se están generando, el enlace espera unos segundos a que estén listos antes de redirigir.

📘

El enlace no caduca con el archivo

Que el ZIP ya no esté almacenado no invalida el enlace. Lo único que lo invalida es su propia expiración de 60 minutos.

Si vienes del comportamiento anterior

• Las URLs directas al bucket de S3 (sin firma, como la URL pública del PDF) dejan de estar disponibles, también para documentos ya emitidos. Ningún archivo se sirve sin un enlace firmado: usa el enlace de files.zip.
• El endpoint GET /{tipo-de-documento}/{id}/files/{fileType} pasa a ser legacy: seguirá funcionando, pero el mecanismo soportado hacia adelante son los enlaces de files.zip.
• Los contratos de creación y consulta no cambian: mismos campos y mismos formatos. Solo cambia el valor del enlace.
• El XML firmado y el AttachedDocument siguen almacenados y disponibles como siempre.