Servidor MCP y API de Keyio

Viviendas

Campos que puedes enviar

• mainPurpose: long_term, short_term o sale (comprada para vender). sale es el seguimiento de compra-venta: etapa, precio objetivo, presupuesto por partidas, financiación, escrituras, plusvalía municipal y precio y fecha de venta.
• taxRegime: es-individual, es-company o es-nonresident (con nonResidentEU si el propietario reside en la UE/EEE). paymentTrackingEnabled activa el seguimiento de cobros de los alquileres de la vivienda; hace falta para registrar cobros.
• Nunca se devuelven las credenciales de SES, Mossos o Ertzaintza, los enlaces de calendario ni la configuración de compartir. El IBAN y los DNI de propietarios y representante solo los ven el propietario y los editores.
• El envío automático a SES (sesAutoSend) y el compartir solo se cambian en la app. Crear respeta el límite de viviendas del plan (403).
• Borrar se rechaza con 409 mientras haya alquileres o gastos; borra también sus documentos y el historial de checklists. No se puede deshacer.

Alquileres

Filtros del listado

• propertyId — Solo los de esa vivienda (404 si no es tuya).
• type — long o short.
• from, to — Estancias que se solapan con ese rango.

Campos que puedes enviar

• renters acepta id, fullName, idNumber, address, phone y email, pero solo devuelve id y fullName. En un PATCH, un inquilino con id conocido conserva lo que no envías; una cadena vacía borra el campo; uno que falta en la lista se quita. renterAddress no se devuelve (es un domicilio).
• Crear en una vivienda vendida da 409. propertyId no se puede cambiar.
• Borrar elimina también pagos, notas, documentos y enlaces de firma, revoca el código de la cerradura y, si era una reserva vasca ya comunicada, deja el aviso de anularla en la Ertzaintza.

Gastos

Necesita un plan con gastos.

Filtros del listado

• propertyId — Solo los de esa vivienda.
• year — Ejercicio, cuatro cifras.

Campos que puedes enviar

• type es texto libre, pero usa una categoría de la app para que cuente en el informe fiscal: Seguro, Comunidad, Impuestos, Suministros, Conservación, Reparaciones, Mobiliario, Electrodomésticos, Intereses de Hipoteca, Formalización Contrato, Defensa Jurídica, Servicios Personales, Otros. IBI se guarda como Impuestos.
• Un activo fijo (mueble, electrodoméstico) es un gasto Mobiliario o Electrodomésticos con amortizationType "investment". Las antiguas rutas /assets responden 410.
• Desglose (sociedades): amount debería ser taxBase + vatAmount + untaxedAmount; la retención es informativa. La API guarda lo que envías sin comprobar las sumas. payment (lo pagado según la conciliación bancaria) es de solo lectura.
• recurrence (solo al crear): { frequency: monthly | quarterly | yearly, nextDueDate, endDate }. Crea los periodos ya vencidos hasta hoy (120 como mucho) y un gasto recurrente que se copia cada día que toca; la respuesta añade recurring: { recurringExpenseId, backfilled, nextDueDate }. El gasto no guarda la recurrencia y un PATCH no la acepta (400): cámbiala o detenla en /recurring-expenses.
• file (al crear) o PUT /expenses/{id}/file adjuntan la factura: PDF, JPEG, PNG, WebP o GIF; sustituir borra la anterior. DELETE del archivo deja el gasto.
• /recurring-expenses: solo los tuyos (filtro propertyId). PATCH acepta type, description, issuerName, issuerId, frequency, nextDueDate, lastAmount, endDate (null la quita), active y operationCategory. DELETE deja de repetirlo; los gastos ya creados se quedan.

Buzón de facturas

Necesita un plan con gastos. Es del titular de la cuenta: las facturas que subes sin vivienda o reenvías por email esperan aquí hasta archivarlas como gasto.

Campos que puedes enviar

• GET /inbox devuelve las facturas de la más antigua a la más nueva y el buzón: { available, address, accountEmail, allowedSenders }. PUT /inbox/mailbox lo activa (siempre la misma dirección) y acepta allowedSenders; 409 si el buzón no está disponible.
• POST /inbox/{id}/file lleva uno de los dos: expenseId (adjunta la factura a ese gasto, 200) o expense (los mismos campos que POST /expenses, lo crea, 201). La factura sale del buzón. 409 si no tiene archivo.
• La API no lee la factura con la IA de Keyio: la lee quien llama (tu programa o tu asistente) y decide la vivienda y los importes.

