Esta guia es para el administrador del tenant responsable de habilitar y configurar el modulo de agente retenedor ITBMS antes que los auxiliares de CxP empiecen a postear pagos.
Su tenant ha sido designado por la DGI como agente retenedor de ITBMS bajo la Resolucion 201-8055 (o una resolucion sucesora) y necesita habilitar el pipeline automatico de retenciones de CifraHQ.
Tenants extranjeros o no panamenos no necesitan Configuracion. Deje Agente Retenedor de ITBMS designado desactivado y el modulo entero permanecera inactivo.
Navegue a Contabilidad → Retenciones ITBMS (Configuracion). La primera vez, CifraHQ crea una fila de Configuracion en su base de datos con valores predeterminados sensatos (tasa 50%, disparador OnPayment, prefijo de certificado RT-).
Complete la seccion Designacion de Agente:
| Campo | Que ingresar |
|---|---|
| Agente Retenedor de ITBMS designado | Activar |
| Referencia de designacion | La resolucion que lo designo (ej., "Resolucion 201-8055 / 2026-2027") |
| Vigente desde | Fecha de inicio de su periodo de designacion |
| Vigente hasta | Fecha de fin del periodo (tipicamente bienal) |
El sistema respeta la ventana de vigencia: pagos fuera de la ventana no generaran retenciones, aunque el indicador este activo.
| Campo | Predeterminado DGI | Notas |
|---|---|---|
| Tasa de retencion | 50% | Tasa mandada por la DGI. Solo cambie si una regulacion futura lo modifica. |
| Evento disparador | Al pagar (DGI canonico) | Cuando se emite la retencion. La alternativa ("Al postear factura") es opcion de Fase 2. |
| Requerir aprobacion de CPA para cerrar | Desactivado (active si ingresos anuales > USD 11,000) | Cuando esta activo, el cierre mensual se enruta a un usuario CPA para aprobacion. |
| Campo | Notas |
|---|---|
| Prefijo de certificado | Predeterminado RT-. Usado como {prefijo}{secuencia de 8 digitos} (ej., RT-00000001). |
| Proximo numero de certificado | Solo lectura. El motor lo incrementa atomicamente bajo concurrencia optimista. |
| Enviar certificado al proveedor automaticamente | Active si quiere que cada certificado emitido se envie por correo automaticamente. |
El motor de retencion emite Asientos Contables de dos lineas contra estas cuentas:
| Cuenta | Usada cuando |
|---|---|
| ITBMS Retenido por Pagar | Usted es el agente: CR esta cuenta de pasivo al emitir retencion; DR al anular. Tipicamente un codigo 2-04-xx en Plan de Cuentas Panama. |
| ITBMS Retenido por Cobrar | Usted es proveedor registrando un certificado recibido de su cliente: DR esta cuenta de activo al emparejar. Tipicamente un codigo 1-04-xx. |
Si alguna cuenta no esta configurada, las retenciones igual persisten en el submayor pero el Asiento Contable correspondiente no se postea. El paso de validacion mensual del Formulario 4331 sacara a la luz la brecha.
Los tenants nuevos reciben estas cuentas pre-creadas. Desde CifraHQ 2.3.x, el Plan de Cuentas predeterminado de cada tenant nuevo incluye:
116000 - ITBMS Retenido por Cobrar(activo)231500 - ITBMS Retenido por Pagar(pasivo)Una migracion de relleno tambien corre contra tenants existentes en la primera actualizacion despues de 2.3.0: inserta las dos cuentas si faltan, y las auto-vincula a la fila singleton
TenantWithholdingConfigcuando las FK aun son null. Asi que en la mayoria de tenants encontrara las dos cuentas ya seleccionadas al abrir Contabilidad → Retenciones ITBMS (Configuracion) por primera vez. Verifique que coincidan con sus convenciones de Plan de Cuentas antes de ir en vivo - puede cambiar a cualquier otra cuenta de pasivo/activo en la misma categoria.
Una vez habilitado el indicador de agente, la pagina de detalle del Proveedor muestra una nueva seccion Retencion ITBMS. Para cada proveedor:
| Campo | Cuando cambiarlo |
|---|---|
| Domicilio fiscal | Predeterminado Panama. Cambie a Estados Unidos, Mexico, Canada, u Otro para Proveedores extranjeros. |
| Sujeto a retencion de ITBMS | Auto-gestionado: se desactiva cuando el Domicilio Fiscal es distinto de Panama. Anule para casos especiales. |
| Tasa de retencion ITBMS (anulacion) | Deje vacio para usar el predeterminado del tenant (50%). Establezca solo para Proveedores bajo regimen especial. |
| Razon de exencion | Ninguna / Zona Franca / Regimen Especial / Pequeno contribuyente / Extranjero / Otro |
| Referencia de documento de exencion | El numero de resolucion DGI que otorga la exencion |
| Exencion valida hasta | Fecha de vencimiento - el sistema avisa cuando es mayor a 365 dias |
La forma mas rapida de omitir un proveedor por completo es establecer correctamente el Domicilio Fiscal.
Despues de la Configuracion, ejecute esta prueba de humo contra un proveedor de Panama:
Si los pasos 5-6 no ocurren, vea la seccion de solucion de problemas en la Guia del Agente Retenedor.
La pagina de detalle del Proveedor tiene un boton Verificar Tax ID junto al campo de RUC (espeja la pagina de Cliente que ha tenido esto desde hace anos). Haga clic en el despues de ingresar el RUC del proveedor y CifraHQ:
Panama para un RUC panameno, Otro para Proveedores extranjeros con cedula extranjera u otro identificador)Por que importa para el flujo de retencion:
El mismo boton esta disponible desde la busqueda por Codigo del proveedor (/api/Vendor/VerifyTaxIdByCode?code=...), util cuando solo tiene el codigo del proveedor desde un CSV importado.
En casos raros - tipicamente cuando un despliegue cae a media-emision-de-pago o una dependencia externa (periodo contable faltante, cuenta configurada subitamente invalida) tropieza al motor - puede terminar con una fila ITBMSRetention en estado Emitido sin fila RetentionCertificate correspondiente. El paso de validacion de cierre del Formulario 4331 bloqueara el cierre del periodo hasta que se corrija.
CifraHQ trae un endpoint de recuperacion de una sola ejecucion:
POST /api/RetentionCertificate/ReissueByPayment?paymentId={billPaymentId}
Lo que hace:
(SourceDocId, PaymentId))RetentionCertificate faltanteCertificateDeliveryJob para que el PDF se genere, se cargue y se envieEl endpoint es idempotente: llamarlo sobre un pago que ya tiene certificado sano simplemente devuelve el certificado existente y no hace nada mas.
Cuando usarlo:
| Situacion | Accion |
|---|---|
| La validacion del Formulario 4331 dice "retencion sin certificar" | Ejecute ReissueByPayment para cada pago afectado |
| El Pago de Factura muestra posteado pero sin panel de Certificado de Retencion, y esperaron 60+ segundos | Ejecute ReissueByPayment |
| Recuperacion masiva tras una interrupcion | Consulte ITBMSRetentions r LEFT JOIN RetentionCertificates c ON c.RetentionId = r.Id WHERE c.Id IS NULL, luego llame a ReissueByPayment para cada r.PaymentId |
El estado del trabajo aparece en /hangfire - las ejecuciones exitosas dejan un rastro de Auditoria claro.
La plantilla del certificado se construye programaticamente en C# al momento del seed usando el API .NET de Stimulsoft y se guarda en formato XML. Esto elimina toda la clase de problemas "la plantilla JSON cargaba bien en el disenador pero crashea el render del servidor" que afectaban a las plantillas hechas a mano anteriores.
Una vez por tenant (y nuevamente despues de actualizar la version de CifraHQ que traiga plantilla actualizada):
POST /api/WithholdingTemplateSeeder/Seed
El endpoint devuelve una lista JSON de plantillas creadas/actualizadas/omitidas:
{
"Created": [],
"Updated": ["RetentionCertificate"],
"Skipped": []
}
PrintReports con ese nombreIsCustom = false), asi que se sobrescribio con el binario mas recienteIsCustom = true (alguien personalizo la plantilla en el disenador Stimulsoft); la personalizacion queda intactaSeguro de re-ejecutar en cualquier momento - la nueva construccion programatica siempre emite los mismos bytes XML canonicos, asi que un re-seed nunca introduce un crash en tiempo de carga en la ruta de render .NET.
Puede editar la plantilla seeded en el disenador web Stimulsoft (link en la pagina de admin de PrintReports). El disenador guarda sus ediciones en formato JSON, que es lo que usa el disenador JS - y que el disenador JS tambien carga de regreso limpiamente. La ruta de render del PDF se mantiene robusta porque el binding de datos es el mismo en ambos formatos; solo cambia la codificacion en disco.
Si alguna vez carga una plantilla JSON que el renderer del servidor rechaza con InvalidCastException - Unable to cast object of type 'JValue' to type 'JObject' (un comportamiento conocido de Stimulsoft .NET 2025.x con JSON hecho a mano), re-ejecute el seeder - reemplazara el JSON roto con el XML canonico y sus personalizaciones tendran que re-aplicarse a traves del disenador.
Solo puede desactivar el indicador Agente Retenedor de ITBMS designado cuando no hay retenciones abiertas (Emitido o Borrador) en el periodo actual. Si existen retenciones, cierre primero el Formulario 4331 actual.
Esta proteccion previene certificados huerfanos y protege el GL.
/settings/taxes/itbms-withholdings) - rol administradorWas this page helpful?