P4 Software / cifrahq-spanish

Guia del Agente Retenedor

Guia del Agente Retenedor

Esta guia es para Auxiliares de CxP y Contadores Fiscales en un tenant designado como agente retenedor de ITBMS bajo la Resolucion 201-8055 de la DGI.

Requisitos previos

Antes de emitir cualquier certificado, el administrador debe completar lo siguiente (una sola vez):

  1. Ir a Contabilidad → Retenciones ITBMS (Configuracion)
  2. Habilitar Agente Retenedor de ITBMS designado
  3. Ingresar la Referencia de designacion (ej., "Resolucion 201-8055 / 2026-2027")
  4. Establecer Vigente desde al inicio de su periodo de designacion
  5. Confirmar que la Tasa de retencion sea 50% (predeterminado por la DGI)
  6. Seleccionar la Cuenta de ITBMS por Pagar (Retenido) (cuenta de pasivo en su Plan de Cuentas - tipicamente un codigo 2-04-xx)
  7. Opcionalmente habilitar Enviar certificado al proveedor automaticamente

Vea la Guia del Administrador para detalles.

El flujo a vista de pajaro

Usted recibe una factura de proveedor con ITBMS  →  Usted postea un pago
                                              ↓
                                  CifraHQ calcula la retencion 50%
                                              ↓
                          Certificado emitido + GL contabilizado + PDF enviado
                                              ↓
                          Fin de mes: generar Formulario 4331
                                              ↓
                                Subir CSV a e-Tax 2.0 de DGI

Que Proveedores activan una retencion

Una retencion se genera automaticamente solo cuando todas estas condiciones son verdaderas al postear el pago:

Compuerta Donde configurarla Que hace
Designacion de agente habilitada Contabilidad → Retenciones ITBMS (Configuracion) Interruptor maestro del modulo
Fecha de pago dentro de su ventana de vigencia Contabilidad → Retenciones ITBMS (Configuracion) Respeta ciclos bienales de designacion
Proveedor marcado Sujeto a retencion de ITBMS Detalle del proveedor → seccion Retencion Activacion/desactivacion por proveedor
Domicilio fiscal del proveedor es Panama Detalle del proveedor → seccion Retencion Excluye automaticamente Proveedores extranjeros
La factura origen tiene al menos una linea con ITBMS Detalle de la factura Nada que retener de una factura sin ITBMS

Proveedores de Miami / EE.UU. / Mexico / Canada estan excluidos por defecto. Cuando establece el Domicilio Fiscal en algo distinto a Panama, Sujeto a retencion de ITBMS se desactiva automaticamente.

Paso a paso: postear un pago que genere una retencion

  1. Postee la factura del proveedor normalmente. Asegurese de que tenga lineas de ITBMS correctas (7%, 10%, o 15% segun aplique).
  2. Cree un Pago de Factura para esa factura. Establezca la fecha de posteo y el monto.
  3. Postee el pago. El motor de retencion corre en segundo plano en pocos segundos y:
    • Crea una fila RetentionCertificate con numero secuencial (ej., RT-00000001)
    • Postea un Asiento Contable: DR su cuenta de CxP, CR la cuenta de ITBMS Retenido por Pagar
    • Si Enviar certificado al proveedor automaticamente esta habilitado y el proveedor tiene correo, el PDF se entrega

El pago en si no se ve afectado - se postea al monto bruto. La retencion es un documento separado para mantener limpio el envejecimiento de CxP.

Ver certificados emitidos

Hay tres lugares donde puede encontrar un certificado emitido:

1. La pagina de detalle del Pago de Factura (lo mas comun)

Cuando abre un Pago de Factura posteado que genero una retencion, vera un panel Certificado de Retencion en la barra lateral derecha. El panel muestra:

Campo Que indica
Numero de Certificado El numero secuencial asignado al emitirse (ej., RT-00000007)
Fecha de Emision La fecha de activacion de la retencion - normalmente la fecha de posteo del pago
Total Retenido El monto en dolares retenido al proveedor (50% del ITBMS)
Proveedor La razon social del proveedor y el correo al que se envio el certificado
Estado Emitido / Anulado
Entrega Correo - entregado {marca de tiempo} cuando termina el envio automatico, o Aun no entregado si el correo sigue en cola o fallo
Almacenamiento Azure Blob (PDF cargado al contenedor del tenant) o Respaldo local (Azure no estaba disponible; haga clic en Reenviar para reintentar)

