com.contadeo/mcp

Ajusta las existencias de un producto del inventario por su código: relativo con `ajuste` (+ entra mercadería, - sale) o absoluto con `stock` (fijar el total tras un conteo físico; null = quitar el control de existencias). Prefiere `ajuste`: es atómico frente al descuento automático de las facturas. Inventario ligero: mueve el número actual, NO lleva historial de movimientos (kardex). No lo uses por una venta o devolución con comprobante: la factura y la nota de crédito ya mueven el stock solas.

Marca una factura AUTORIZADA como ANULADA en Contadeo (registro interno; el trámite formal ante el SRI se realiza en su portal). Si la factura ya no admite anulación (fuera del plazo legal o emitida a consumidor final), NO la anules: reversa con una NOTA DE CRÉDITO (preparar_nota_credito / emitir_nota_credito). Una factura con TRANSACCIONES ASOCIADAS vivas —notas de crédito o débito que la modifican y no están anuladas, o comprobantes de retención recibidos conciliados con ella— devuelve 400 con la lista en `problemas`: hay que desarmarlas en orden inverso (primero lo que cuelga, después la factura) y volver a intentarlo; las retenciones las anula el cliente que las emitió, no el titular de la cuenta. Es una acción sensible: confírmala explícitamente con el usuario antes de llamarla.

Lista los clientes del catálogo, opcionalmente filtrados por texto (busca en razón social e identificación). Úsalo para obtener la identificación y datos de un comprador antes de emitir una factura.

Lista los productos/servicios del catálogo, opcionalmente filtrados por texto (código o descripción). Cada producto trae su precio unitario, su tarifa de IVA y sus existencias (`stock`; null = sin control, típico en servicios; puede ser negativo), más categoría y unidad. Los archivados (activo=false) no aparecen. Es un inventario ligero SIN historial de movimientos. Úsalo para armar los detalles de una factura con precios correctos o para responder cuánto queda de un producto.

Guarda de una vez si los comprobantes de un proveedor dan crédito de IVA, y lo aplica a los que ya tengas cargados. Se decide UNA vez por proveedor, no comprobante por comprobante. PROTOCOLO OBLIGATORIO, igual que al emitir: llama PRIMERO sin `confirmar` — eso NO escribe nada y devuelve el impacto (cuántos comprobantes, cuánto IVA y qué períodos se mueven). MUÉSTRASELO al usuario y espera su confirmación explícita; solo entonces vuelve a llamar con `confirmar: true` y el `confirmToken` que te devolvió. Estás moviendo una cifra que se declara ante el SRI. Si el usuario quiere una excepción para un comprobante suelto, usa `alcance: 'comprobante'` con su `compraId`: eso NO cambia la decisión guardada del proveedor.

Borrador de SOLO LECTURA del Anexo Transaccional Simplificado del período: conteos por sección (compras, ventas, ventas por establecimiento, anulados), los totales de cabecera, el informe de validación contra la ficha técnica del SRI (reglas V1-V17 y N1-N9, con severidad, ruta y mensaje), las filas que quedaron EXCLUIDAS del anexo con su motivo, y las brechas conocidas del producto (lo que le falta a Contadeo, no al anexo). También dice si el período YA tiene un anexo generado y archivado (bloque `snapshot`, resuelto contra el historial) y con qué huella. NUNCA devuelve el XML ni el ZIP del anexo: llevan la identificación de todos los clientes y proveedores del período, y esos solo se descargan desde el panel. El período es mensual (`mes`, 1-12) o semestral (`semestre`: 1=enero-junio, 2=julio-diciembre) — el semestral es una OPCIÓN del contribuyente RIMPE, no un dato de su régimen: confírmalo con el usuario, no lo asumas. Requiere el módulo ATS contratado (402 si la cuenta no lo tiene). Muestra SIEMPRE el campo `disclaimer` de la respuesta.

