Referencia API MCP Tools | Docs contable.io

Inicio rapido

Envia un request JSON-RPC al servidor MCP y recibe una respuesta:

curl -X POST https://tu-servidor.com/mcp/sse \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "consultar_saldo_cuenta",
      "arguments": { "cuenta_codigo": "1105" }
    }
  }'

Respuesta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"cuenta_codigo\": \"1105\", \"cuenta_nombre\": \"Caja general\", \"saldo_neto\": 3500000.0, \"naturaleza\": \"debito\"}"
    }]
  }
}

El servidor expone 29 herramientas contables que un agente externo puede invocar para consultar saldos, crear facturas, clasificar transacciones y mas. Todas las operaciones de escritura crean registros en estado provisional que requieren aprobacion humana antes de afectar la contabilidad.

Arquitectura

┌──────────────┐     JSON-RPC      ┌──────────────────┐     SQL + RLS      ┌────────────┐
│              │  ──────────────►   │                  │  ───────────────►  │            │
│  Tu Agente   │     POST /mcp/sse │  MCP Server      │  SET LOCAL         │ PostgreSQL │
│  (LLM)       │  ◄──────────────  │  (bookkeeper-    │  company_id        │  (RLS)     │
│              │     JSON response │   contable)       │  ◄───────────────  │            │
└──────────────┘                   └──────────────────┘                    └────────────┘
       │                                    │
       │ MCP_TOKEN (Bearer)                 │ MCP_COMPANY_ID
       │ autenticacion                      │ contexto multi-tenant

El servidor MCP actua como puente entre tu agente y la base de datos contable. Cada request se ejecuta dentro de una transaccion PostgreSQL con Row-Level Security (RLS) activado, garantizando que un agente solo puede acceder a datos de la empresa configurada.

Autenticacion

El servidor valida un Bearer token en cada request.

Authorization: Bearer sk-mcp-abc123...

En produccion, el token es obligatorio. Requests sin token reciben HTTP 401.

En desarrollo, si no hay token configurado (MCP_TOKEN vacio), el servidor permite requests sin autenticacion y registra un warning en los logs.

# Variable de entorno del servidor
MCP_TOKEN=sk-mcp-tu-token-secreto

Protocolo (JSON-RPC 2.0)

Transporte

El servidor soporta dos transportes:

Transporte	Endpoint	Uso
Streamable HTTP	`POST /mcp/sse`	Recomendado. Request JSON-RPC, response JSON directa.
Legacy SSE	`GET /mcp/sse` + `POST /mcp/messages`	Compatibilidad con clientes MCP antiguos.

Ciclo de vida de una sesion

1. Inicializar

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

Respuesta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": {
      "name": "bookkeeper-contable",
      "version": "0.1.0"
    }
  }
}

La respuesta incluye el header Mcp-Session-Id que se debe enviar en requests posteriores.

2. Listar herramientas

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Respuesta:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "consultar_saldo_cuenta",
        "description": "Consulta el saldo actual de una cuenta contable por codigo PUC.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "cuenta_codigo": { "type": "string", "description": "Codigo PUC de la cuenta (ej: \"1105\", \"2205\", \"4135\")" },
            "fecha_corte": { "type": "string", "description": "Fecha de corte opcional en formato YYYY-MM-DD" }
          },
          "required": ["cuenta_codigo"]
        }
      }
    ]
  }
}

3. Invocar herramienta

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "buscar_tercero",
    "arguments": { "query": "Ferreteria", "tipo": "proveedor" }
  }
}

4. Terminar sesion

curl -X DELETE https://tu-servidor.com/mcp/sse \
  -H "Mcp-Session-Id: uuid-de-sesion"

Coercion de argumentos

Los LLMs a veces envian parametros con tipos incorrectos. El servidor coerce automaticamente:

Tipo esperado	Valor recibido	Resultado
`int`	`"30"`	`30`
`float`	`"1500000"`	`1500000.0`
`bool`	`"true"`	`True`
`bool`	`"false"`, `"0"`, `"no"`	`False`

Codigos de error JSON-RPC

Codigo	Significado	Causa tipica
`-32601`	Metodo no encontrado	`method` no es `initialize`, `tools/list`, ni `tools/call`
`-32602`	Herramienta no encontrada	El `name` en `tools/call` no existe en el registro
`-32603`	Error de ejecucion	Excepcion no capturada en la herramienta

Contexto multi-tenant

Cada empresa en contable.io es un tenant aislado. El servidor MCP necesita saber a cual empresa pertenece cada request.

# Variable de entorno del servidor
MCP_COMPANY_ID=550e8400-e29b-41d4-a716-446655440000

Al inicio de cada operacion, el servidor ejecuta:

SET LOCAL app.current_company_id = '550e8400-...';

Esto activa las politicas RLS de PostgreSQL. Todas las tablas filtran por company_id automaticamente. Un agente no puede acceder a datos de otra empresa, incluso si construye queries SQL directas (la herramienta consulta_sql tambien esta protegida por RLS).

Herramientas — Lectura

Estas herramientas consultan datos sin modificar la base de datos.

`consultar_saldo_cuenta`

Consulta el saldo actual de una cuenta contable por codigo PUC.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`cuenta_codigo`	`string`	Si	Codigo PUC de la cuenta (ej: `"1105"`, `"2205"`, `"4135"`)
`fecha_corte`	`string`	No	Fecha de corte en formato `YYYY-MM-DD`. Si se omite, consulta el saldo acumulado total.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "consultar_saldo_cuenta",
    "arguments": {
      "cuenta_codigo": "1105",
      "fecha_corte": "2026-02-28"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"cuenta_codigo\": \"1105\", \"cuenta_nombre\": \"Caja general\", \"tipo_cuenta\": \"asset\", \"es_detalle\": true, \"saldo_debito\": 5000000.0, \"saldo_credito\": 1500000.0, \"saldo_neto\": 3500000.0, \"naturaleza\": \"debito\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`cuenta_codigo`	`string`	Codigo PUC de la cuenta
`cuenta_nombre`	`string`	Nombre de la cuenta
`tipo_cuenta`	`string`	Tipo de cuenta (`asset`, `liability`, `equity`, `income`, `expense`)
`es_detalle`	`boolean`	`true` si es cuenta de detalle, `false` si es agrupadora
`saldo_debito`	`number`	Total acumulado de debitos
`saldo_credito`	`number`	Total acumulado de creditos
`saldo_neto`	`number`	Saldo neto segun la naturaleza de la cuenta
`naturaleza`	`string`	`"debito"` (clases 1, 5, 6, 7) o `"credito"` (clases 2, 3, 4)

Nota: El saldo incluye transacciones en estado confirmed y provisional. Para la naturaleza debito, saldo_neto = debito - credito. Para naturaleza credito, saldo_neto = credito - debito.

`buscar_tercero`

Busca un tercero (cliente o proveedor) por nombre, NIT o telefono.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`query`	`string`	Si	Texto de busqueda (nombre parcial, NIT o telefono)
`tipo`	`string`	No	Filtro por tipo: `"cliente"`, `"proveedor"` o `"ambos"` (default: `"ambos"`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "buscar_tercero",
    "arguments": {
      "query": "Ferreteria",
      "tipo": "proveedor"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{\"id\": \"a1b2c3d4-...\", \"nombre\": \"Ferreteria El Constructor\", \"razon_social\": \"Ferreteria El Constructor S.A.S.\", \"nit\": \"900123456-7\", \"tipo\": \"proveedor\", \"telefono\": \"3001234567\", \"email\": \"ventas@constructor.co\"}]"
    }]
  }
}

