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.
Interno y del SII
Sección titulada «Interno y del SII»| PDF interno | PDF del SII | |
|---|---|---|
| Quién lo genera | REDCUMBRE, con la plantilla de tu empresa | El 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é sirve | Entregarlo a tu cliente con tu diseño | Respaldo oficial del documento ante el SII |
| Documento tributario | descargarPdfDte | descargarPdfSiiDte: sólo para documentos emitidos por el Portal MiPyme; en otro carril responde 400 |
| Boleta de honorarios | descargarPdfInternoBoletaHonorarios | descargarPdfSiiBoletaHonorarios |
| Boleta de terceros | descargarPdfInternoBoletaTerceros | descargarPdfSiiBoletaTerceros |
El PDF del SII de una boleta tiene un estado, estadoPdfSii, que se lee en el detalle de la boleta:
estadoPdfSii | Significado |
|---|---|
PENDIENTE | Está en cola para descarga; vuelve a intentar más tarde |
DISPONIBLE | Ya se bajó |
FALLIDO | Se agotaron los reintentos (hasta 7 días); usa el PDF interno |
NO_APLICA | No 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.
Descarga
Sección titulada «Descarga»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).
# PDF interno de una boleta de honorarios, guardado en un archivoredcumbre 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 SIIredcumbre api descargarPdfDte --param id=<dteId> --param template_id=<plantilla> --salida factura.pdfredcumbre api descargarPdfSiiDte --param id=<dteId> --salida factura-sii.pdfResultado 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:
redcumbre api listarArchivosDte --param id=<dteId>redcumbre api listarArchivosBoletaHonorarios --param id=<id>redcumbre api descargarArchivoBoletaHonorarios --param id=<id> --param archivoId=<archivoId> --salida archivo.pdfResultado 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. idcorrecto. 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.
Compartirlo con un tercero
Sección titulada «Compartirlo con un tercero»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:
generarEnlacesDescargaDtedevuelvepdfUrl,xmlUrlypdfSiiUrl(este últimonullsi 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
pdfInternoUrlypdfSiiUrl, públicos, que piden el RUT del receptor y una verificación anti-automatización. El bloquedescargastrae enlaces para usuarios que también son usuarios de REDCUMBRE: exigen su sesión y se usan como navegación (<a href>), no confetch. Un documento de prueba nunca abre por enlace público. - Por correo:
enviarArchivoDtePorEmailenví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.
Dónde guardarlo
Sección titulada «Dónde guardarlo»- Guarda el
idy el folio del documento, no la URL. Elidte permite volver a pedir el PDF cuando lo necesites. Los enlacesdescargasde las boletas se calculan desde elidy son estables, pero exigen sesión. - 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.
- 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. - 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.
- 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.