Próximos vencimientos de declaraciones (IVA mensual o semestral RIMPE, renta, retenciones, ATS) según el noveno dígito del RUC y el régimen del emisor, con fecha límite y días restantes. Úsalo cuando el usuario pregunte cuándo le toca declarar o qué vence pronto. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Devuelve el detalle y estado actual de un comprobante por su ID: estado, número completo, clave de acceso, número de autorización del SRI, fechas, totales y mensajes de error si fue rechazado. Con eventos:true incluye además el timeline paso a paso de la emisión (firmado, enviado, respuesta del SRI, reintentos, contingencia) — úsalo para explicar en qué punto está una emisión lenta o por qué falló.

Devuelve la cuenta de Contadeo del usuario: nombre, ambiente activo (1=Pruebas, 2=Producción) y el plan que RIGE su emisión con el consumo del mes (usoPlan.regimen: 'pool' = empresa patrocinada que emite con el plan y el cupo de otra cuenta; lo contratado por ELLA está en usoPlan.propio — no confundas los dos al responder por el plan). Llámalo al inicio de una sesión de facturación o cuando el usuario pregunte por su plan o su cupo. Si la cuenta administra VARIAS empresas trae además el bloque `multiempresa` con todas y cuál está activa: dilo antes de facturar.

Auxiliar de la declaración mensual de retenciones en la fuente de RENTA (formulario 103) que TU emisor practicó al pagar: agrupa por código de retención del SRI (`baseImponible`, `valor` y `cantidad` de líneas por código), más totales y el vencimiento del período (según el catálogo; null si tu perfil no tiene la obligación — hoy solo la tienen los contribuyentes especiales). Excluye la retención de IVA (esa va al F104/ATS, no al 103). No es la declaración oficial: el mapeo código→casillero lo confirma tu contador (`aValidar: true`). Para el detalle línea a línea (con el RUC del sujeto retenido) usa consultar_retenciones. Muestra SIEMPRE el campo `disclaimer` de la respuesta. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Borrador del F104 (declaración de IVA) del período, EXPLICADO. Además de las cifras del servidor (débito 429, crédito 564, impuesto causado 601, retenciones 609, a pagar 902 o crédito 615, vencimiento según régimen: mensual general, semestral RIMPE Emprendedor, null si no declara IVA), la respuesta trae `resumen_ejecutivo` (una frase en español llano: muéstrala), `desglose_explicado` (paso a paso anclado a los casilleros del formulario oficial), `alertas` (observaciones proactivas: ventas con IVA 0, factor 563, crédito del mes anterior sin descontar, compras faltantes: muéstralas TODAS) y `proyeccion_proximo_mes` (qué se arrastra al 605/483 y por qué). No es la declaración oficial. Cuando el usuario pregunte POR QUÉ un número da lo que da, complementa con consultar_libro_ventas / consultar_libro_compras (el detalle comprobante a comprobante); para la versión narrada para principiantes usa explicar_f104; antes de declarar sugiere validar_f104; para '¿qué pasa si...?' usa simular_f104. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Libro de compras del período: comprobantes recibidos de proveedores con sus bases de IVA, retenciones y totales — insumo para el crédito tributario y el ATS. Devuelve las líneas y los totales del mes. Es el detalle detrás del crédito tributario (564) del F104: úsalo cuando el usuario pregunte POR QUÉ su crédito da lo que da o si le falta registrar algún gasto; validar_f104 hace este cruce automáticamente. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Libro de ventas del período: comprobantes emitidos AUTORIZADOS con sus bases de IVA y totales — insumo para la declaración y el ATS. Devuelve las líneas y los totales del mes. Es el detalle detrás del IVA de ventas (429) del F104: úsalo cuando el usuario pregunte POR QUÉ su débito da lo que da o qué comprobante mueve el total; validar_f104 hace este cruce automáticamente. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Checklist de obligaciones según el perfil del emisor (régimen, obligado a contabilidad, contribuyente especial, persona natural o sociedad): qué declaraciones y anexos le tocan y cuáles no. Los ítems con aValidar:true están en revisión normativa — díselo al usuario. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Devuelve las tablas de referencia oficiales que aplican a la facturación electrónica en Ecuador: tipos de identificación, tarifas de IVA vigentes, formas de pago, regla de consumidor final y ventana de anulación. Consúltalo en vez de responder de memoria cuando el usuario pregunte por códigos, tarifas o reglas del SRI.