Campos de respuesta (por cada tercero)

Campo	Tipo	Descripcion
`id`	`string`	UUID del tercero
`nombre`	`string`	Nombre comercial o razon social
`razon_social`	`string`	Razon social legal
`nit`	`string`	NIT con digito de verificacion (ej: `"900123456-7"`)
`tipo`	`string`	`"cliente"`, `"proveedor"` o `"cliente, proveedor"`
`telefono`	`string`	Telefono o celular
`email`	`string`	Correo electronico

Nota: Retorna maximo 20 resultados. La busqueda es case-insensitive y busca coincidencias parciales en nombre, NIT, nombre comercial y telefono.

`buscar_producto`

Busca productos por nombre, SKU o codigo.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`query`	`string`	Si	Texto de busqueda (nombre parcial, SKU o codigo)
`solo_venta`	`boolean`	No	Si es `true`, solo retorna productos marcados como item de venta (default: `true`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "buscar_producto",
    "arguments": {
      "query": "consultoria",
      "solo_venta": true
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{\"id\": \"b2c3d4e5-...\", \"sku\": \"SRV-CONS01\", \"nombre\": \"Consultoria contable\", \"tipo\": \"SERVICE\", \"precio_venta\": \"2500000\", \"tipo_impuesto\": \"IVA 19%\", \"tarifa_iva\": \"19\", \"is_active\": true}]"
    }]
  }
}

Campos de respuesta (por cada producto)

Campo	Tipo	Descripcion
`id`	`string`	UUID del producto
`sku`	`string`	Codigo SKU
`nombre`	`string`	Nombre del producto o servicio
`tipo`	`string`	`"SERVICE"` o `"PRODUCT"`
`precio_venta`	`string`	Precio de venta en COP
`tipo_impuesto`	`string`	Nombre del tipo de impuesto (ej: `"IVA 19%"`)
`tarifa_iva`	`string`	Tarifa de IVA como porcentaje (ej: `"19"`)
`is_active`	`boolean`	Estado activo del producto

`consulta_sql`

Ejecuta una consulta SQL de solo lectura contra la base de datos contable.

Categoria: Lectura Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`sql`	`string`	Si	Query SQL. Solo `SELECT` y `WITH` permitidos. RLS filtra por empresa automaticamente.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "consulta_sql",
    "arguments": {
      "sql": "SELECT t.document_number, t.total_amount, t.status FROM transactions t WHERE t.transaction_type = 'SALES_INVOICE' ORDER BY t.created_at DESC LIMIT 10"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"columnas\": [\"document_number\", \"total_amount\", \"status\"], \"filas\": [{\"document_number\": \"FV-0042\", \"total_amount\": 5950000.0, \"status\": \"confirmed\"}], \"total_filas\": 1, \"truncado\": false}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`columnas`	`array`	Lista de nombres de columnas
`filas`	`array`	Lista de filas (cada fila es un objeto con los nombres de columna como claves)
`total_filas`	`integer`	Numero de filas retornadas
`truncado`	`boolean`	`true` si hay mas filas que el limite (50)

Warning: Esta herramienta tiene restricciones de seguridad estrictas:

Solo SELECT y WITH — cualquier INSERT, UPDATE, DELETE, DROP u otro DML/DDL es rechazado.

No se permiten multiples sentencias (sin punto y coma).

Acceso bloqueado a: pg_catalog, information_schema, pg_roles, pg_shadow, pg_authid, pg_user.

Funciones bloqueadas: lo_import, lo_export, pg_read_file, dblink, copy, set_config, current_setting, pg_sleep, pg_terminate_backend, generate_series.

Maximo 50 filas por consulta.

RLS filtra automaticamente por company_id.

`consultar_cuentas_por_pagar`

Consulta cuentas por pagar con dias de mora y estado de vencimiento.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`tercero_id`	`string`	No	UUID del proveedor para filtrar. Vacio = todos los proveedores.
`vencidas_solo`	`boolean`	No	Si es `true`, solo retorna facturas vencidas (default: `false`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "consultar_cuentas_por_pagar",
    "arguments": {
      "vencidas_solo": true
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{\"tercero_id\": \"a1b2c3d4-...\", \"tercero\": \"Distribuidora ABC\", \"nit\": \"900456789-1\", \"monto_pendiente\": 3200000.0, \"vencimiento\": \"2026-02-15\", \"dias_mora\": 19, \"estado\": \"vencida\", \"num_facturas\": 2}]"
    }]
  }
}

Campos de respuesta (por cada cuenta)

Campo	Tipo	Descripcion
`tercero_id`	`string`	UUID del proveedor
`tercero`	`string`	Nombre del proveedor
`nit`	`string`	NIT del proveedor
`monto_pendiente`	`number`	Monto total pendiente de pago en COP
`vencimiento`	`string`	Fecha de vencimiento mas antigua (`YYYY-MM-DD`)
`dias_mora`	`integer`	Dias de mora (0 si no esta vencida)
`estado`	`string`	`"vencida"` o `"vigente"`
`num_facturas`	`integer`	Numero de facturas de compra asociadas

Nota: Los resultados se ordenan por dias_mora descendente (las mas vencidas primero). Los saldos se calculan a partir de asientos contables en cuentas marcadas como cuentas_por_pagar.

`consultar_cuentas_por_cobrar`

Consulta cuentas por cobrar con dias de mora y estado de vencimiento.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`tercero_id`	`string`	No	UUID del cliente para filtrar. Vacio = todos los clientes.
`vencidas_solo`	`boolean`	No	Si es `true`, solo retorna facturas vencidas (default: `false`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "consultar_cuentas_por_cobrar",
    "arguments": {
      "tercero_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "vencidas_solo": false
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{\"tercero_id\": \"a1b2c3d4-...\", \"tercero\": \"Empresa XYZ\", \"nit\": \"800111222-3\", \"monto_pendiente\": 8500000.0, \"vencimiento\": \"2026-03-15\", \"dias_mora\": 0, \"estado\": \"vigente\", \"num_facturas\": 3}]"
    }]
  }
}

Campos de respuesta (por cada cuenta)

Campo	Tipo	Descripcion
`tercero_id`	`string`	UUID del cliente
`tercero`	`string`	Nombre del cliente
`nit`	`string`	NIT del cliente
`monto_pendiente`	`number`	Monto total pendiente de cobro en COP
`vencimiento`	`string`	Fecha de vencimiento mas antigua (`YYYY-MM-DD`)
`dias_mora`	`integer`	Dias de mora (0 si no esta vencida)
`estado`	`string`	`"vencida"` o `"vigente"`
`num_facturas`	`integer`	Numero de facturas de venta con estado `PENDING` o `PARTIAL`