El panel tiene tres botones de accion:

  • Reimprimir PDF - abre un PDF nuevo en otra pestana. El renderizado usa datos en vivo de la plantilla y los detalles actuales del proveedor cada vez, asi que una actualizacion de marca o una correccion de la razon social aparece en la reimpresion sin necesidad de re-emitir el certificado.
  • Reenviar por correo - re-encola el trabajo de entrega al mismo correo del proveedor. Use esto cuando el proveedor reporte que el correo automatico nunca llego. El trabajo re-renderiza el PDF, re-carga a Azure si el intento previo quedo solo local, y reenvia.
  • Copiar URL de verificacion - copia la URL publica https://verify.CifraHQ.cloud/cert/{token} al portapapeles, lista para pegar en un chat o correo de seguimiento.

Si el pago no activo una retencion (proveedor extranjero, factura sin ITBMS, etc.), el panel simplemente no aparece. No hay error ni tarjeta vacia - la barra lateral derecha solo muestra los campos normales del pago.

2. Pagina de lista del Formulario 4331

Contabilidad → Formulario 4331 consolida los totales de cada periodo: cantidad de Proveedores, cantidad de certificados, base imponible, ITBMS facturado, ITBMS retenido, estado, y un export CSV por periodo. Profundice en una fila para ver todos los certificados emitidos en ese mes y su estado.

3. URL de descarga directa

Para acceso programatico, cada certificado expone:

GET /api/RetentionCertificate/Download?id={certificateId}

La respuesta es un stream PDF recien generado (application/pdf). Es el mismo renderizador que usa el boton Reimprimir PDF - util para scripts, trabajos de archivado o portales de Proveedores.

Reimpresion y reenvio - en profundidad

Dos escenarios cubren casi todo el trafico de reimpresion/reenvio:

Escenario A: "El proveedor dice que nunca recibio el correo"

Es el caso mas frecuente. El correo automatico se envia inmediatamente despues de postear la retencion, pero puede caer en spam, rebotar por una direccion mal escrita, o ser descartado en silencio por un filtro agresivo en el MX del proveedor.

Pasos de resolucion:

  1. Abra el detalle del Pago de Factura
  2. En el panel de Certificado de Retencion, verifique que el correo en la fila Proveedor sea correcto. Si esta equivocado, corrija el registro del proveedor (Detalle del proveedor → Correo) antes de hacer clic en Reenviar - el reenvio usa el correo actual.
  3. Haga clic en Reenviar por correo. El boton muestra un spinner momentaneo; un toast confirma "Reenviado a ".
  4. Refresque la pagina despues de ~30 segundos. La fila Entrega debe actualizarse a Correo - entregado {nueva marca de tiempo}.
  5. Si el proveedor sigue sin verlo, haga clic en Reimprimir PDF y reenvie el PDF manualmente como adjunto.

Escenario B: "Cambiamos de marca / corregimos la razon social del proveedor / actualizamos la URL de verificacion"

La fila del certificado en la base de datos es inmutable por cumplimiento - la fecha de emision, numero, monto y token de verificacion nunca cambian. Pero el PDF renderizado siempre se construye con datos en vivo al momento de la solicitud:

  • La plantilla viene del registro PrintReports actual, asi que una actualizacion (cargada desde el disenador Stimulsoft) se refleja al instante.
  • El bloque de marca del tenant (logo, RUC, direccion) viene de los valores actuales de Configuracion → Empresa.
  • El bloque del proveedor (nombre, RUC, direccion) viene del registro actual del proveedor.

Entonces si cambia el logo corporativo o corrige una errata en la razon social de un proveedor, solo haga clic en Reimprimir sobre cada certificado afectado. Sin re-emision, sin nuevo numero secuencial, sin nuevo asiento contable.

Por que Reenviar re-carga el PDF a Azure

Cuando el renderizado del PDF tiene exito pero la carga al blob de Azure falla (interrupcion de red, permisos del storage account, rotacion de llave), el sistema cae a un marcador de almacenamiento local://. La fila del certificado sigue mostrando Emitido y el correo puede haberse enviado, pero el PDF archivado queda solo en el worker que manejo la solicitud.

Reenviar limpia explicitamente el marcador local:// antes de re-ejecutar el trabajo, forzando un nuevo render del PDF y una nueva carga a Azure. Despues de Reenviar, la fila Almacenamiento debe leer Azure Blob - en ese punto el PDF queda durablemente almacenado en el contenedor del tenant y sobrevive a reciclajes del worker.

Lo que el usuario NO necesita hacer

  • No necesita anular y re-emitir un certificado para corregir una errata en el bloque de marca del proveedor.
  • No necesita re-ejecutar el motor de retencion para refrescar el correo - Reenviar lo maneja.
  • No necesita adjuntar manualmente el PDF a un correo - deje que Reenviar lo entregue por la misma ruta automatica; asi la bitacora de Auditoria registra la entrega.

Que contiene el PDF del certificado