Retenciones que TU emisor practicó a otros en un mes (Renta, IVA, ISD): detalle línea a línea y totales por tipo. Es insumo para el ATS de compras. OJO CON EL SENTIDO: son las retenciones que tú HICISTE al pagar, no las que TE hicieron tus clientes al cobrarles — esas constan en los comprobantes de retención que ellos te emitieron y se descuentan en tu declaración. Si el usuario pregunta por 'lo que me retuvieron', aclárale esa diferencia. Solo contiene datos desde jun-2026. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Autocompleta los datos de un comprador a partir de su RUC (13 díg.) o cédula (10 díg.): busca primero en tu directorio y, si no está, en el catastro público del SRI — devuelve razón social, dirección y régimen. Trae `advertencias` (p. ej. contribuyente FANTASMA, inactivo o con transacciones inexistentes): MUÉSTRALAS al usuario antes de facturarle, para evitar rechazos del SRI. Úsalo antes de preparar_factura cuando solo tengas el número; si no hay datos, pide los del comprador o usa crear_cliente.

Proyecta los ingresos anuales del emisor (lo facturado en Contadeo: facturas + notas de débito − notas de crédito autorizadas) frente a los límites del RIMPE y devuelve VERDE/AMARILLO/ROJO (o NO_APLICA en régimen general). Úsalo cuando el usuario pregunte cómo va con el límite de su régimen o si le conviene cambiarse. Aclara siempre que solo ve lo facturado en Contadeo. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Devuelve TODO lo necesario para emitir un comprobante: los emisores (RUC, razón social) con sus establecimientos y puntos de emisión, los certificados de firma disponibles por emisor, y el semáforo `listoParaEmitir` con la lista `porCompletar` de requisitos que faltan (firma electrónica, emisor). LLÁMALO SIEMPRE antes de la primera emisión: si `listoParaEmitir` es false, informa al usuario TODO lo que falta de una vez y resuélvelo ANTES de preparar facturas — no avances por prueba y error. Usa `certificadoIdSugerido` y `serieSugerida` de cada emisor para no inventar IDs. Si la cuenta administra VARIAS empresas la respuesta trae el bloque `multiempresa`: di bajo qué empresa y RUC vas a facturar y confírmalo antes de preparar. OJO: para saber CUÁNDO declarar NO calcules con el RUC de esta respuesta — usa consultar_calendario_tributario.

Da de alta un cliente (comprador) en el catálogo de la cuenta. Valida la cédula/RUC localmente (dígito verificador) antes de enviar. Úsalo cuando buscar_clientes no encuentre al comprador, o para registrar varios clientes que el usuario dicte o pegue.

Da de alta un producto o servicio en el catálogo: código único, nombre, precio unitario (sin IVA) y tarifa de IVA; opcionalmente existencias iniciales, categoría y unidad. Con el catálogo poblado, las facturas se preparan por productoId sin reescribir precios. Úsalo para registrar el inventario que el usuario dicte.

Devuelve una URL temporal (expira en 1 hora) para descargar el RIDE (PDF) de un comprobante AUTORIZADO. Comparte la URL con el usuario.

Devuelve una URL temporal (expira en 1 hora) para descargar el XML autorizado por el SRI de un comprobante.