`proximos_vencimientos_fiscales`

Consulta los proximos vencimientos fiscales DIAN segun el NIT de la empresa.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`dias_adelante`	`integer`	No	Dias hacia adelante para buscar vencimientos (default: `30`, max: `365`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "proximos_vencimientos_fiscales",
    "arguments": {
      "dias_adelante": 60
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{\"declaracion\": \"Retencion en la Fuente - Febrero 2026\", \"formulario\": \"350\", \"fecha\": \"2026-03-15\", \"dias_restantes\": 9, \"estado\": \"urgente\", \"periodo\": \"Febrero\"}, {\"declaracion\": \"IVA Bimestral - Enero-Febrero\", \"formulario\": \"300\", \"fecha\": \"2026-03-15\", \"dias_restantes\": 9, \"estado\": \"urgente\", \"periodo\": \"Enero-Febrero\"}]"
    }]
  }
}

Campos de respuesta (por cada vencimiento)

Campo	Tipo	Descripcion
`declaracion`	`string`	Nombre de la declaracion
`formulario`	`string`	Codigo de formulario DIAN (`"110"`, `"300"`, `"350"`)
`fecha`	`string`	Fecha de vencimiento (`YYYY-MM-DD`)
`dias_restantes`	`integer`	Dias hasta el vencimiento (negativo si ya vencio)
`estado`	`string`	`"pendiente"`, `"proxima"` (15 dias), `"urgente"` (7 dias) o `"vencida"`
`periodo`	`string`	Etiqueta del periodo (si aplica)
`rango_nit`	`string`	Rango de NIT aplicable (solo para renta)

Nota: Los vencimientos se calculan a partir del calendario fiscal DIAN y los dos ultimos digitos del NIT de la empresa. Incluye declaraciones vencidas hasta 30 dias atras. Los resultados se ordenan por dias_restantes ascendente (los mas urgentes primero).

`consultar_checklist_precierre`