El PDF (en espanol por defecto para tenants de Panama) incluye:

  • Su marca de tenant (logo + razon social + RUC)
  • Numero de certificado y fecha de emision
  • Nombre y RUC del proveedor retenido
  • Numero de factura origen y CUFE
  • Detalle por bucket: tasa, base imponible, ITBMS facturado, ITBMS retenido
  • Total retenido en USD (mostrado como "B/.")
  • URL y token de verificacion: https://verify.CifraHQ.cloud/cert/{token}
  • Pie de cumplimiento DGI

Los Proveedores pueden verificar cualquier certificado visitando la URL (publica, sin autenticacion).

Cuando y como anular un certificado

Puede anular un certificado antes del cierre del periodo. La anulacion:

  • Cambia el estado del certificado a Anulado
  • Postea un Asiento Contable de reversion (DR/CR invertidos con los mismos montos)
  • Emite un aviso de anulacion (la bitacora de Auditoria registra el motivo)

Despues del cierre del periodo (estado Enviado), la anulacion esta bloqueada. Use el flujo de Rectificacion sobre el Formulario 4331.

Generar Formulario 4331 al cierre del mes

  1. Ir a Contabilidad → Formulario 4331
  2. Clic en Generar
  3. Elegir Ano y Mes del periodo
  4. Clic en Validar primero - el sistema verifica:
    • Ninguna retencion en estado Borrador
    • Cada retencion emitida tiene un certificado
    • El balance del GL "ITBMS Retenido por Pagar" iguala la suma de los certificados
  5. Si la validacion pasa, clic en Generar. La declaracion se crea en Borrador.
  6. Clic en CSV sobre la fila para descargar el export.
  7. La respuesta incluye un header SHA-256 X-Form4331-Hash. El mismo hash se persiste en la declaracion para Auditoria.

Subir a e-Tax 2.0 de la DGI

  1. Inicie sesion en e-Tax 2.0 con las credenciales del RUC del agente.
  2. Navegue a la declaracion mensual del Formulario 4331.
  3. Suba el CSV exportado desde CifraHQ.
  4. Al confirmar, vuelva a CifraHQ, abra la fila del Formulario 4331, clic en Enviar e ingrese el numero de confirmacion DGI.
  5. La declaracion pasa a estado Enviado y el periodo se bloquea.

Fecha limite de presentacion: el 15 del mes siguiente al mes de presentacion. Las presentaciones tardias incurren en multa minima de USD 10 mas intereses.

Solucion de problemas

Sintoma Causa probable Que hacer
Pago posteado pero no aparece el panel de Certificado de Retencion El proveedor tiene Sujeto a retencion = false, o Domicilio Fiscal ≠ Panama, o la factura no tenia lineas con ITBMS Verifique el registro del proveedor. Si esta correctamente marcado, probablemente la factura no tenia lineas con ITBMS - nada que retener.
Pago posteado, proveedor correcto, pero el panel sigue sin aparecer El trabajo de retencion sigue corriendo, o tuvo error a media emision Refresque despues de 30 segundos. Si el panel sigue sin aparecer, vea "Recuperacion de huerfanos" en la Guia del Administrador.
El panel muestra el certificado pero Almacenamiento dice Respaldo local La carga al blob de Azure fallo (problema transitorio de red, rotacion de permisos, etc.) Haga clic en Reenviar por correo - fuerza un nuevo render del PDF y una nueva carga a Azure.
El panel muestra el certificado pero Entrega dice Aun no entregado despues de un minuto El trabajo de entrega de correo fallo o sigue en cola Haga clic en Reenviar por correo; verifique primero que el correo del proveedor sea correcto.
El proveedor reporta que el correo nunca llego Filtro de spam o direccion con rebote Verifique y corrija el correo del proveedor si es necesario, luego haga clic en Reenviar por correo. Si el MX del proveedor rechaza el nuestro, haga clic en Reimprimir PDF y reenvie manualmente.
El boton Reimprimir devuelve un error sobre renderizado de plantilla La plantilla Stimulsoft no se sembro en este tenant Pidale al administrador ejecutar POST /api/WithholdingTemplateSeeder/Seed (vea la Guia del Administrador).
"Discrepancia GL/submayor" durante validacion del 4331 Se emitio una retencion pero las cuentas contables del tenant no estan establecidas Abra Contabilidad → Retenciones ITBMS (Configuracion) y elija la cuenta ITBMS Retenido por Pagar.
Generacion del Formulario 4331 rechazada Una de las reglas de validacion de cierre fallo Clic en Validar primero - el dialogo lista cada razon.
Cierre de periodo bloqueado por aviso "retencion sin certificar" Existe una fila de retencion sin certificado correspondiente (huerfano) Vea "Recuperacion de huerfanos" en la Guia del Administrador.

Was this page helpful?

Previous Retenciones ITBMS (Formulario 4331) Next Guia del Administrador