Emite la factura: se firma con el certificado del emisor y se transmite al SRI. Es un DOCUMENTO TRIBUTARIO — llámalo SOLO después de que el usuario vio el resumen de preparar_factura y confirmó explícitamente ESA factura; nunca emitas amparado en una autorización genérica dada antes de mostrar el resumen. El payload (infoFactura + detalles + idempotencyKey + confirmToken) debe venir de preparar_factura sin modificarlo; este tool re-valida el cuadre y el confirmToken localmente y rechaza si el payload no cuadra, fue modificado a mano o el resumen confirmado expiró. Si un intento anterior falló por red o timeout, reintenta con el MISMO payload: el idempotencyKey evita duplicados y secuenciales quemados. Respuesta 202 (asíncrona): usa esperar_autorizacion después. Para lotes confirmados usa emitir_lote.

Emite en secuencia las facturas de un lote preparado con preparar_lote (máximo 25). Son DOCUMENTOS TRIBUTARIOS — llámalo SOLO después de que el usuario confirmó explícitamente el resumenAgregado del lote entero; una confirmación por lote basta, pero tiene que existir y ser sobre el resumen mostrado. Primero re-valida el cuadre Y el confirmToken de TODAS localmente: si alguna no cuadra o su token no coincide/expiró, NO se emite ninguna. Luego emite una a una (202 asíncrona); si una falla, continúa con las siguientes y lo reporta — salvo error de credencial, cupo o rate limit (401/402/429), donde se detiene y marca el resto NO_INTENTADA. Después llama a esperar_autorizacion con el array `ids` de las encoladas (timeout sugerido 90). Reintentos: vuelve a llamar solo con las fallidas, conservando cada idempotencyKey (no se duplican facturas ni se queman secuenciales).

Emite la nota de crédito: se firma con el certificado del emisor y se transmite al SRI (documento tributario REAL que revierte la factura). Llámalo SOLO tras mostrar el resumen de preparar_nota_credito y recibir confirmación explícita. El payload (infoNotaCredito + detalles + idempotencyKey + confirmToken) debe venir de preparar_nota_credito sin modificarlo; este tool re-valida el cuadre y el confirmToken localmente y rechaza si no cuadra, fue modificado a mano o el resumen expiró. Respuesta 202 (asíncrona): usa esperar_autorizacion después. Reintentos con el MISMO payload: el idempotencyKey evita duplicados.

Hace polling de uno o VARIOS comprobantes hasta que el SRI los resuelva (AUTORIZADO, RECHAZADO, DEVUELTA o ANULADO) o se agote el tiempo. Llámalo inmediatamente después de emitir_factura (parámetro `id`) o de emitir_lote (parámetro `ids` con todos los comprobanteId encolados; timeout sugerido 90). El SRI suele resolver en 5–30 segundos. Si se agota el tiempo NO es un error: la respuesta trae el estado intermedio actual (BORRADOR, FIRMADO, ENVIADO o CONTINGENCIA) — repórtaselo al usuario y vuelve a llamar, o usa consultar_comprobante con eventos:true para ver el timeline completo. Los comprobantes que queden AUTORIZADO traen `descargas` con las URLs temporales del RIDE (PDF) y el XML autorizado: compártelas con el usuario sin llamar a descargar_ride/descargar_xml.

