Skip to content

hafisol/hazel-retenciones

v0.2.1Proprietary

Calcula retenciones colombianas de renta, IVA e ICA a partir de factura y RUT del pagador y proveedor, y entrega el Excel formulado de CalRetenciones.

GitHubOpen Website

Hazel

Plugin para calcular retenciones colombianas de renta, IVA e ICA desde ChatGPT y entregar el Excel formulado de CalRetenciones.

Uso en ChatGPT

  1. Instala Hazel y conecta tu cuenta cuando ChatGPT lo solicite.
  2. Guarda los RUT del pagador y de los proveedores en las fuentes de un proyecto de ChatGPT. Puedes compartir ese proyecto con otra persona autorizada.
  3. En un chat del proyecto, adjunta la factura, proforma o foto legible. Indica fecha de pago/abono y lugar de cada concepto cuando corresponda.
  4. Pide: @Hazel calcula las retenciones de esta factura usando los RUT del proyecto y genera el Excel formulado.
  5. Descarga Retenciones-<NIT sin DV>.xlsx. El enlace del servicio caduca en una hora; guarda el archivo en el chat/proyecto.

Un plugin instalado no obtiene acceso automático a todos los proyectos o archivos. Si un RUT no resulta accesible, Hazel pide ese soporte concreto. La disponibilidad en celular/tableta depende de que el plugin esté instalado y admitido en esa cuenta y superficie.

Repositorio, servicio y publicación

Publicar este repositorio no publica automáticamente el plugin en el directorio universal de ChatGPT. La distribución pública en ese directorio requiere carga del ZIP, comprobaciones, revisión de OpenAI y publicación por el titular. Sites crea además una conexión de plugin del servicio para su propietario. El estado efectivo de esas conexiones se debe verificar en la cuenta; no se presume por la presencia de estos archivos.

Qué se conserva de CalRetenciones

Una hoja Tax Withholding, Arial, blanco y negro, identificación, conceptos, cantidad, unitario, subtotal, IVA, bruto, retenciones y neto. Las celdas calculadas contienen fórmulas Excel y valores en caché; las tarifas y mínimos llevan notas clásicas con sus fuentes. La aritmética usa Decimal y redondeo explícito.

assets/hazel-template.xlsx es un ejemplo sintético creado con el generador original. assets/workbook-blueprint.json conserva exactamente sus estilos y estructura de paquete. Las pruebas comparan cada celda, fórmula, valor, estilo, combinación y altura del caso equivalente. reference/build_retenciones.original.mjs conserva una copia del generador de origen con el encabezado empresarial parametrizado; requiere el runtime Artifact Tool de Codex y no es una dependencia del servidor.

El servidor portable utiliza el formato Open XML y las partes del libro sintético para ejecutarse en Cloudflare Workers. Corrige la comparación del mínimo de reteIVA antes de IVA cuando corresponde y permite IVA mixto, base especial explícita y umbrales con redondeo o inclusión documentados. El nombre del pagador es un dato del caso.

Regla fiscal y documentos

ChatGPT lee las fotos/PDF, identifica ambas partes e investiga la regla vigente por impuesto y concepto. El servicio verifica estructura, NIT/DV, vigencia declarada, fuentes oficiales, cobertura de conceptos, bases y conciliación; genera el archivo. No realiza OCR independiente ni autentica por sí solo un RUT. Un SHA acredita los bytes recibidos, no la veracidad de los campos extraídos.

El catálogo orienta hacia DIAN, Bogotá, Cota y Funza. No contiene una tarifa universal por CIIU, municipio o proveedor. Cada caso exige la norma y calidad aplicables al corte. Una proforma ya descontada se concilia desde su bruto para evitar una segunda deducción.

Privacidad y almacenamiento

Este repositorio no contiene RUT, facturas reales ni un maestro de terceros. Los datos permanecen en el proyecto/adjuntos elegidos en ChatGPT. Los archivos opcionalmente transferidos al servicio se leen de forma transitoria para obtener su huella y no se guardan. Las descargas y sus análisis se cifran con AES-GCM; la llave se entrega solo en el enlace. Los enlaces vencen en una hora y se realiza limpieza oportunista de los objetos vencidos.

El maestro fiscal local de cada empresa conserva su condición; un paquete para el proyecto es una copia de consulta fechada, no un segundo maestro ni una sincronización automática.

Desarrollo

Node.js 22.13 o posterior.

npm ci
npm test
npm run typecheck
npm run dev

La configuración de Sites está en .openai/hosting.json, con capacidad MCP y un bucket R2 BUCKET. La autenticación de la cuenta pertenece a Sites. El endpoint anterior /api/hazel/mcp redirige al endpoint protegido y no permite generar archivos de forma anónima. No requiere una API key de OpenAI ni invoca modelos de pago desde el servidor.

Para sincronizar las instrucciones y crear el ZIP instalable:

node --experimental-strip-types scripts/sync-skill.mjs
node scripts/package-plugin.mjs

El ZIP contiene plugin.json, mcp.json, las instrucciones y el icono. El servidor se despliega aparte mediante el flujo de Sites. El código también incluye un catálogo de marketplace para pruebas en clientes compatibles; ese catálogo no sustituye la publicación móvil.

Pruebas

Se prueban importes independientes, cantidades cero/doble, límites UVT, mínimo de reteIVA sobre el concepto, IVA mixto/base especial, proformas, calidades desconocidas, NIT/DV, vigencia, cobertura de todos los impuestos, fórmulas y formato del XLSX, file params, MCP, restricciones de URLs, límites de tamaño y cifrado. La revisión con Artifact Tool reabre, recalcula, modifica una cantidad, restaura y renderiza el libro. Esto no constituye una prueba nativa de Microsoft Excel ni una prueba en un teléfono físico.

Fuentes de la integración: plugins, proyectos, empaquetado, archivos y publicación.

Soporte

Abre una incidencia en GitHub sin adjuntar RUT, facturas ni datos personales a una conversación pública.