Troubleshooting & Reference · Article 7.4
«El enlace de la factura está roto o falta el PDF»
Los PDF ocasionalmente fallan al renderizarse (fallo de Gotenberg) o al cargarse en R2. Síntoma: el documento se muestra como «emitido» pero al hacer clic en el enlace devuelve 404 o el PDF está en blanco. Recuperación: regenerar desde el menú desplegable de Documentos.
La generación de PDF es un proceso asíncrono de varios pasos: renderizar HTML a partir de una plantilla Jinja, enviar a Gotenberg (Chrome sin interfaz gráfica) para la conversión a PDF, cargar los bytes en Cloudflare R2 y guardar la URL en el registro de la propuesta. Cualquier paso puede fallar de forma independiente. El modelo de recuperación de Clozo es «reintentar desde cualquier paso» — el botón Regenerar reconstruye las piezas que faltan.
Step by step
Identifique el PDF que falta.
Abra el menú desplegable de Documentos en la página de detalle de la propuesta; el documento roto es el que tiene el enlace 404.
Haga clic en
Regenerarjunto a él.El renderizador vuelve a ejecutarse; los nuevos bytes se cargan en R2.
Espere ~10 segundos y vuelva a intentar el enlace.
La nueva URL reemplaza a la anterior; el enlace en cualquier correo enviado previamente también resolverá al nuevo archivo (la ruta en R2 es estable).
Why this works this way
La ruta de renderizado está en apps/pdf/service.py. Cada tipo de documento tiene su propio renderizador (render_proposal_pdf, render_final_invoice_pdf, render_credit_note_pdf, etc.). Cuando tiene éxito, los bytes van a apps/storage/r2.py:upload_to_r2(), que devuelve una URL almacenada en el modelo.
Modos de fallo: - Tiempo de espera de Gotenberg (30 s por defecto): normalmente por una plantilla larga (gran número de líneas) o un reinicio del pod de Gotenberg. El reintento suele tener éxito. - Fallo de carga en R2: problema transitorio de credenciales o red; el reintento tiene éxito en minutos. - Factura fantasma: el registro de la factura se creó (número asignado, estado establecido) pero el renderizado del PDF o la carga fallaron de forma silenciosa. El autónomo ve el estado «Factura final emitida» pero el enlace del PDF devuelve 404.
Condición de carrera específica de las enmiendas: el hook post-firma genera nuevos PDFs de INV / Storno / Nota de crédito en paralelo. Si un renderizador falla, los demás tienen éxito y el estado del modelo avanza. El PDF faltante necesita regeneración específica.
Troubleshooting
Keep reading
Lifecycle
Status: Deposit paid — work can start
The deposit landed (Stripe webhook or manual confirmation). Clozo flips the status, queues the deposit receipt PDF, and starts a behind-the-scenes job to pre-render the final invoice. You can begin the work.
Proposals & Invoices
The 4 delta branches: Δ+, Δ−, Δ=0, Δ_REFUND
Every signed amendment falls into one of four branches based on (a) the sign of the cost change and (b) whether the proposal was already paid. Each branch fires a different document chain. This is the central conceptual map for the entire amendment system.