Explica el F104 casillero por casillero, al nivel de alguien que NUNCA ha declarado: la ecuación completa (IVA cobrado 429 − crédito de compras 564 = impuesto causado 601; menos saldo del mes anterior 605 y retenciones 609 = a pagar 902 o crédito 615), por qué unas ventas altas pueden dar IVA generado $0 (ventas a crédito 480-486 cuyo IVA aparece el mes siguiente en el 483, o ventas tarifa 0%), qué es el factor de proporcionalidad (563) y por qué acumular crédito no es ganar. Dos modos: (a) con `anio` y `mes` narra el borrador de Contadeo de ese período; (b) con `cifras` narra números que el usuario pegó de una declaración (suya o ya presentada en el SRI), con chequeos aritméticos suaves; los casilleros que no reconoce los lista sin inventarles significado. Úsalo cuando el usuario pregunte qué significa un campo, por qué paga lo que paga, o pegue su formulario. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Glosario del SRI en lenguaje llano: RIDE, clave de acceso, RIMPE, retención, crédito tributario, consumidor final, punto de emisión, firma electrónica, F104, nota de crédito, ambiente de pruebas… ÚSALO SIEMPRE que el usuario pregunte qué significa un término, o cuando detectes que no lo entiende, EN VEZ de explicarlo de memoria: en materia tributaria ecuatoriana un matiz equivocado suena igual de convincente que el dato correcto. Acepta el término tal como lo escribió el usuario, incluso coloquial ('el pdf de la factura', 'me retuvieron'). Sin `termino` devuelve el glosario completo, útil para orientar a alguien que recién empieza. Si un término trae `consultaCon`, llama a esa herramienta para dar la cifra vigente en vez de citar números de memoria.

Lista los comprobantes emitidos, con filtros opcionales por estado (AUTORIZADO, RECHAZADO, DEVUELTA, ENVIADO, ANULADO...), ambiente y emisor. Úsalo cuando el usuario pregunte por sus facturas o el estado de emisiones recientes. Cada fila trae su `ambiente`: la lista puede mezclar Pruebas y Producción, así que léelo por fila antes de sacar conclusiones sobre lo que el usuario declaró de verdad.

El panorama COMPLETO de la cuenta en una sola llamada: si está lista para emitir (emisor + firma electrónica vigente), qué declaraciones vencen pronto, el semáforo del límite RIMPE y un `resumen` ya redactado en lenguaje llano. ÚSALO al empezar una sesión, cuando el usuario pregunte '¿cómo voy?', '¿qué me toca este mes?', '¿estoy al día?' o cualquier cosa sobre su estado, en vez de encadenar consultar_cuenta + consultar_obligaciones + consultar_semaforo_rimpe. Lee el campo `resumen` al usuario tal cual antes de entrar en detalles: ya está escrito para alguien sin formación tributaria. Si `listoParaEmitir` es false, resuelve `porCompletar` ANTES de preparar cualquier factura. El consolidado es de UNA empresa: si aparece el bloque `multiempresa`, aclara de cuál estás hablando y que las demás llevan cuentas aparte. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Construye UNA factura LISTA con toda la matemática tributaria hecha por el servidor: calcula líneas, agrupa el IVA por tarifa, cuadra totales con redondeo oficial y valida la identificación del comprador (dígito verificador) y el límite de consumidor final. NO emite nada. LLÁMALO SIEMPRE en lugar de calcular tú los montos; para 2 o más facturas usa preparar_lote. PROTOCOLO: 1) contexto_emision para los IDs, 2) preparar_factura, 3) MUESTRA el campo 'resumen' al usuario y espera su confirmación explícita de ESTA factura — una instrucción general previa no cuenta como confirmación, 4) emitir_factura con el 'payload' EXACTO devuelto (incluye idempotencyKey, que evita duplicados al reintentar, y la fechaEmision dentro de infoFactura si la pediste). Si el usuario indicó una fecha pasada, verifica que aparezca en el resumen antes de pedir la confirmación.

Construye VARIAS facturas de una vez (máximo 25) con toda la matemática hecha por el servidor: cada una se calcula y cuadra igual que en preparar_factura, y además devuelve un resumen AGREGADO (tabla por factura + totales del lote). NO emite nada. El comprador, la forma de pago y la fechaEmision pueden ser comunes al lote o indicarse por factura (el valor por factura REEMPLAZA al común, sin mezclar campos). PROTOCOLO DE CONFIRMACIÓN MASIVA: muestra al usuario el resumenAgregado COMPLETO y pide UNA confirmación explícita del lote entero ANTES de llamar a emitir_lote — nunca emitas ninguna factura del lote sin esa confirmación, aunque exista una instrucción general previa. Si el usuario quiere cambiar una factura, corrige y vuelve a preparar el lote completo. Cada payload trae su idempotencyKey: consérvalos intactos para emitir_lote y para cualquier reintento.