Consulta el estado del checklist de cierre para un periodo contable.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`year`	`integer`	Si	Ano del periodo (ej: `2026`)
`month`	`integer`	Si	Mes del periodo (`1`-`12`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "consultar_checklist_precierre",
    "arguments": {
      "year": 2026,
      "month": 2
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"periodo\": \"2026-02\", \"periodo_nombre\": \"Febrero 2026\", \"estado_periodo\": \"OPEN\", \"bancos_conciliados\": true, \"inventario_contado\": true, \"transacciones_provisionales\": 3, \"razones_bloqueo\": [\"Hay 3 transacciones provisionales pendientes de aprobacion\"], \"puede_cerrar\": false, \"mensaje\": \"Periodo Febrero 2026: NO se puede cerrar. 1 bloqueo(s).\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`periodo`	`string`	Periodo en formato `YYYY-MM`
`periodo_nombre`	`string`	Nombre legible del periodo (ej: `"Febrero 2026"`)
`estado_periodo`	`string`	`"OPEN"` o `"CLOSED"`
`bancos_conciliados`	`boolean`	`true` si todos los bancos estan conciliados
`inventario_contado`	`boolean`	`true` si se realizo conteo de inventario
`transacciones_provisionales`	`integer`	Numero de transacciones provisionales pendientes
`razones_bloqueo`	`array`	Lista de razones por las que no se puede cerrar
`puede_cerrar`	`boolean`	`true` si el periodo esta listo para cerrar
`mensaje`	`string`	Resumen legible del estado

Herramientas — Escritura

Todas las herramientas de escritura crean registros con estado provisional. Un humano debe aprobar cada registro desde la interfaz web antes de que afecte la contabilidad oficial.

Security: Las herramientas de escritura validan que SUM(debitos) == SUM(creditos) con una tolerancia de 0.01 COP. Los asientos desbalanceados son rechazados.

`crear_tercero`

Crea un tercero (cliente o proveedor) con datos del RUT o manuales.

Categoria: Escritura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`nombre`	`string`	Si	Razon social o nombre completo
`tipo`	`string`	Si	`"cliente"`, `"proveedor"` o `"ambos"`
`nit`	`string`	Si	Numero de identificacion (NIT o cedula)
`telefono`	`string`	No	Telefono de contacto
`email`	`string`	No	Correo electronico
`direccion`	`string`	No	Direccion fisica
`ciudad`	`string`	No	Ciudad o municipio
`departamento`	`string`	No	Departamento
`nombre_comercial`	`string`	No	Nombre comercial (si difiere de razon social)
`tipo_persona`	`string`	No	`"juridica"` o `"natural"` (default: `"juridica"`)
`responsabilidad_fiscal`	`string`	No	`"responsable_iva"` o `"no_responsable_iva"`
`regimen_tributario`	`string`	No	`"SIMPLE"` u `"ordinario"`
`autorretenedor`	`boolean`	No	`true` si es autorretenedor
`gran_contribuyente`	`boolean`	No	`true` si es gran contribuyente
`facturador_electronico`	`boolean`	No	`true` si tiene facturacion electronica
`ciiu`	`string`	No	Codigo CIIU de actividad economica

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_tercero",
    "arguments": {
      "nombre": "Distribuidora Nacional S.A.S.",
      "tipo": "proveedor",
      "nit": "900987654",
      "telefono": "3109876543",
      "email": "contacto@distribuidora.co",
      "ciudad": "Bogota",
      "departamento": "Cundinamarca"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"tercero_id\": \"d4e5f6a7-...\", \"nombre\": \"Distribuidora Nacional S.A.S.\", \"tipo\": \"proveedor\", \"estado\": \"activo\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`tercero_id`	`string`	UUID del tercero creado
`nombre`	`string`	Razon social
`tipo`	`string`	Tipo asignado
`estado`	`string`	Siempre `"activo"` al crear

Nota: Si ya existe un tercero con el mismo NIT en la empresa, la herramienta retorna un error con tercero_existente_id y tercero_existente_nombre para que el agente use el registro existente.

`crear_producto`

Crea un producto o servicio con datos minimos.

Categoria: Escritura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`nombre`	`string`	Si	Nombre del producto o servicio
`tipo`	`string`	No	`"producto"` o `"servicio"` (default: `"servicio"`)
`precio_venta`	`string`	No	Precio de venta en COP (default: `"0"`)
`sku`	`string`	No	Codigo SKU. Si esta vacio, se genera automaticamente (`SRV-XXXXXXXX` o `PRD-XXXXXXXX`).
`tax_type_id`	`string`	No	UUID del tipo de impuesto. Si esta vacio, usa IVA 19% por defecto.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_producto",
    "arguments": {
      "nombre": "Asesoria tributaria",
      "tipo": "servicio",
      "precio_venta": "3500000"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"producto_id\": \"e5f6a7b8-...\", \"nombre\": \"Asesoria tributaria\", \"sku\": \"SRV-A1B2C3D4\", \"tipo\": \"servicio\", \"precio_venta\": \"3500000\", \"impuesto\": \"IVA 19%\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`producto_id`	`string`	UUID del producto creado
`nombre`	`string`	Nombre del producto
`sku`	`string`	Codigo SKU (generado o proporcionado)
`tipo`	`string`	`"servicio"` o `"producto"`
`precio_venta`	`string`	Precio de venta en COP
`impuesto`	`string`	Nombre del tipo de impuesto asignado

`crear_productos_lote`

Crea multiples productos/servicios en una sola operacion (maximo 100).

Categoria: Escritura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`productos_json`	`string`	Si	JSON string con array de objetos producto

Cada objeto en el array acepta:

Campo	Tipo	Requerido	Descripcion
`nombre`	`string`	Si	Nombre del producto o servicio
`tipo`	`string`	No	`"producto"` o `"servicio"` (default: `"servicio"`)
`precio_venta`	`string`	No	Precio de venta en COP (default: `"0"`)
`sku`	`string`	No	Codigo SKU. Si esta vacio, se genera automaticamente.
`tax_type_id`	`string`	No	UUID del tipo de impuesto. Si esta vacio, usa IVA 19% por defecto.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_productos_lote",
    "arguments": {
      "productos_json": "[{\"nombre\": \"Asesoria tributaria\", \"tipo\": \"servicio\", \"precio_venta\": \"3500000\"}, {\"nombre\": \"Widget X\", \"tipo\": \"producto\", \"precio_venta\": \"50000\", \"sku\": \"PRD-001\"}]"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"creados\": [{\"producto_id\": \"e5f6a7b8-...\", \"nombre\": \"Asesoria tributaria\", \"sku\": \"SRV-A1B2C3D4\", \"tipo\": \"servicio\", \"precio_venta\": \"3500000\", \"impuesto\": \"IVA 19%\"}, {\"producto_id\": \"f6a7b8c9-...\", \"nombre\": \"Widget X\", \"sku\": \"PRD-001\", \"tipo\": \"producto\", \"precio_venta\": \"50000\", \"impuesto\": \"IVA 19%\"}], \"fallidos\": [], \"total_creados\": 2, \"total_fallidos\": 0}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`creados`	`array`	Lista de productos creados exitosamente (mismo formato que `crear_producto`)
`fallidos`	`array`	Lista de `{indice, nombre, error}` para items que fallaron
`total_creados`	`integer`	Cantidad de productos creados
`total_fallidos`	`integer`	Cantidad de items que fallaron

Limites

Maximo 100 productos por llamada
SKUs duplicados dentro del lote se rechazan
SKUs que ya existen en la base de datos se rechazan
Todos los productos creados exitosamente se guardan en una sola transaccion

`crear_factura_venta_borrador`

Crea un borrador de factura de venta (provisional, requiere aprobacion).

Categoria: Escritura Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`tercero_id`	`string`	Si	UUID del cliente
`lineas`	`string`	Si	JSON array de lineas de factura (ver formato abajo)
`medio_pago`	`string`	No	`"credito"` o `"contado"` (default: `"credito"`)
`plazo_dias`	`integer`	No	Dias de plazo para pago a credito: `8`, `15`, `30`, `60`, `90` (default: `30`)
`notas`	`string`	No	Observaciones opcionales

Formato de cada linea en lineas:

{
  "producto_id": "uuid-del-producto",
  "cantidad": "2",
  "precio_unitario": "5000000"
}

El precio_unitario es opcional. Si se omite, usa el sale_price del producto.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_factura_venta_borrador",
    "arguments": {
      "tercero_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "lineas": "[{\"producto_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\", \"cantidad\": \"2\", \"precio_unitario\": \"5000000\"}]",
      "medio_pago": "credito",
      "plazo_dias": 30,
      "notas": "Servicio de consultoria febrero 2026"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"factura_id\": \"f6a7b8c9-...\", \"numero\": \"FV-0043\", \"tercero\": \"Empresa XYZ\", \"subtotal\": \"10000000\", \"iva\": \"1900000\", \"total\": \"11900000\", \"estado\": \"provisional\", \"mensaje\": \"Factura creada como borrador. Requiere aprobacion del contador.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`factura_id`	`string`	UUID de la factura creada
`numero`	`string`	Numero de documento (ej: `"FV-0043"`)
`tercero`	`string`	Nombre del cliente
`subtotal`	`string`	Subtotal antes de impuestos en COP
`iva`	`string`	Monto total de IVA en COP
`total`	`string`	Total de la factura (subtotal + IVA) en COP
`estado`	`string`	Siempre `"provisional"`
`mensaje`	`string`	Confirmacion con instruccion de aprobacion

Nota: La factura genera automaticamente los asientos contables: debito a Cuentas por Cobrar (1305), credito a Ingresos (4135), y credito a IVA por Pagar (2408). El IVA se calcula automaticamente a partir del tax_type del producto.

`crear_recibo_caja_borrador`

Crea un borrador de recibo de caja (pago recibido de un cliente).

Categoria: Escritura Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`tercero_id`	`string`	Si	UUID del cliente que realiza el pago
`monto`	`string`	Si	Monto total recibido en COP (ej: `"1500000"`)
`cuenta_banco_id`	`string`	Si	UUID de la cuenta bancaria donde se recibe el pago
`facturas_aplicar`	`string`	No	JSON array de UUIDs de facturas a las que aplicar el pago (default: `"[]"`)
`notas`	`string`	No	Observaciones opcionales

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_recibo_caja_borrador",
    "arguments": {
      "tercero_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "monto": "11900000",
      "cuenta_banco_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "notas": "Pago factura FV-0043"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"recibo_id\": \"a7b8c9d0-...\", \"numero\": \"RC-0015\", \"tercero\": \"Empresa XYZ\", \"total\": \"11900000\", \"banco\": \"Bancolombia ...4567\", \"estado\": \"provisional\", \"mensaje\": \"Recibo de caja creado como borrador. Requiere aprobacion del contador.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`recibo_id`	`string`	UUID del recibo creado
`numero`	`string`	Numero de documento (ej: `"RC-0015"`)
`tercero`	`string`	Nombre del cliente
`total`	`string`	Monto total del recibo en COP
`banco`	`string`	Nombre del banco y ultimos 4 digitos de la cuenta
`estado`	`string`	Siempre `"provisional"`
`mensaje`	`string`	Confirmacion con instruccion de aprobacion

Nota: El asiento contable generado es: debito a la cuenta del Banco, credito a Cuentas por Cobrar (1305).

`crear_comprobante_egreso_borrador`

Crea un borrador de comprobante de egreso (pago a un proveedor o beneficiario).

Categoria: Escritura Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`tercero_id`	`string`	Si	UUID del proveedor o beneficiario
`monto`	`string`	Si	Monto total del pago en COP (ej: `"2500000"`)
`cuenta_banco_id`	`string`	Si	UUID de la cuenta bancaria desde la que se paga
`concepto`	`string`	Si	Descripcion del pago (ej: `"Pago factura FP-001"`)
`cuenta_contable`	`string`	Si	Codigo PUC de la cuenta a debitar (ej: `"2205"` para proveedores, `"5110"` para honorarios)
`facturas_aplicar`	`string`	No	JSON array de UUIDs de facturas a las que aplicar el pago (default: `"[]"`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_comprobante_egreso_borrador",
    "arguments": {
      "tercero_id": "d4e5f6a7-b8c9-0123-defg-456789012345",
      "monto": "2500000",
      "cuenta_banco_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "concepto": "Pago factura FP-001 suministros oficina",
      "cuenta_contable": "2205"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"comprobante_id\": \"b8c9d0e1-...\", \"numero\": \"CE-0028\", \"tercero\": \"Distribuidora Nacional S.A.S.\", \"concepto\": \"Pago factura FP-001 suministros oficina\", \"total\": \"2500000\", \"banco\": \"Davivienda ...8901\", \"estado\": \"provisional\", \"mensaje\": \"Comprobante de egreso creado como borrador. Requiere aprobacion del contador.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`comprobante_id`	`string`	UUID del comprobante creado
`numero`	`string`	Numero de documento (ej: `"CE-0028"`)
`tercero`	`string`	Nombre del beneficiario
`concepto`	`string`	Descripcion del pago
`total`	`string`	Monto total del pago en COP
`banco`	`string`	Nombre del banco y ultimos 4 digitos
`estado`	`string`	Siempre `"provisional"`
`mensaje`	`string`	Confirmacion con instruccion de aprobacion

Nota: El asiento contable generado es: debito a la cuenta_contable especificada (gasto o CxP), credito a la cuenta del Banco. Si la cuenta_contable es una cuenta agrupadora (ej: "5110"), el sistema busca automaticamente la primera subcuenta activa de detalle.

`crear_transaccion_borrador`

Crea un borrador de comprobante contable generico con asientos de libre configuracion.

Categoria: Escritura Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`descripcion`	`string`	Si	Descripcion del comprobante contable
`lineas`	`string`	Si	JSON array de lineas de asiento (ver formato abajo)

Formato de cada linea en lineas:

{
  "cuenta_codigo": "5135",
  "debito": "500000",
  "credito": "0",
  "tercero_id": "uuid-opcional",
  "descripcion": "descripcion opcional de la linea"
}

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_transaccion_borrador",
    "arguments": {
      "descripcion": "Pago servicios publicos febrero 2026",
      "lineas": "[{\"cuenta_codigo\": \"5135\", \"debito\": \"850000\", \"credito\": \"0\"}, {\"cuenta_codigo\": \"1110\", \"debito\": \"0\", \"credito\": \"850000\"}]"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"transaccion_id\": \"c9d0e1f2-...\", \"numero\": \"CC-0012\", \"total_debitos\": \"850000\", \"total_creditos\": \"850000\", \"num_lineas\": 2, \"estado\": \"provisional\", \"mensaje\": \"Comprobante contable creado como borrador. Requiere aprobacion del contador.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`transaccion_id`	`string`	UUID de la transaccion creada
`numero`	`string`	Numero de documento (ej: `"CC-0012"`)
`total_debitos`	`string`	Suma total de debitos en COP
`total_creditos`	`string`	Suma total de creditos en COP
`num_lineas`	`integer`	Numero de lineas de asiento
`estado`	`string`	Siempre `"provisional"`
`mensaje`	`string`	Confirmacion con instruccion de aprobacion

Warning: Los asientos deben estar balanceados. Si total_debitos != total_creditos (con tolerancia de 0.01), la herramienta retorna error: "Asientos desbalanceados: debitos=X, creditos=Y".

`crear_cotizacion`

Crea una cotizacion (documento comercial sin impacto contable).

Categoria: Escritura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`tercero_id`	`string`	Si	UUID del cliente
`lineas`	`string`	Si	JSON array de lineas (mismo formato que `crear_factura_venta_borrador`)
`notas`	`string`	No	Observaciones opcionales
`vigencia_dias`	`string`	No	Dias de vigencia de la cotizacion (default: `"30"`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_cotizacion",
    "arguments": {
      "tercero_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "lineas": "[{\"producto_id\": \"b2c3d4e5-f6a7-8901-bcde-f12345678901\", \"cantidad\": \"1\"}]",
      "notas": "Precios sujetos a cambio sin previo aviso",
      "vigencia_dias": "15"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"cotizacion_id\": \"d0e1f2a3-...\", \"numero\": \"COT-0008\", \"tercero\": \"Empresa XYZ\", \"subtotal\": \"5000000\", \"iva\": \"950000\", \"total\": \"5950000\", \"vigencia\": \"2026-03-21\", \"estado\": \"draft\", \"mensaje\": \"Cotizacion COT-0008 creada. Vigente hasta 2026-03-21. Puedes verla en el dashboard.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`cotizacion_id`	`string`	UUID de la cotizacion creada
`numero`	`string`	Numero de documento (ej: `"COT-0008"`)
`tercero`	`string`	Nombre del cliente
`subtotal`	`string`	Subtotal antes de impuestos
`iva`	`string`	IVA total
`total`	`string`	Total de la cotizacion
`vigencia`	`string`	Fecha de vencimiento de la cotizacion (`YYYY-MM-DD`)
`estado`	`string`	Siempre `"draft"`
`mensaje`	`string`	Confirmacion con fecha de vigencia

Nota: Las cotizaciones no generan asientos contables ni afectan saldos. Son documentos comerciales informativos.

Herramientas — Inteligencia y memoria

Estas herramientas usan modelos ML y memoria persistente para mejorar la precision del agente.

`sugerir_clasificacion`

Sugiere una cuenta contable usando el clasificador ML entrenado con datos historicos de la empresa.

Categoria: Inteligencia Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`description`	`string`	Si	Descripcion de la transaccion o movimiento bancario
`amount`	`float`	No	Monto de la transaccion (mejora precision)
`contact_name`	`string`	No	Nombre del tercero (mejora precision)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "sugerir_clasificacion",
    "arguments": {
      "description": "Pago servicio de internet ETB",
      "amount": 189000,
      "contact_name": "ETB"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"cuenta_codigo\": \"5135\", \"confianza\": 0.92, \"alternativas\": [{\"cuenta_codigo\": \"5195\", \"confianza\": 0.05}], \"modelo\": \"per_company\", \"auto_confirmar\": true, \"mensaje\": \"Sugerencia: cuenta 5135 (confianza: 92%)\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`cuenta_codigo`	`string`	Codigo PUC de la cuenta sugerida
`confianza`	`number`	Nivel de confianza del modelo (0.0 a 1.0)
`alternativas`	`array`	Hasta 3 cuentas alternativas con sus niveles de confianza
`modelo`	`string`	`"per_company"` (modelo especifico), `"global"` (modelo generico), o `"none"`
`auto_confirmar`	`boolean`	`true` si la confianza es suficiente para confirmar automaticamente
`mensaje`	`string`	Resumen legible de la sugerencia

Nota: El umbral minimo de confianza es 0.70 (70%). Si ningun modelo alcanza este umbral, la herramienta retorna confianza: 0 y recomienda clasificacion manual. El modelo per_company tiene prioridad sobre el global.

`verificar_duplicado_reciente`

Verifica si existe una transaccion provisional reciente similar (posible duplicado).

Categoria: Inteligencia Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`tercero_nombre`	`string`	Si	Nombre del tercero a verificar
`monto`	`string`	Si	Monto total de la transaccion (ej: `"1500000"`)
`fecha`	`string`	No	Fecha de referencia `YYYY-MM-DD` (default: hoy)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "verificar_duplicado_reciente",
    "arguments": {
      "tercero_nombre": "Ferreteria El Constructor",
      "monto": "1500000"
    }
  }
}

Response (con duplicado encontrado)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"posibles_duplicados\": [{\"transaccion_id\": \"e1f2a3b4-...\", \"numero_documento\": \"FV-0041\", \"tercero\": \"Ferreteria El Constructor\", \"monto\": \"1500000\", \"tipo\": \"SALES_INVOICE\", \"creada\": \"2026-03-06T10:30:00+00:00\", \"similitud_nombre\": 1.0}], \"recomendacion\": \"Se encontraron 1 transaccion(es) provisional(es) similares. Confirma con el usuario si ya fue registrada antes de crear un nuevo borrador.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`posibles_duplicados`	`array`	Lista de transacciones similares encontradas
`posibles_duplicados[].transaccion_id`	`string`	UUID de la transaccion similar
`posibles_duplicados[].numero_documento`	`string`	Numero de documento
`posibles_duplicados[].tercero`	`string`	Nombre del tercero
`posibles_duplicados[].monto`	`string`	Monto de la transaccion
`posibles_duplicados[].tipo`	`string`	Tipo de transaccion
`posibles_duplicados[].creada`	`string`	Fecha de creacion (ISO 8601)
`posibles_duplicados[].similitud_nombre`	`number`	Similitud del nombre (0.0 a 1.0)
`recomendacion`	`string`	Recomendacion del sistema

Nota: Busca en las ultimas 24 horas transacciones provisionales con nombre similar (ratio > 0.8) y monto dentro de +/-10%. Usar antes de crear borradores desde WhatsApp para evitar registros duplicados.

`registrar_correccion`

Registra una correccion del usuario para que el agente aprenda de sus errores.

Categoria: Memoria Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`transaction_id`	`string`	Si	UUID de la transaccion corregida
`field`	`string`	Si	Campo corregido: `"account_code"`, `"contact_id"`, `"amount"`, `"description"`
`original_value`	`string`	Si	Valor original asignado por el agente
`corrected_value`	`string`	Si	Valor correcto establecido por el usuario

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "registrar_correccion",
    "arguments": {
      "transaction_id": "c9d0e1f2-a3b4-5678-cdef-901234567890",
      "field": "account_code",
      "original_value": "5195",
      "corrected_value": "5135"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"memory_entry_id\": \"f2a3b4c5-...\", \"rule_created\": true, \"memory_key\": \"correction:account_code:5135\", \"mensaje\": \"Regla creada: cuando 'account_code' sea '5195', usar '5135'.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`memory_entry_id`	`string`	UUID de la entrada de memoria
`rule_created`	`boolean`	`true` si se creo una regla nueva, `false` si se actualizo una existente
`memory_key`	`string`	Clave interna de la regla de memoria
`mensaje`	`string`	Confirmacion legible

Nota: Si la misma correccion se registra multiples veces, el contador de la regla se incrementa en lugar de crear duplicados. Las correcciones se almacenan en AgentMemory Layer 1 y se usan para mejorar futuras clasificaciones.

Herramientas — Automatizacion

Estas herramientas ejecutan procesos contables automatizados y gestionan tareas del agente.

`ejecutar_depreciacion_mensual`

Genera asientos de depreciacion mensual para todos los activos fijos del periodo.

Categoria: Automatizacion Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`year`	`integer`	Si	Ano del periodo (ej: `2026`)
`month`	`integer`	Si	Mes del periodo (`1`-`12`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ejecutar_depreciacion_mensual",
    "arguments": {
      "year": 2026,
      "month": 2
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"transaccion_id\": \"a3b4c5d6-...\", \"total_depreciacion\": 1250000.0, \"activos_procesados\": 5, \"categorias\": [{\"categoria\": \"Equipos de oficina\", \"activos\": 3, \"depreciacion\": 750000.0}, {\"categoria\": \"Vehiculos\", \"activos\": 2, \"depreciacion\": 500000.0}], \"estado\": \"provisional\", \"periodo\": \"2026-02\", \"mensaje\": \"Depreciacion generada: $1,250,000.00 para 5 activos. Transaccion creada como provisional — requiere aprobacion.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`transaccion_id`	`string`	UUID de la transaccion de depreciacion
`total_depreciacion`	`number`	Monto total depreciado en COP
`activos_procesados`	`integer`	Numero de activos fijos procesados
`categorias`	`array`	Desglose por categoria de activo
`estado`	`string`	Siempre `"provisional"`
`periodo`	`string`	Periodo procesado (`YYYY-MM`)
`mensaje`	`string`	Resumen legible del resultado

`ejecutar_automatch_bancario`

Ejecuta conciliacion automatica cruzando el extracto bancario con el libro contable.

Categoria: Automatizacion Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`bank_account_id`	`string`	Si	UUID de la cuenta bancaria a conciliar
`period_year`	`integer`	Si	Ano del periodo (ej: `2026`)
`period_month`	`integer`	Si	Mes del periodo (`1`-`12`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "ejecutar_automatch_bancario",
    "arguments": {
      "bank_account_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "period_year": 2026,
      "period_month": 2
    }
  }
}

Response

El formato de respuesta depende del servicio de conciliacion (auto_match_bank_period). Tipicamente incluye el numero de matches encontrados, sugerencias de conciliacion y lineas sin match.

`crear_tarea_agente`

Crea una tarea de proceso multi-paso para tracking de progreso.

Categoria: Automatizacion Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`process_type`	`string`	Si	Tipo de proceso: `"pre_close"`, `"reconciliation"`, `"depreciation"`, `"declaration"`
`process_label`	`string`	Si	Etiqueta legible (ej: `"Pre-cierre Febrero 2026"`)
`step_total`	`integer`	Si	Numero total de pasos del proceso (`1`-`50`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "crear_tarea_agente",
    "arguments": {
      "process_type": "pre_close",
      "process_label": "Pre-cierre Febrero 2026",
      "step_total": 5
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"task_id\": \"b4c5d6e7-...\", \"process_type\": \"pre_close\", \"process_label\": \"Pre-cierre Febrero 2026\", \"step_current\": 0, \"step_total\": 5, \"status\": \"pending\", \"mensaje\": \"Tarea 'Pre-cierre Febrero 2026' creada con 5 pasos.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`task_id`	`string`	UUID de la tarea creada
`process_type`	`string`	Tipo de proceso
`process_label`	`string`	Etiqueta del proceso
`step_current`	`integer`	Paso actual (inicia en `0`)
`step_total`	`integer`	Total de pasos
`status`	`string`	Estado inicial: `"pending"`
`mensaje`	`string`	Confirmacion

`actualizar_tarea_agente`

Actualiza el progreso de una tarea del agente.

Categoria: Automatizacion Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`task_id`	`string`	Si	UUID de la tarea a actualizar
`step_current`	`integer`	Si	Paso actual (`0` a `step_total`)
`status`	`string`	No	Nuevo estado: `"pending"`, `"in_progress"`, `"waiting_approval"`, `"completed"`, `"failed"`
`state_json`	`string`	No	JSON con datos de estado a mergear (ej: `'{"matched": 5}'`)

Transiciones de estado validas:

Estado actual	Puede ir a
`pending`	`in_progress`, `failed`
`in_progress`	`waiting_approval`, `completed`, `failed`
`waiting_approval`	`completed`, `failed`, `in_progress`

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "actualizar_tarea_agente",
    "arguments": {
      "task_id": "b4c5d6e7-f8a9-0123-bcde-f45678901234",
      "step_current": 3,
      "status": "in_progress",
      "state_json": "{\"bancos_conciliados\": 2, \"bancos_total\": 3}"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"task_id\": \"b4c5d6e7-...\", \"process_type\": \"pre_close\", \"process_label\": \"Pre-cierre Febrero 2026\", \"step_current\": 3, \"step_total\": 5, \"status\": \"in_progress\", \"state\": {\"bancos_conciliados\": 2, \"bancos_total\": 3}, \"mensaje\": \"Tarea actualizada: paso 3/5, estado=in_progress\"}"
    }]
  }
}

`enviar_documento_pdf`

Genera y envia el PDF de un documento por WhatsApp.

Categoria: Automatizacion Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`tipo_documento`	`string`	Si	Tipo: `"factura_venta"`, `"cotizacion"`, `"recibo_caja"`, `"comprobante_egreso"`
`documento_id`	`string`	Si	UUID del documento a enviar

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "enviar_documento_pdf",
    "arguments": {
      "tipo_documento": "factura_venta",
      "documento_id": "f6a7b8c9-d0e1-2345-abcd-ef6789012345"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"enviado\": true, \"tipo\": \"factura de venta\", \"filename\": \"FV-0043.pdf\", \"mensaje\": \"PDF de factura de venta enviado exitosamente\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`enviado`	`boolean`	`true` si se envio exitosamente
`tipo`	`string`	Tipo de documento legible
`filename`	`string`	Nombre del archivo PDF generado
`mensaje`	`string`	Confirmacion del envio

Warning: Esta herramienta solo funciona desde contexto WhatsApp (requiere numero de telefono del destinatario). Tiene un limite de 5 envios de PDF por sesion. El tamano maximo del PDF es 5 MB.

Herramientas — Cierre de periodo

Estas herramientas gestionan el proceso de cierre contable mensual.

`listar_cuentas_bancarias`

Lista las cuentas bancarias activas de la empresa.

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Ninguno.

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "listar_cuentas_bancarias",
    "arguments": {}
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "[{\"id\": \"c3d4e5f6-...\", \"banco\": \"Bancolombia\", \"numero_cuenta\": \"12345674567\", \"moneda\": \"COP\"}, {\"id\": \"d4e5f6a7-...\", \"banco\": \"Davivienda\", \"numero_cuenta\": \"98765438901\", \"moneda\": \"COP\"}]"
    }]
  }
}

Campos de respuesta (por cada cuenta)

Campo	Tipo	Descripcion
`id`	`string`	UUID de la cuenta bancaria
`banco`	`string`	Nombre del banco
`numero_cuenta`	`string`	Numero de cuenta
`moneda`	`string`	Codigo de moneda (ej: `"COP"`)

`consultar_tarea_activa_precierre`

Busca una tarea de pre-cierre activa (en progreso o esperando aprobacion).

Categoria: Lectura Nivel de riesgo: Bajo

Parametros

Parametro	Tipo	Requerido	Descripcion
`year`	`integer`	No	Ano del periodo (`0` = la mas reciente)
`month`	`integer`	No	Mes del periodo (`0` = la mas reciente)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "consultar_tarea_activa_precierre",
    "arguments": {
      "year": 2026,
      "month": 2
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"encontrada\": true, \"task_id\": \"b4c5d6e7-...\", \"estado\": \"in_progress\", \"etiqueta\": \"Pre-cierre Febrero 2026\", \"paso_actual\": 3, \"pasos_total\": 5, \"state\": {\"bancos_conciliados\": 2}, \"creada\": \"2026-03-05T14:00:00+00:00\", \"mensaje\": \"Tarea 'Pre-cierre Febrero 2026' en estado 'in_progress' (paso 3/5).\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`encontrada`	`boolean`	`true` si se encontro una tarea activa
`task_id`	`string`	UUID de la tarea
`estado`	`string`	Estado actual de la tarea
`etiqueta`	`string`	Etiqueta del proceso
`paso_actual`	`integer`	Paso actual
`pasos_total`	`integer`	Total de pasos
`state`	`object`	Datos de estado del proceso
`creada`	`string`	Fecha de creacion (ISO 8601)
`mensaje`	`string`	Resumen legible

`cerrar_periodo_contable`

Cierra definitivamente un periodo contable. Verifica el checklist de pre-cierre antes de cerrar.

Categoria: Escritura Nivel de riesgo: Alto

Parametros

Parametro	Tipo	Requerido	Descripcion
`year`	`integer`	Si	Ano del periodo (ej: `2026`)
`month`	`integer`	Si	Mes del periodo (`1`-`12`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "cerrar_periodo_contable",
    "arguments": {
      "year": 2026,
      "month": 2
    }
  }
}

Response (exito)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"exito\": true, \"periodo\": \"2026-02\", \"mensaje\": \"Periodo Febrero 2026 cerrado exitosamente. No se podran registrar mas movimientos en este periodo.\"}"
    }]
  }
}

Response (bloqueado)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"error\": \"No se puede cerrar el periodo\", \"razones_bloqueo\": [\"Hay bancos sin conciliar\", \"Hay 3 transacciones provisionales pendientes de aprobacion\"], \"checklist\": {\"puede_cerrar\": false, \"bancos_conciliados\": false, \"inventario_contado\": true, \"transacciones_provisionales\": 3}}"
    }]
  }
}

Warning: Esta operacion es irreversible. Una vez cerrado, no se pueden crear ni modificar transacciones en ese periodo. La herramienta verifica automaticamente el checklist de pre-cierre y rechaza el cierre si hay bloqueos pendientes.

Herramientas — Declaraciones tributarias

Estas herramientas generan y presentan declaraciones tributarias ante la DIAN.

`generar_borrador_declaracion`

Genera un borrador de declaracion tributaria a partir de la contabilidad.

Categoria: Escritura Nivel de riesgo: Medio

Parametros

Parametro	Tipo	Requerido	Descripcion
`tipo`	`string`	Si	Tipo de declaracion: `"iva"`, `"retefuente"` o `"reteica"`
`periodo`	`string`	Si	Periodo en formato `YYYY-MM` (ej: `"2026-01"`)

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generar_borrador_declaracion",
    "arguments": {
      "tipo": "iva",
      "periodo": "2026-01"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"declaracion_id\": \"e7f8a9b0-...\", \"formulario\": \"F300\", \"tipo\": \"iva\", \"periodo\": \"2026-01\", \"year\": 2026, \"period_code\": \"1\", \"estado\": \"borrador\", \"casillas\": {\"29\": \"15000000\", \"32\": \"2850000\", \"64\": \"1200000\", \"91\": \"1650000\"}, \"total_a_pagar\": \"1650000\", \"total_calculado\": \"1650000\", \"ajuste_redondeo\": \"0\", \"mensaje\": \"Borrador de F300 generado para 2026-01. Total a pagar: $1650000. Revise las casillas antes de presentar.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`declaracion_id`	`string`	UUID de la declaracion generada
`formulario`	`string`	Codigo de formulario DIAN: `"F300"` (IVA) o `"F350"` (ReteFuente)
`tipo`	`string`	Tipo de declaracion
`periodo`	`string`	Periodo fiscal
`year`	`integer`	Ano del periodo
`period_code`	`string`	Codigo de periodo DIAN (bimestre para IVA, mes para ReteFuente)
`estado`	`string`	Siempre `"borrador"`
`casillas`	`object`	Mapa casilla → valor (todas las casillas del formulario)
`total_a_pagar`	`string`	Total a pagar en COP
`total_calculado`	`string`	Total calculado antes de redondeo
`ajuste_redondeo`	`string`	Diferencia de redondeo
`mensaje`	`string`	Resumen con total a pagar

Nota: Para IVA, el period_code depende de la periodicidad configurada de la empresa: bimestral (default), cuatrimestral o anual. La declaracion de ReteICA aun no esta implementada.

`presentar_declaracion_dian`

Presenta una declaracion tributaria ante la DIAN via el portal MUISCA.

Categoria: Escritura Nivel de riesgo: Alto

Parametros

Parametro	Tipo	Requerido	Descripcion
`declaracion_id`	`string`	Si	UUID de la declaracion a presentar

Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "presentar_declaracion_dian",
    "arguments": {
      "declaracion_id": "e7f8a9b0-c1d2-3456-efab-789012345678"
    }
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"risk_level\": \"alto\", \"declaracion_id\": \"e7f8a9b0-...\", \"formulario\": \"F300\", \"total_a_pagar\": \"1650000\", \"estado\": \"requiere_confirmacion\", \"session_id\": null, \"mensaje\": \"ALTO RIESGO: Esta a punto de presentar F300 por $1650000 ante la DIAN. Para iniciar la sesion MUISCA, el usuario debe confirmar desde la interfaz web y posiblemente ingresar un codigo OTP.\", \"accion_siguiente\": \"Use el endpoint POST /api/v1/tax-declarations/e7f8a9b0-.../muisca/start para iniciar la sesion.\"}"
    }]
  }
}

Campos de respuesta

Campo	Tipo	Descripcion
`risk_level`	`string`	Siempre `"alto"`
`declaracion_id`	`string`	UUID de la declaracion
`formulario`	`string`	Codigo de formulario DIAN
`total_a_pagar`	`string`	Total a pagar en COP
`estado`	`string`	`"requiere_confirmacion"`, `"no_disponible"` o `"servicio_no_disponible"`
`session_id`	`string`	ID de sesion MUISCA (si se inicio)
`mensaje`	`string`	Descripcion detallada del estado
`accion_siguiente`	`string`	Instruccion para continuar el proceso

Warning: Esta herramienta inicia una interaccion real con el portal MUISCA de la DIAN. La declaracion debe estar en estado filed (aprobada internamente). La presentacion final requiere confirmacion del usuario desde la interfaz web y puede requerir un codigo OTP del representante legal.

Manejo de errores

Errores a nivel de herramienta

Cuando una herramienta encuentra un error de validacion o negocio, retorna un response exitoso (JSON-RPC result) pero con un campo error en el contenido:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"error\": \"Cuenta contable '9999' no existe\"}"
    }]
  }
}