Documentos

De una vivienda (/properties/{id}/documents) o de un alquiler (/rentals/{id}/documents), con las mismas rutas.

Campos que puedes enviar

• documentType: contract, addendum, inventory, checkin_report, checkout_report, receipt, invoice, deposit, id_copy, insurance, deed, energy_certificate, habitability_certificate, tourist_license, house_rules, appliance_instructions, wifi_info u other. file: PDF, imágenes, Word, Excel u OpenDocument. Los de un alquiler se crean publicados.
• Se devuelven con status (draft, published, archived, pending_signature, signed), hasFile y signing (cuántos firmantes y cuántos han firmado), nunca enlaces ni datos de los firmantes. El GET de uno añade file: en un contrato firmado, el PDF firmado.
• PATCH: name, description, documentType, validityDate (null la quita) y publishedToPortal. Borrar se rechaza con 409 mientras esté pendiente de firma, y borra también sus archivos.

Cobros de renta

Necesita un plan con cobros y el seguimiento de cobros activado en la vivienda (paymentTrackingEnabled).

Filtros del listado

• year — Solo los cargos de ese año.

Campos que puedes enviar

• Cargos: en larga estancia, uno por mes hasta el mes que viene; en corta, la señal y el resto o los hitos de su paymentPlan. Cada uno trae chargeType (monthly_rent, advance, balance, installment), expectedAmount, receivedAmount, status (paid, partial, pending, due, late) y sus entries.
• Para registrar un cobro, di qué cargo es con year + month, chargeType o planEntryId. Se suma a lo ya recibido: paid al llegar a lo esperado, partial antes. Si no queda claro qué cargo es, el 400 los lista. method: transfer (por defecto), cash, card, domiciliacion u other. 409 si el seguimiento de cobros está desactivado.
• Un cobro concreto se corrige o se quita en …/entries/{entryId}; quitar el último borra el registro. Borrar el cargo entero solo lo puede hacer quien lo registró (403).

Notas del alquiler

El registro de comunicaciones del alquiler. Las notas no se editan.

Campos que puedes enviar

• content hasta 2.000 caracteres. type: note, call, email, whatsapp, letter, meeting u other; contactDirection: inbound u outbound. createdBy es el nombre de tu cuenta. Se listan de la más nueva a la más antigua; solo su autor la puede borrar.

Mantenimiento

Necesita un plan con mantenimiento.

Filtros del listado

• propertyId — Solo las de esa vivienda.
• status — open, acknowledged, in_progress, completed o cancelled.

Campos que puedes enviar

• category: plumbing, electrical, hvac, appliance, structural, cleaning u other (por defecto); urgency: low, medium (por defecto), high o emergency; status empieza en open. notes hasta 2.000 caracteres. linkedExpenseId (solo PATCH) enlaza un gasto de la misma vivienda; null lo desenlaza. Al completarla se anota resolvedAt.
• Hasta 5 fotos por incidencia (una imagen por POST; 409 al pasar de 5); n empieza en 1. Se devuelve photoCount, nunca enlaces a las fotos. Solo quien la creó la puede borrar (si no, cancélala); borrarla borra sus fotos.

Informes fiscales

Necesita un plan con informes. Son estimaciones y llevan siempre el aviso de revisarlas con tu asesor fiscal.

Filtros del listado

• year — Obligatorio en los dos.
• isRatePct — 15 o 25: tipo del Impuesto sobre Sociedades (informe de una vivienda de sociedad).

• El informe de una vivienda trae regime (IRPF, IS o IRNR), owners con su ownershipPercentage, ocupación, ingresos, gastos por casilla, el detalle irpf (rendimiento neto, reducción por alquiler de vivienda, imputación de rentas), is o irnr, y result { deductions, netResult, estimatedTax }. Las cifras son del 100 % de la vivienda.
• El resumen da, por vivienda con actividad ese año, ingresos, gastos deducibles, resultado neto e impuesto estimado, y los totales.

Plantillas de contrato

Necesita un plan con contratos. Son solo tuyas.

Campos que puedes enviar

• content es un documento TipTap: { "type": "doc", "content": [ … ] }, el mismo formato que el editor de la app. category: rental-contract, short-term-rental, rent-review, inventory, termination, addendum u other.