Construye una NOTA DE CRÉDITO (comprobante 04) que revierte una factura autorizada — la vía legal para 'anular' cuando ya no aplica la anulación (p. ej. fuera del plazo del día 7). NO emite nada; el servidor hace toda la matemática. Dos modos: (1) REVERSO TOTAL — pasa `comprobanteId` (la factura) y `motivo`, y se acredita el 100% (deriva comprador, referencia y el IVA del original); (2) EXPLÍCITO/PARCIAL — pasa `comprador`, `items` a acreditar, la referencia `documentoModificado` y `motivo`. PROTOCOLO: muestra el `resumen` al usuario y espera confirmación explícita; solo entonces llama a emitir_nota_credito con el 'payload' EXACTO (incluye idempotencyKey y confirmToken). REQUISITO: el SRI RECHAZA una NC a consumidor final (error 69) — exige un receptor identificado (RUC, cédula o pasaporte); una factura emitida a consumidor final NO se puede acreditar.

Reenvía por correo el comprobante (RIDE/XML) de una factura AUTORIZADA a su receptor, o a otro correo si indicas `para`. Útil cuando el cliente dice que no le llegó. Solo aplica a comprobantes ya autorizados por el SRI.

Registra un comprobante que TE FACTURARON, para que su IVA cuente en el crédito tributario (casillero 564) de tu declaración. Pasa la BASE imponible y el CÓDIGO de tarifa; NUNCA calcules el IVA tú: lo deriva el servidor con el mismo motor que usa al leer un XML. Si tienes el archivo XML del comprobante, es mejor subirlo por el dashboard (Compras): trae la clave de acceso y el desglose exactos. Consulta los códigos de tarifa vigentes con consultar_reglas_sri.

Agregados de ventas del período (default: mes en curso): conteo por estado, total facturado autorizado, desglose por tipo de comprobante y por mes. Úsalo cuando el usuario pida resúmenes o cifras de ventas. Para comparar ingresos contra los límites del RIMPE usa consultar_semaforo_rimpe (no lo calcules tú).

Responde '¿qué pasa si...?' sobre el borrador del F104 del período: 'si facturo $500 más este mes, ¿cuánto más pago?', '¿y si registro $200 más de compras?', '¿y si paso ventas a crédito?'. Devuelve las cifras base vs simuladas, la `diferencia` del total a pagar (902) y del crédito (615), y una `explicacion` en una frase. Montos en USD: las bases del escenario se gravan con la tarifa general VIGENTE del catálogo del servidor (nunca la asumas tú). Es una ESTIMACIÓN educativa: no aplica el factor 563 ni saldos de declaraciones anteriores (605). Muestra SIEMPRE los `supuestos` y el `disclaimer` al usuario. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.

Chequeo previo a la declaración: cruza el borrador del F104 contra los libros de ventas y compras del período y detecta inconsistencias ANTES de declarar: IVA del borrador que no cuadra con los libros (¿comprobantes emitidos fuera de Contadeo?), compras sin comprobante autorizado (crédito que no se sustenta), notas de crédito emitidas por compensar (443/453) y gastos posiblemente no registrados. Con `cifrasADeclarar` (casillero → valor: 429, 564, 601, 609, 902, 615) además compara lo que el usuario piensa declarar contra el borrador y explica cada diferencia. Muestra al usuario todos los chequeos en `alerta` o `revisar` y la `conclusion`. NUNCA calcules ni inventes fechas, límites u obligaciones: este tool devuelve los valores vigentes del servidor de Contadeo. Incluye SIEMPRE el campo `disclaimer` de la respuesta en tu mensaje al usuario.