API y MCP de Koolya

    Abrir mis empresas

    Conecta un asistente compatible con MCP a una empresa de Koolya. Puedes consultar los asuntos pendientes, trabajar con oportunidades y revisar propuestas de Fiskal según los permisos que elijas.

    Conectar mi asistente

    Añade Koolya a ChatGPT

    En Plugins, pulsa + y añade un servidor MCP personalizado. Llámalo Koolya, pega la dirección del servidor y elige OAuth. Crea el plugin y selecciónalo con @ en una conversación.

    Servidor MCP de Koolya

    https://koolya.com/api/mcp

    Si trabajas en un espacio administrado, puede que un administrador tenga que habilitar los conectores personalizados.

    Elige tu empresa y prueba una petición

    Cuando el asistente te lleve a Koolya, inicia sesión y elige la empresa y los permisos. También puedes crear tu primera empresa durante esa autorización.

    «¿Qué tengo pendiente hoy? Dame un enlace a cada asunto que requiera mi atención.»

    Empieza con cuatro datos o una factura

    1. Crea tu cuenta y confirma tu correo.
    2. Añade https://koolya.com/api/mcp como servidor remoto con Streamable HTTP y OAuth en tu chat.
    3. Autoriza tu empresa y «Consultar Fiskal», «Registrar datos fiscales» y «Configurar empresa». Si aún no tienes una empresa, puedes crearla al conectar. Necesitas Fiskal en tu plan o prueba.
    4. Indica nombre fiscal, NIF, autónomo o sociedad y domicilio fiscal. También puedes adjuntar una factura: identifica tu empresa y la contraparte.
    5. Abre la propuesta de Koolya, revisa los datos y pulsa «Confirmar y guardar en Fiskal».

    «Configura mi empresa en Koolya usando esta factura. Mi empresa es […]. Pregúntame por lo que falte y dame el enlace para revisar la propuesta. Después importaré las facturas y libros de mi programa anterior».

    La lectura del adjunto depende del chat. Koolya valida y guarda los registros. Los regímenes, deducciones y obligaciones censales requieren tu confirmación; este flujo no activa VeriFactu ni presenta declaraciones.

    Conectar otros clientes MCP

    En otros clientes, utiliza MCP remoto con OAuth y registro dinámico. Si admiten Bearer, crea una clave de tipo MCP en Integraciones. La autorización OAuth dura 30 días; el token de acceso dura una hora y se renueva con rotación.

    Vuelve a conectar las conexiones existentes si quieres los nuevos permisos. Mantienen sus permisos originales. La escritura está desmarcada por defecto; «Configurar empresa» requiere ser propietario.

    Facturas, originales y migraciones

    El chat prepara contraparte, número, fechas, líneas, impuestos y total del original. El servidor contrasta el total y permite conservar cuotas y redondeos originales explícitos. Un total manual necesita original, motivo y resolución confirmada; las diferencias pendientes pasan a revisión. La deducción de IVA es 0 y la deducción en renta está desactivada hasta que se indiquen expresamente.

    Exporta facturas, contactos, libros y cobros o pagos en CSV, Excel o JSON. Dale los archivos al chat para convertirlos al formato de Koolya, en lotes según el límite elegido para la conexión: 50 registros por defecto y hasta 500. Se admiten facturas recibidas, ventas históricas F1/F2, contactos, asientos manuales cuadrados, apuntes bancarios y cobros o pagos.

    Importa primero los documentos; usa sus IDs de Koolya para vincular después los cobros y pagos. Las ventas se conservan como históricas sin reemitirlas. Una referencia repetida con datos distintos se rechaza. Las facturas generan sus asientos: importa como manuales solo aperturas y ajustes que no estén representados por esos documentos.

    Una copia completa en formato Fiskal compatible utiliza prepare_fiscal_migration: valida referencias y restaura en una contabilidad vacía con el mismo NIF. La exportación de otro programa necesita conversión. La importación incremental conserva líneas con signo y rectificativas R1–R5 con su modo, motivo y referencias originales.

    store_fiscal_attachment guarda PDF, PNG, JPEG o WebP de hasta 270 KB si el cliente puede proporcionar los bytes. Guarda primero el original y añade su ID a la propuesta. Para archivos de hasta 4 MiB, utiliza fragmentos de hasta 270 KB con uploadId, index, count y SHA-256 del archivo completo. Reenvía los mismos bytes para reanudar; las cuotas de archivos y volumen son configurables por conexión. Para tamaños mayores o clientes sin acceso a bytes, sube los originales desde Fiskal. No se descargan URLs externas. Los originales de una copia completa deben subirse previamente con sus IDs.

    Para continuar una empresa con datos, utiliza fiscal_migration_job: create, stage, prepare hasta ready, items y status. Los elementos se identifican por IDs estables y las referencias sourceSystem, sourceCompany, sourceType y sourceId; documentSource vincula los pagos y originales sin esperar a guardar cada documento. Revisa el contenido completo, cantidades, totales, exclusiones e incidencias y aprueba una vez en Koolya. Continúa con el mismo apply_fiscal_preview hasta complete; cada sublote es atómico y reanudable. La propuesta del trabajo caduca a las 24 horas si no se ha aprobado. cancel cierra el trabajo conservando lo ya aplicado.

    Las F2 históricas pueden carecer de NIF del destinatario. Los registros incompletos conservan su UUID y original en reviewRecords, fuera de los cálculos fiscales. resolvesReview resuelve una incidencia explícita; matchExistingId vincula un duplicado verificado, sin crear otro documento. Se conservan suplidos, retenciones professional/rent/other, fechas de registro y operación, cuotas y clasificación original. El tipo rent distingue la retención de alquiler; no genera una declaración del modelo 115.

    Las propuestas de un lote caducan en una hora. Si cambia la contabilidad, prepara una nueva. Reintentar una propuesta aplicada no duplica los registros.

    Cuentas y medios de pago

    Da de alta cuentas de banco, efectivo, suplidos u otros, con cuenta contable, saldo inicial en céntimos y fecha de apertura. Crea medios asociados o independientes: varias tarjetas pueden compartir una cuenta. Los tipos de medio son efectivo, transferencia, tarjeta, domiciliación, cheque, pagaré, confirming, compensación u otro.

    prepare_fiscal_treasury y POST /fiscal/treasury/preview proponen altas o actualizaciones hasta el límite de registros de la conexión, con revisión y confirmación del usuario en Koolya. Requieren edición de banco. Elige IDs estables; create exige uno nuevo y update uno existente. La actualización sustituye la ficha completa; active:false archiva y omitir accountId desvincula el medio.

    Ejemplo: una cuenta, cinco tarjetas y un medio independiente
    {
      "sourceName": "Mi tesorería",
      "changes": [
        {
          "entity": "account",
          "action": "create",
          "id": "banco-principal",
          "name": "Banco principal",
          "type": "banco",
          "ledgerAccount": "572.01",
          "openingBalanceCents": 50000,
          "openingDate": "2026-01-01",
          "active": true
        },
        {
          "entity": "paymentMethod",
          "action": "create",
          "id": "tarjeta-1",
          "name": "Tarjeta 1",
          "type": "tarjeta",
          "accountId": "banco-principal",
          "active": true
        },
        {
          "entity": "paymentMethod",
          "action": "create",
          "id": "tarjeta-2",
          "name": "Tarjeta 2",
          "type": "tarjeta",
          "accountId": "banco-principal",
          "active": true
        },
        {
          "entity": "paymentMethod",
          "action": "create",
          "id": "tarjeta-3",
          "name": "Tarjeta 3",
          "type": "tarjeta",
          "accountId": "banco-principal",
          "active": true
        },
        {
          "entity": "paymentMethod",
          "action": "create",
          "id": "tarjeta-4",
          "name": "Tarjeta 4",
          "type": "tarjeta",
          "accountId": "banco-principal",
          "active": true
        },
        {
          "entity": "paymentMethod",
          "action": "create",
          "id": "tarjeta-5",
          "name": "Tarjeta 5",
          "type": "tarjeta",
          "accountId": "banco-principal",
          "active": true
        },
        {
          "entity": "paymentMethod",
          "action": "create",
          "id": "compensacion",
          "name": "Compensación",
          "type": "compensacion",
          "active": true
        }
      ]
    }

    Registra primero las cuentas, medios y documentos. En un registro kind:payment, añade accountId, paymentMethodId y, opcionalmente, commissionCents. El medio aporta su tipo y cuenta asociada; una cuenta explícita diferente se rechaza. Los pagos parciales no pueden superar el pendiente. Cuenta y medio deben estar activos y la fecha debe ser posterior o igual a la apertura.

    {
      "sourceName": "Pagos",
      "records": [
        {
          "kind": "payment",
          "externalId": "pago-1",
          "documentType": "expense",
          "documentId": "ID_DEL_GASTO",
          "date": "2026-10-05",
          "amountCents": 6000,
          "paymentMethodId": "tarjeta-1",
          "commissionCents": 100
        }
      ]
    }

    get_fiscal_treasury y GET /fiscal/treasury devuelven accounts con balanceCents, paymentMethods y unassigned para movimientos sin cuenta. asOf es un corte inclusivo, hoy UTC por defecto. Saldo = apertura + cobros − pagos − comisiones; los extractos no suman hasta registrar el movimiento. Se requiere lectura de banco o contabilidad. Las listas treasuryAccounts y paymentMethods conservan los nombres de campo nativos españoles.

    Para movimientos existentes, prepara kind:paymentAssignment con movementId, accountId y paymentMethodId: conserva ID, documento, fecha, importe y comisión. Omitir el medio lo conserva; null lo limpia explícitamente. kind:documentAttachments añade originales a una factura o gasto guardado, conservando los anteriores. Repetir estas asignaciones no duplica movimientos ni archivos.

    kind:treasuryMovement conserva partidas pendientes de vincular con source, cuenta, contrapartida contable y motivo expresos. No inventa una venta o gasto. No reimportes cobros ya incluidos en la apertura. prepare_company_configuration admite ROI con fechas y justificantes y incomeTaxRegime:null limpia un régimen de IRPF heredado de una sociedad.

    Archivar conserva los saldos y movimientos. Reasignar una tarjeta conserva su histórico. La apertura y cuenta contable quedan protegidas si hay movimientos. Las copias incluyen cuentas, medios y referencias; los movimientos antiguos sin cuenta siguen separados. El saldo inicial de tesorería no genera un asiento contable de apertura.

    API documentada

    En tu empresa, abre Integraciones y crea una clave de tipo API con los permisos y caducidad que necesites. Guárdala en el servidor; envíala como Authorization: Bearer TU_CLAVE. Las claves API y MCP son distintas.

    curl 'https://koolya.com/api/v1/fiscal/context' -H 'Authorization: Bearer TU_CLAVE'
    Descargar OpenAPI 3.1 con esquemas de configuración, importación y tesorería

    Rutas bajo /api/v1; respuestas correctas: {"data": …}.

    GET/company/operationsMódulos de lectura autorizados
    GET/company/analyticsanalytics:read
    GET/company/plancompany:read
    GET/company/teamcompany:read y propietario
    POST/sitesanalytics:write
    GET/sites/{siteId}/installationanalytics:read
    GET/crm/contacts/{contactId}/workspacecrm:read y permisos de cada área
    POST/crm/tasks/followupscrm:write
    POST/crm/tasks/completecrm:write
    POST/crm/activitiescrm:write
    POST/crm/opportunities/stagecrm:stage y edición de oportunidades
    POST/company/team/invitations/previewteam:invite y propietario
    GET/company/team/invitations/{proposalId}team:invite y propietario
    POST/fiscal/inbox/{entryId}/expense-proposalLectura y escritura de Fiskal con edición de Buzón y Compras
    POST/crm/opportunities/quoteLectura y escritura de CRM y Fiskal
    GET/fiscal/treasury/cash-flowfiscal:read y banco o contabilidad
    GET/fiscal/inboxfiscal:read y buzón
    GET/fiscal/inbox/{entryId}fiscal:read y buzón
    GET/companiesEmpresa autorizada
    GET/sitesanalytics:read
    GET/sites/{siteId}/analytics?from=…&to=…analytics:read
    GET/sites/{siteId}/liveanalytics:read
    GET/crm/overviewcrm:read
    GET/crm/contactscrm:read
    GET/crm/opportunitiescrm:read
    GET/crm/taskscrm:read
    GET/fiscal/contextfiscal:read
    GET/fiscal/records?entity=expensesfiscal:read
    GET/fiscal/treasury?asOf=2026-10-13fiscal:read + banco o contabilidad
    POST/fiscal/treasury/previewfiscal:write + edición de banco
    POST/fiscal/imports/previewfiscal:write
    POST/fiscal/company/previewfiscal:write + company:write
    POST/fiscal/migrations/previewfiscal:write + company:write
    POST/fiscal/migration-jobsfiscal:write + company:write + edición completa
    POST/fiscal/previews/applyfiscal:write
    POST/fiscal/attachmentsfiscal:write
    Ejemplo: preparar una factura recibida
    {
      "sourceName": "Mi programa anterior",
      "records": [
        {
          "kind": "expense",
          "number": "PROV-2026-001",
          "date": "2026-10-01",
          "party": {
            "name": "Proveedor",
            "taxId": "B12345674"
          },
          "lines": [
            {
              "description": "Servicio",
              "baseCents": 10000,
              "vatBasisPoints": 2100
            }
          ],
          "expectedTotalCents": 12100
        }
      ]
    }

    Envía este JSON a POST /fiscal/imports/preview. Devuelve previewId, summary y reviewUrl. El usuario confirma y guarda en el enlace con su sesión de Koolya. API y MCP no pueden aprobar por él. Después puedes recuperar el resultado con POST /fiscal/previews/apply y {"previewId":"…"}.

    Importes en céntimos enteros; tipos fiscales en puntos: 2100 = 21 %. JSON hasta 512 KiB. Fiskal admite entity contacts, invoices, expenses, journal, bank, payments, treasuryAccounts, paymentMethods, reviewRecords y sourceReferences, con offset, limit hasta el máximo autorizado en la conexión y respuesta total, nextOffset.

    Analytics utiliza fechas ISO 8601 UTC e intervalos hasta 366 días. Los visitantes son sesiones efímeras. CRM admite search, offset y filter con hasta 100 fichas; filtros: contactos lead/client/archived, oportunidades new/qualified/proposal/won/lost, tareas pending/done/overdue.

    Herramientas MCP

    Empresa, Analytics y CRM permiten consultar los pendientes de hoy, comparar sitios y abrir la ficha de un cliente. Con escritura de CRM puedes crear seguimientos, completar tareas y registrar actividades. Consulta las herramientas autorizadas en tu asistente.

    Fiskal: get_fiscal_context, list_fiscal_records, get_fiscal_treasury, prepare_fiscal_treasury, prepare_fiscal_import, store_fiscal_attachment y apply_fiscal_preview. Con company:write: prepare_company_configuration, prepare_fiscal_migration y fiscal_migration_job.

    Solo se ofrecen herramientas permitidas por tu conexión. Cada llamada revalida usuario, empresa, áreas y plan. Los documentos se tratan como datos; sus instrucciones no conceden permisos.

    Sesiones, permisos y errores

    Puedes confiar en tu dispositivo durante 30 días al iniciar sesión, o 7 si administras Koolya. El plazo es fijo; los cambios sensibles siguen exigiendo un código reciente. Desde Seguridad puedes cerrar las otras sesiones. Cambiar credenciales revoca accesos anteriores.

    Revoca claves y autorizaciones desde Integraciones. Retirar un miembro o sus permisos bloquea sus operaciones. Cada conexión pertenece a una empresa. El servicio de chat recibe los datos consultados o adjuntados.

    En Integraciones puedes configurar registros por operación (1–500), operaciones por minuto (1–600), operaciones diarias opcionales (hasta 100.000), archivos diarios (hasta 10.000) y volumen diario (hasta 1 GiB). Por defecto: 50 registros, 60 operaciones/minuto, sin tope diario de operaciones, 100 archivos y 20 MiB/día. Los contadores son por conexión y compartidos entre ubicaciones; las llamadas admitidas cuentan aunque fallen y el día se reinicia a las 00:00 UTC. Un 429 exige esperar al siguiente periodo o ajustar el límite. Nunca publiques claves ni las incluyas en URLs.

    400: datos inválidos; 401: conexión caducada o revocada; 402: módulo fuera del plan; 403: permiso insuficiente; 404: recurso no disponible en esta empresa; 405: método incorrecto; 409: duplicado incompatible o contabilidad modificada; 410: propuesta caducada; 413: archivo o lote demasiado grande; 428: revisión humana o autenticación reciente requerida; 429: límite de consultas. El cuerpo contiene error y, cuando corresponde, code.