Ir al contenido

Documentos y PDF

Un documento emitido tiene dos clases de PDF y varias formas de entregarlo. Esta mecánica dice cuál es cuál, cómo bajarlo y qué hacer con el archivo. La usan las fichas de documentos tributarios, boletas de honorarios y boletas de terceros; cómo se emite el documento está en Emisión de documentos.

PDF internoPDF del SII
Quién lo generaREDCUMBRE, con la plantilla de tu empresaEl SII (el respaldo oficial)
Cuándo estáEn cuanto el documento existe (en el modo SINC_PARCIAL, también en la respuesta de emisión)Después, y no siempre: se baja en segundo plano con reintentos
Para qué sirveEntregarlo a tu cliente con tu diseñoRespaldo oficial del documento ante el SII
Documento tributariodescargarPdfDtedescargarPdfSiiDte: sólo para documentos emitidos por el Portal MiPyme; en otro carril responde 400
Boleta de honorariosdescargarPdfInternoBoletaHonorariosdescargarPdfSiiBoletaHonorarios
Boleta de tercerosdescargarPdfInternoBoletaTercerosdescargarPdfSiiBoletaTerceros

El PDF del SII de una boleta tiene un estado, estadoPdfSii, que se lee en el detalle de la boleta:

estadoPdfSiiSignificado
PENDIENTEEstá en cola para descarga; vuelve a intentar más tarde
DISPONIBLEYa se bajó
FALLIDOSe agotaron los reintentos (hasta 7 días); usa el PDF interno
NO_APLICANo hay respaldo del SII para esta boleta (por ejemplo, una boleta de prueba, o ya viene con el PDF en SINC_COMPLETO)

Mientras está PENDIENTE, pedir el PDF del SII responde 404 con el código PDF_SII_NOT_AVAILABLE y el campo estadoPdfSii, para distinguir «todavía se está generando» de «falló». El mismo 404 se obtiene si la boleta no existe: lee el campo, no sólo el status.

Plantillas. El PDF interno se representa con una plantilla. Las disponibles: listarPlantillasPdfDte (para un documento o por código de tipo SII), listarPlantillasPdfBoletaHonorarios y listarPlantillasPdfBoletaTerceros. Al emitir una boleta puedes elegir templateId; queda congelado en la boleta y gobierna toda representación posterior, incluido el PDF que se adjunta al correo del destinatario. Para imprimir con otro formato sin cambiar lo que recibe el destinatario, usa la representación alterna (generarPdfAlternativoBoletaHonorarios, generarPdfAlternativoBoletaTerceros, generarPdfDte): se genera al momento, no se guarda y no altera nada del documento.

Modo de prueba. Todo PDF de un documento de prueba lleva la marca «DOCUMENTO DE PRUEBA — SIN VALIDEZ TRIBUTARIA» en cada página: no se lo entregues a un cliente. El PDF de respaldo del SII no existe en prueba: descargarPdfSiiDte se rechaza con OPERACION_NO_DISPONIBLE_EN_PRUEBA y el de una boleta de prueba responde como uno que no está disponible. Un documento del otro modo responde igual que uno que no existe.

Todas las descargas con API key entregan el archivo en la respuesta, como application/pdf (Content-Disposition: attachment). Ninguna es una redirección ni devuelve una URL de almacenamiento. Necesitas el id del documento (el que devolvió la emisión o el listado).

Ventana de terminal
# PDF interno de una boleta de honorarios, guardado en un archivo
redcumbre api descargarPdfInternoBoletaHonorarios --param id=<id> --salida boleta.pdf
# PDF del SII (respaldo oficial)
redcumbre api descargarPdfSiiBoletaHonorarios --param id=<id> --salida boleta-sii.pdf
# Documento tributario: PDF de la plataforma y PDF del SII
redcumbre api descargarPdfDte --param id=<dteId> --param template_id=<plantilla> --salida factura.pdf
redcumbre api descargarPdfSiiDte --param id=<dteId> --salida factura-sii.pdf

Resultado esperado: el CLI escribe el PDF en el archivo de --salida y no imprime su contenido. Sin --salida, una respuesta binaria no se puede guardar.

Para listar los archivos de un documento (internos, del SII y personalizados) y bajar uno puntual:

Ventana de terminal
redcumbre api listarArchivosDte --param id=<dteId>
redcumbre api listarArchivosBoletaHonorarios --param id=<id>
redcumbre api descargarArchivoBoletaHonorarios --param id=<id> --param archivoId=<archivoId> --salida archivo.pdf

Resultado esperado: la lista de archivos con su id; la descarga puntual guarda el PDF.

  • Límite de descargas. Las descargas de boletas responden 429 («Límite de descargas por identidad superado») si repites demasiado: espera antes de reintentar y no vuelvas a pedir el mismo archivo en un bucle. La representación alterna también cuenta, porque se genera cada vez.
  • id correcto. Una llave de prueba sólo ve documentos de prueba y una de producción sólo de producción; pedir uno del otro modo responde como si no existiera.
  • Precio. Lo que cuesta depende de tu plan: redcumbre tarifas <operationId> --produccion.

Para que otra persona (tu cliente, su contador) descargue sin tener cuenta, hay enlaces públicos de REDCUMBRE, nunca un enlace al almacenamiento:

  • Documento tributario: generarEnlacesDescargaDte devuelve pdfUrl, xmlUrl y pdfSiiUrl (este último null si el documento no salió por el Portal MiPyme). Se abren sin autenticación, en el dominio de tu empresa o el de REDCUMBRE por defecto. En el modo de prueba el enlace público no existe: entrega la vista que exige sesión.
  • Boletas: la respuesta de emisión trae pdfInternoUrl y pdfSiiUrl, públicos, que piden el RUT del receptor y una verificación anti-automatización. El bloque descargas trae enlaces para usuarios que también son usuarios de REDCUMBRE: exigen su sesión y se usan como navegación (<a href>), no con fetch. Un documento de prueba nunca abre por enlace público.
  • Por correo: enviarArchivoDtePorEmail envía un archivo del documento a un destinatario. En producción el correo sí sale al destinatario.

Trata un enlace público como una llave de lectura: quien lo tenga puede abrir el documento. No lo publiques ni lo pegues donde no corresponda.

  1. Guarda el id y el folio del documento, no la URL. El id te permite volver a pedir el PDF cuando lo necesites. Los enlaces descargas de las boletas se calculan desde el id y son estables, pero exigen sesión.
  2. Si necesitas el archivo, descárgalo y guárdalo tú, en el almacenamiento de tu sistema (disco, base de documentos, tu propio bucket), asociado a tu orden o a tu cliente. Es un documento tributario con RUT y nombres de personas: trátalo como dato personal y con el acceso que corresponde.
  3. No lo pongas en el repositorio del proyecto ni lo pegues en una conversación: añade la carpeta de salida a .gitignore. Los PDF de prueba llevan la marca de prueba y no tienen validez tributaria.
  4. Nunca uses un enlace directo a un bucket de almacenamiento. Ninguna operación de REDCUMBRE lo entrega: toda descarga pasa por la API o por un enlace público de REDCUMBRE. No armes uno ni aceptes uno que te pasen.
  5. Pide el PDF del SII más tarde, no en la misma llamada de emisión, salvo que uses SINC_COMPLETO. Si está PENDIENTE, reintenta con espera; si está FALLIDO, conserva el PDF interno.

La API no publica por cuánto tiempo conserva REDCUMBRE los archivos de tu empresa: no lo asumas. Si tu obligación de conservar el documento es tuya, guarda tu copia.