Contabilidad PyMe (Chile)

¿Para qué sirve?

Es un motor contable chileno con doble partida validada (Σ Debe = Σ Haber) que cierra el ciclo completo:

• Ventas (afectas, exentas, boletas) con asiento automático.
• Compras con IVA crédito y retención 10% en boletas de honorarios.
• Pagos a proveedores (caja/banco).
• Cobros de clientes (caja/banco/Payku).
• Libros de ventas y compras en pantalla + descarga CSV formato SII (compatible con Nubox, Defontana, Softland).
• Formulario 29 mensual calculado (débitos, créditos, retenciones, códigos SII).
• Cierre de mes: bloquea períodos ya declarados al SII. Reapertura auditada.

¿Cuándo lo necesitas?

• Empresa chilena (persona jurídica o EIRL) que necesita llevar contabilidad interna sin depender solo de la contadora externa.
• Quieres tener los libros de ventas y compras listos para exportar y subir al portal del SII.
• Necesitas calcular el F29 mensual con datos reales del período.
• Quieres integrar Payku para cobros online que generen su asiento automáticamente.

Fuera de Chile: el plugin es específico para el SII. La arquitectura permite adaptadores para otros países (AR/AFIP, MX/SAT, CO/DIAN), pero no vienen implementados.

Cómo activarlo

1. Registra el plugin contabilidad (viene registrado por defecto en plugins/plugins-registry.php).

2. Corre el instalador:

   docker exec wf_web php /var/www/html/plugins/contabilidad/install.php install

   O programáticamente:

   require_once __DIR__ . '/plugins/contabilidad/contabilidad.php';
   $res = ContabilidadController::install();

   Es idempotente: correrlo varias veces no rompe nada (usa CREATE TABLE IF NOT EXISTS + upserts).

3. Aparecen las páginas del contador en el menú lateral del CMS:

   • Cargar venta / compra / pago / cobro
   • Libro de ventas / compras
   • Formulario 29
   • Cierre de mes
   • Dashboard contable
   • Generar asientos / Validación

Configuración inicial

Copia plugins/contabilidad/config.example.php a config.php (o a config.local.php para overrides por instancia) y ajusta:

País y tasas fiscales

'country' => [
    'code'        => 'CL',
    'currency'    => 'CLP',
    'tax_adapter' => 'sii-cl',   // único implementado por ahora
],
'accounting' => [
    'iva_rate'                  => 0.19,   // 19% Chile
    'retencion_honorarios_rate' => 0.10,   // 10% BHE 2026
    'redondeo_decimales'        => 0,      // pesos chilenos = enteros
    'balance_tolerance'         => 0.01,   // Σ Debe = Σ Haber ±$0.01
],

Plan de cuentas

El plugin trae un plan mínimo chileno (seed_plan_de_cuentas_cl.sql) con las cuentas típicas. Puedes ajustar los códigos en config.php:

'cuentas' => [
    'caja'                 => '1.1.01',
    'banco'                => '1.1.02',
    'clientes'             => '1.1.03',
    'iva_credito'          => '1.1.04',
    'proveedores'          => '2.1.01',
    'iva_debito'           => '2.1.02',
    'retencion_honorarios' => '2.1.04',
    'ventas_afectas'       => '4.1.01',
    'ventas_exentas'       => '4.1.02',
],

Las páginas del contador buscan por código, no por ID, así que puedes usar tu propio plan de cuentas siempre que respetes los mismos códigos.

Roles

'access' => [
    // Roles que pueden CARGAR (mutaciones)
    'roles_contador' => ['contador'],
    // Roles que solo pueden LEER (dashboards, libros, F29)
    'roles_lectura'  => ['lectura'],
    // superadmin/admin siempre pueden todo
],

Crea los roles contador y lectura en Configuración → Admins (o en RBAC Manager) y asígnalos a los admins correspondientes.

Payku (opcional)

Si tienes el plugin Payku instalado y quieres que las ventas ofrezcan botón "Generar link de pago":

'payku' => [
    'integration_enabled' => true,
],

Cómo se usa día a día

Cargar una venta

1. Ve a Cargar venta.
2. Selecciona el cliente, tipo (afecta / exenta / boleta), monto neto, IVA (autocalculado), total.
3. Confirma. El sistema arma el asiento automático:
   • Debe: Clientes (por total)
   • Haber: Ventas afectas (neto) + IVA débito (19%)
4. La venta queda registrada y aparece en el Libro de ventas.

Cargar una compra

Igual que la venta pero al revés:

• Debe: Gasto/Activo + IVA crédito
• Haber: Proveedores

Si es una boleta de honorarios, el sistema agrega automáticamente:

• Debe: Honorarios
• Haber: Proveedores (por 90%) + Retención 10% (por 10%)

Cargar un pago o cobro

• Pago: Debe Proveedores / Haber Caja o Banco.
• Cobro: Debe Caja/Banco/Payku / Haber Clientes.

Libro de ventas / compras (formato SII)

En Libro de ventas o Libro de compras ves las operaciones del período en pantalla, con:

• Filtros por fecha.
• Totales de neto, IVA y total.
• Botón Descargar CSV — genera el archivo con BOM UTF-8, separador ; y los códigos SII estándar. Compatible con Nubox, Defontana y Softland.

Formulario 29 mensual

En F29 eliges el mes y el sistema calcula:

• Débitos fiscales (IVA de ventas del período).
• Créditos fiscales (IVA de compras del período).
• Retenciones (BHE 10%).
• Los códigos oficiales del SII con los valores listos para transcribir al portal.

Cierre de mes

Cuando ya declaraste el F29 al SII, ve a Cierre de mes → Cerrar período. Desde ese momento:

• No se pueden cargar nuevas ventas/compras/pagos/cobros con fecha de ese mes.
• Cualquier intento se rechaza con el error "período cerrado".
• Si necesitas corregir algo, Reabrir período queda auditado en el log.

Dashboard contable

Vista rápida con:

• Total de ventas del mes vs. mes anterior.
• Total de compras del mes.
• IVA por pagar (débitos − créditos).
• Cuentas por cobrar (con aging básico).

Se conecta con

• Payku — si está activo con payku.integration_enabled=true, el libro de ventas muestra botón "Generar link de pago" y el webhook (roadmap) creará cobros automáticamente.

• Otros plugins pueden registrar tipos de asiento (hooks). Por ejemplo, un plugin de RRHH puede registrar remuneracion como origen:

  ContabilidadController::registerAsientoOrigen('remuneracion', [
      'label'   => 'Remuneración de personal',
      'compile' => [RRHHController::class, 'compileAsientoRemuneracion'],
  ]);

  Los orígenes autorizados se whitelistean en config.php (hooks.allowed_origenes_externos).

Estructura del plugin

plugins/contabilidad/
├── contabilidad.php                  ← entry point
├── config.example.php                ← IVA, retención, cuentas, roles, Payku
├── install.php                       ← CLI installer (install/uninstall/status)
├── controllers/
│   └── contabilidad.controller.php   ← lifecycle + hooks + upserts CMS
├── lib/                              ← lógica compartida
│   ├── asientos.php                  ← compileAsientoVenta/Compra/Pago/Cobro
│   ├── auth.php                      ← wpb_require_role / csrf
│   ├── cierres.php                   ← mes_esta_cerrado / cerrar_mes
│   ├── rut.php                       ← validación módulo 11
│   └── sii.php                       ← códigos SII + CSV libros
├── migrations/
│   ├── create_contabilidad_tables.sql  ← 11 tablas contables
│   ├── seed_plan_de_cuentas_cl.sql     ← plan mínimo CL
│   └── drop_contabilidad_tables.sql    ← DROP TABLE (solo con --drop)
└── views/main.php

Estado del sistema

Para ver la versión instalada, orígenes de asiento registrados y config resumida:

docker exec wf_web php /var/www/html/plugins/contabilidad/install.php status

Desinstalación

Soft (quita el menú del CMS, conserva los datos):

docker exec wf_web php /var/www/html/plugins/contabilidad/install.php uninstall

Hard (borra también todas las tablas contables — ⚠ destructivo):

docker exec wf_web php /var/www/html/plugins/contabilidad/install.php uninstall --drop

Preguntas frecuentes

¿Reemplaza a mi contadora? No. Es una herramienta operativa para que la empresa lleve sus registros diarios. El contador sigue revisando, presentando declaraciones y firmando. Le entregas los CSV listos y el F29 calculado, ahorrándole horas de tipeo.

¿Sirve para otros países (Argentina, México, Colombia)? Hoy solo sii-cl está implementado. La arquitectura permite adaptadores nuevos en lib/sii*.php, pero hay que desarrollarlos.

¿Se pueden importar comprobantes del SII? No de fábrica. Roadmap: importar CSV descargado del portal del SII para conciliar.

¿Emite boletas / facturas electrónicas oficiales? No — es solo contabilidad interna. La emisión al SII requiere integración con un DTE certificado (SII directo, Bsale, Facturación.cl u otros).

¿Puedo customizar el plan de cuentas? Sí, cambia los códigos en config.php. Las páginas buscan por código, no por ID.

¿Funciona con múltiples empresas / holdings? No de fábrica — una empresa por instalación. Multi-empresa requiere desarrollo custom.

¿Los períodos cerrados se pueden reabrir? Sí, con reapertura auditada (queda registrado quién y cuándo). Pero es una operación crítica que idealmente no debería usarse: si ya declaraste al SII, cualquier cambio implica rectificar la declaración.

Roadmap

• Sesión C: sistema de eventos formal (asiento.created, cierre.done) para que otros plugins reaccionen.
• Webhook Payku → cobro automático (endpoint /payku-notify que crea cobro+asiento cuando Payku confirma).
• Cuentas por cobrar / pagar con aging (0-30, 31-60, 61-90, +90).
• Cuenta separada 1.1.05 "Cuenta Payku" para conciliar comisiones.
• Multipaís: adapters para AR (AFIP) y MX (SAT).

¿Qué sigue?

• Payku — para cobros online con asiento automático.
• Report Manager — para armar reportes contables custom.
• Data Protection — los datos de clientes están sujetos a Ley 21.719.