Estos errores son esperados y el agente debe manejarlos — por ejemplo, pidiendo al usuario que corrija el dato.

Errores a nivel de protocolo

Cuando el servidor no puede procesar el request, retorna un error JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Tool execution failed. Check server logs for details."
  }
}

Codigo	Significado	Accion recomendada
`-32601`	Metodo no encontrado	Verificar que el `method` es correcto
`-32602`	Herramienta no encontrada	Verificar el nombre de la herramienta con `tools/list`
`-32603`	Error interno de ejecucion	Revisar los logs del servidor. Reintentar con parametros diferentes.
`401`	No autorizado (HTTP)	Verificar el token Bearer
`404`	Sesion no encontrada (HTTP)	Re-inicializar la sesion con `initialize`

Errores comunes y soluciones

Error	Causa	Solucion
`"tercero_id debe ser un UUID valido"`	Formato de UUID incorrecto	Usar formato `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`"Cuenta contable 'X' no existe"`	Codigo PUC no encontrado	Verificar el plan de cuentas con `consulta_sql`
`"Asientos desbalanceados"`	Debitos != creditos	Ajustar montos para que SUM(debito) == SUM(credito)
`"El periodo YYYY-MM esta cerrado"`	Periodo contable cerrado	Usar un periodo abierto
`"Ya existe un tercero con NIT X"`	NIT duplicado	Usar el `tercero_existente_id` retornado
`"Solo queries SELECT o WITH permitidos"`	DML en `consulta_sql`	Usar herramientas de escritura en lugar de SQL directo

Limites y seguridad

Estado provisional

Todas las herramientas de escritura crean registros con status: "provisional". Un contador humano debe aprobar cada registro desde la interfaz web para que pase a estado confirmed y afecte los estados financieros.

provisional → confirmed → (voided)
     ↓
   editable    inmutable

Validacion de balance

El sistema valida que cada transaccion cumpla la partida doble:

SUM(debitos) == SUM(creditos) ± 0.01

Restricciones de la herramienta SQL

Solo SELECT y WITH — sin DML ni DDL
Sin punto y coma (una sentencia por request)
Catalogos del sistema bloqueados
Maximo 50 filas por consulta
RLS activo (solo datos de la empresa)

Limites del envio de PDF

Maximo 5 envios de PDF por sesion de WhatsApp
Tamano maximo de PDF: 5 MB
Solo disponible desde contexto WhatsApp

Niveles de riesgo por herramienta

Nivel	Herramientas	Descripcion
Bajo	Todas las de lectura, `crear_tercero`, `crear_producto`, `crear_productos_lote`, `crear_cotizacion`, `registrar_correccion`, `crear_tarea_agente`, `actualizar_tarea_agente`	Sin impacto contable o impacto reversible
Medio	`consulta_sql`, `crear_factura_venta_borrador`, `crear_recibo_caja_borrador`, `crear_comprobante_egreso_borrador`, `crear_transaccion_borrador`, `ejecutar_depreciacion_mensual`, `ejecutar_automatch_bancario`, `enviar_documento_pdf`, `generar_borrador_declaracion`	Crea registros provisionales o ejecuta procesos
Alto	`cerrar_periodo_contable`, `presentar_declaracion_dian`	Irreversible o interaccion con sistemas externos (DIAN)