ppm install skill-contabilidad
ppm skill install-claude

Contabilidad PascalAI — guía de operación para agentes

El sistema

• Backend: ConServer (Delphi DataSnap REST), producción en https://conta.gustavoenriquez.com, BD PostgreSQL contdb en el VPS.
• Multi-tenant por NIT: cada empresa es un nit_empresa. La autenticación fija el tenant; nunca hay que pasar nit_empresa en los params.
• Contabilidad colombiana: PUC, partida doble, retenciones (fuente/IVA/ICA), NIIF, DIAN (facturación electrónica, exógena), nómina ley colombiana.

Los MCP

Server	Uso
conta-query (mcp-conta-query.exe)	Solo lectura. Preferirlo SIEMPRE para consultas y reportes.
conta (mcp-conta.exe)	Full: escrituras (marcadas * en la descripción del tool). Usarlo solo cuando la tarea exige modificar datos.

25 tools por dominio: conta_sistema, conta_empresa, conta_puc, conta_terceros, conta_comprobantes, conta_periodos, conta_retenciones, conta_centros_costo, conta_reportes, conta_activos_fijos, conta_presupuestos, conta_conciliacion, conta_flujo_efectivo, conta_exogena, conta_facturacion_electronica, conta_importacion, conta_nomina, conta_inventario, conta_ventas, conta_compras, conta_cuentas_pagar, conta_tesoreria, conta_cobranza, conta_pos, conta_crm.

Todos los tools reciben lo mismo: operation (nombre del método, sin prefijo CON_), params (string con un objeto JSON) y opcionalmente login/nit/password para cambiar de empresa o usuario en una llamada.

Regla #1: help antes de operar

operation:"help" devuelve todas las operaciones del módulo con su documentación extraída del código fuente del servidor, incluyendo la forma exacta de params. No inventes nombres de campos: si no conoces la operación, pide help primero. Los nombres de reportes llevan prefijo RPT_ (ej. RPT_BalancePrueba, no GetBalancePrueba).

Convenciones de params: fechas ISO "yyyy-mm-dd", montos numéricos sin formato, anio/mes enteros. Las listas suelen paginar con page y page_size. El servidor responde errores como {"error": "..."}.

Regla #2: integridad contable — el auxiliar y el mayor van JUNTOS

El servidor separa los módulos auxiliares del libro mayor: las operaciones Save* registran en el auxiliar (quedan PENDIENTE/BORRADOR) y las Contabilizar* generan el comprobante contable. Un Save* sin su contabilización deja el auxiliar desincronizado del mayor — un estado inválido que NUNCA debes producir.

Protocolo obligatorio para toda operación que introduzca valores económicos (saldos iniciales, movimientos, ajustes, facturas, pagos, depreciaciones):

1. Planea la partida doble ANTES de mutar: qué cuenta se debita, cuál se acredita, en qué comprobante. Si falta un dato — típicamente la cuenta de contrapartida — pregunta al usuario PRIMERO; nunca guardes y preguntes después.
2. Ejecuta el ciclo completo en la misma tarea: SaveMovimientoTesoreria → ContabilizarMovimiento; SaveAjusteInventario → ContabilizarAjuste; SaveAPFactura → AprobarAPFactura → ContabilizarAPFactura; SaveAPPago → ContabilizarAPPago; SaveTransferencia → ContabilizarTransferencia.
3. Operaciones sin Contabilizar propio (ej. saldo inicial en SaveCaja, saldos iniciales de inventario): el asiento se hace a mano — SaveComprobante (débito: la cuenta del auxiliar, ej. banco 1110xx; crédito: la contrapartida que confirme el usuario — en aperturas, capital 31xx o resultados acumulados 37xx) y ContabilizarComprobante.
4. Algunas operaciones sí contabilizan solas: EjecutarDepreciacion (comprobante DEP), BajaActivoFijo (BAJ), RevaluarActivoFijo (REVAL). Revisa el doc en help; si la respuesta trae comp_tipo/comp_numero, NO dupliques el asiento.
5. Verifica al cerrar: el saldo del auxiliar debe coincidir con el de su cuenta contable (RPT_BalancePrueba o el reporte del módulo). Si difieren, repórtalo al usuario — no lo dejes pasar en silencio.

Flujos contables clave

Registrar un asiento (comprobante)

1. conta_periodos GetPeriodos {anio} — verificar que el período de la fecha esté ABIERTO; si no, AbrirPeriodo {anio, mes} (requiere permiso).
2. conta_comprobantes GetTiposComprobante — elegir tipo_codigo (CI, CE, CG, FV...).
3. SaveComprobante con cabecera + movimientos[] (cada línea: cuenta_codigo, debito/credito, tercero, centro de costo opcional). Débitos = créditos o el servidor rechaza. Queda en estado BORRADOR.
4. ContabilizarComprobante {tipo_codigo, numero} — pasa a CONTABILIZADO y actualiza saldos.
5. Un comprobante contabilizado NUNCA se borra: AnularComprobante genera la reversión.

Retenciones

Antes de facturar/causar con un tercero: conta_retenciones GetRetencionSugerida {tercero_tipo_id, tercero_numero_id, base_gravable} — devuelve las líneas de retención (cuentas, tarifas, montos) que deben añadirse al comprobante.

Consultas y reportes (usar conta-query)

• Saldos y estados: conta_reportes → RPT_BalancePrueba {anio, mes_desde, mes_hasta}, RPT_BalanceGeneral, RPT_EstadoResultados, RPT_LibroMayor, RPT_LibroDiario, RPT_Cartera, RPT_Dashboard, RPT_LibroIVA, RPT_LibroTercero, RPT_AnalisisHorizontal.
• Movimientos: conta_comprobantes GetComprobantes {fecha_desde, fecha_hasta, estado, buscar, page}.
• Maestros: conta_puc GetPlanCuentas, conta_terceros GetTerceros.

Ciclo comercial

Ventas: conta_ventas (cotización → factura → contabilización; la FV genera el comprobante). Compras: conta_compras (orden → recepción → factura proveedor) y conta_cuentas_pagar para causación y pagos. Cartera/cobros: conta_cobranza (recibos de caja, acuerdos, estado de cuenta). Caja/bancos: conta_tesoreria; conciliación con conta_conciliacion (importa extracto CSV y concilia).

Cierres

Mensual: conta_periodos CerrarPeriodo. Anual: operaciones de cierre en el mismo tool (traslado de resultados). No cerrar períodos sin confirmación explícita del usuario.

Precauciones

• Explorar con conta-query; pasar a conta (full) solo para escribir.
• Operaciones destructivas o de cierre (Anular*, Cerrar*, Delete*, importaciones masivas, emisión de facturación electrónica DIAN) → confirmar con el usuario antes de ejecutar.
• Multi-empresa: las credenciales (env vars CONTA_LOGIN/CONTA_NIT/ CONTA_PASSWORD) fijan el tenant; para operar otra empresa, cambiar las env vars o pasar login/nit/password en la llamada.
• Los MCP se instalan con ppm install mcp-conta / ppm install mcp-conta-query desde https://registry.pascalai.org.