*MCP › Referencia › Finanzas › Facturas* # Crear o actualizar el espejo de una factura emitida externamente > Guarda en Filmo una copia de solo lectura de una factura emitida por OTRO sistema (un ERP como Business Central), para que el equipo de operaciones pueda verla. Filmo no la emite: no se numera con una serie de Filmo, no se firma y nunca se envía a Verifactu. Se guarda validada, bloqueada y marcada como emitida externamente, y en Filmo no se puede editar, anular, cobrar, rectificar, facturar electrónicamente ni enviar por correo: todo cambio llega a través de esta misma llamada. La clave es el par de la ruta: repetirla actualiza el mismo espejo, y repetir el mismo contenido no cambia nada. Responde 201 cuando crea el espejo y 200 cuando lo actualiza o ya era idéntico. El cliente se resuelve por `contactId`, después por identificador fiscal y por último por nombre exacto (los contactos nunca se crean implícitamente); uno que no se puede resolver es un 400 `validation_error` cuyo `errors[0].path` indica el motivo: `contactId` (no existe ese contacto), `contactTaxId` (varios contactos comparten ese identificador fiscal, o ninguno lo tiene y no se envió `contactName`) o `contactName` (varios contactos, o ninguno, tienen ese nombre). Los totales declarados se comprueban con las líneas con una tolerancia de un céntimo por línea: si no coinciden es un 400 `validation_error` con `errors[0].path` `subTotal`, `taxTotal` o `total` (también `total` cuando la base más los impuestos no suman esa cifra); un tipo de impuesto que no se reconoce en una línea es `lines[n].taxRate`. 409 si el número de factura ya lo usa otra factura de la cuenta, si la clave pertenece a una factura que no es un espejo sincronizado, o si se reenvía como emitido un espejo anulado. Devuelve la factura completa, la misma proyección que su GET. HERRAMIENTA `filmo_invoices_upsert_external` · `invoices:write` · 120/min · Puede requerir un add-on · Anotación del servidor: Idempotente ## Argumentos | Nombre | Tipo | Obligatorio | Descripción | | --- | --- | --- | --- | | `originSystem` | string | Sí | Identificador del sistema de origen, un slug en minúsculas (p. ej. booqable, rentman, business_central). | | `originExternalId` | string | Sí | Identificador del documento en el sistema de origen. | | `invoiceNumber` | string | Sí | Número de factura exactamente como lo emitió el sistema de origen. | | `invoiceDate` | string | Sí | Fecha de emisión. | | `dueDate` | string | No | Fecha de vencimiento. | | `currency` | string | No | Moneda en ISO 4217. = `"EUR"` | | `contactId` | string | No | Identificador del contacto en Filmo. | | `contactTaxId` | string | No | Identificador fiscal del cliente, cuando se desconoce su identificador en Filmo. | | `contactName` | string | No | Nombre exacto del cliente, como último recurso. | | `lines` | object[] | Sí | Líneas de la factura. | | `lines.description` | string | Sí | Descripción de la línea. | | `lines.quantity` | string | Sí | Cantidad. | | `lines.unitPrice` | string | Sí | Precio unitario antes de impuestos. | | `lines.discountPercent` | string | No | Descuento de la línea como porcentaje (0-100). | | `lines.taxType` | string | No | Tipo de impuesto de Filmo (p. ej. IVA_21). Si falta, se infiere de taxRate. | | `lines.taxRate` | string | No | Porcentaje de impuesto de la línea (p. ej. "21"). Obligatorio cuando falta taxType. | | `subTotal` | string | No | Base imponible según el sistema de origen (comprobada contra las líneas). | | `taxTotal` | string | No | Total de impuestos según el sistema de origen. | | `total` | string | No | Total según el sistema de origen. | | `externalStatus` | string | No | issued o voided en el sistema de origen. `issued`, `voided` = `"issued"` | | `voidReason` | string | No | Motivo por el que el sistema de origen la anuló. | | `paymentStatus` | string | No | Estado del pago según el sistema de origen. `unpaid`, `partially_paid`, `paid`, `overpaid` | | `totalPaid` | string | No | Importe cobrado según el sistema de origen. | | `originUrl` | string | No | Enlace al documento en el sistema de origen (https). | | `originFileUrl` | string | No | PDF original emitido por el sistema de origen (https). | | `notes` | string | No | Notas internas. | | `idempotencyKey` | string | No | Clave de idempotencia elegida por el cliente (se recomienda un UUID). Repetir la misma clave con los mismos argumentos en 24 h devuelve la respuesta almacenada sin volver a ejecutar; con argumentos distintos responde 422. Es la forma segura de reintentar tras un fallo de red. | ## Resultado En un éxito el resultado lleva `structuredContent` con `data` y `meta`. Estos son los atributos de `data`. | Nombre | Tipo | Descripción | | --- | --- | --- | | `id` | string | Identificador único de la factura. | | `invoiceNumber` | string | Número de factura; null mientras es un borrador (el número se asigna al validarla). | | `status` | string | Estado del ciclo de vida del documento: draft, validated (validado y numerado) o voided. `draft`, `validated`, `voided` | | `isRectification` | boolean | Si la factura rectifica una anterior. Las facturas creadas en Filmo nunca son rectificativas, y las notas de crédito se sirven en `/api/v1/credit-notes`; pero `/api/v1/invoices` aún puede devolver documentos rectificativos importados (por ejemplo, de una importación de Rentman) con este campo en true, así que deduplícalos con las notas de crédito por número. | | `invoiceDate` | string | Fecha de emisión en ISO 8601 con desfase; null mientras es un borrador. | | `dueDate` | string | Fecha de vencimiento en ISO 8601 con desplazamiento; null si no está definida. | | `currency` | string | Moneda de la factura como código ISO 4217 (por ejemplo "EUR"). | | `contact` | object | Referencia compacta al contacto facturado; null si no hay. | | `contact.id` | string | Identificador único del contacto. | | `contact.name` | string | Nombre del contacto. | | `orderId` | string | Identificador del pedido de origen; null si la factura no procede de un pedido. | | `orderNumber` | string | Número del pedido de origen; null si la factura no procede de un pedido. | | `projectId` | string | Identificador del proyecto vinculado; null si no está vinculado. | | `subTotal` | string | Subtotal antes de descuentos e impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP). | | `discountTotal` | string | Total de descuentos como cadena decimal "1234.50" (ROUND_HALF_UP). | | `taxesPrice` | string | Total de impuestos como cadena decimal "1234.50" (ROUND_HALF_UP). | | `netPrice` | string | Base imponible (neto antes de impuestos) como cadena decimal "1234.50" (ROUND_HALF_UP). | | `grossPrice` | string | Total con impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP). | | `totalPaid` | string | Importe cobrado hasta la fecha como cadena decimal "1234.50" (ROUND_HALF_UP); null si no consta. | | `paymentStatus` | string | Estado del pago: unpaid (nada cobrado todavía, también para facturas sin cobro registrado), partially_paid, paid, overpaid (cobrado por encima del total), overdue (vencido y sin pagar) o voided (el documento está anulado, sea cual sea lo cobrado antes). El filtro `paymentStatus` usa los mismos valores. `unpaid`, `partially_paid`, `paid`, `overpaid`, `overdue`, `voided` | | `paymentMethod` | string | Método de pago de la factura; null si no se ha registrado. | | `tags` | object[] | Etiquetas adjuntas a la factura, con su identificador y nombre. | | `tags.id` | string | Identificador único de la etiqueta. | | `tags.name` | string | Nombre de la etiqueta. | | `createdAt` | string | Fecha de creación en ISO 8601 con desplazamiento. | | `updatedAt` | string | Fecha de la última actualización en ISO 8601 con desplazamiento. | | `projectName` | string | Nombre del proyecto vinculado; null si no está vinculado. | | `taxBreakdown` | object[] | Desglose de impuestos por tipo; null si no se ha calculado. | | `taxBreakdown.taxType` | string | Clave del tipo de impuesto (por ejemplo "IVA_21"). | | `taxBreakdown.label` | string | Etiqueta de impuesto legible. | | `taxBreakdown.rate` | number | Tipo impositivo aplicado, como porcentaje (por ejemplo 21 para el 21%). | | `taxBreakdown.baseAmount` | string | Base imponible sobre la que se aplica el impuesto, como cadena decimal "1234.50" (ROUND_HALF_UP). | | `taxBreakdown.amount` | string | Importe del impuesto como cadena decimal "1234.50" (ROUND_HALF_UP). | | `productDiscountTotal` | string | Total de descuentos aplicados a nivel de producto, como cadena decimal "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. | | `globalDiscountTotal` | string | Total de descuento global del documento, como cadena decimal "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. | | `insuranceTotal` | string | Total del seguro como cadena decimal "1234.50" (ROUND_HALF_UP). | | `depositTotal` | string | Total de fianzas como cadena decimal "1234.50" (ROUND_HALF_UP). | | `exchangeRate` | number | Tipo de cambio aplicado cuando la moneda difiere de la moneda base; null si no aplica. | | `billingAddress` | object | Dirección de facturación; null si no consta. | | `billingAddress.label` | string | Etiqueta descriptiva de la dirección; null si no consta. | | `billingAddress.addressLine1` | string | Primera línea de la dirección; null si no consta. | | `billingAddress.addressLine2` | string | Segunda línea de la dirección; null si no consta. | | `billingAddress.city` | string | Ciudad; null si no consta. | | `billingAddress.province` | string | Provincia o región; null si no se ha registrado. | | `billingAddress.postcode` | string | Código postal; null si no se ha registrado. | | `billingAddress.country` | string | País; null si no consta. | | `sourceQuoteIds` | string[] | Identificadores de los presupuestos de origen; null si la factura no procede de presupuestos. | | `sourceProformaIds` | string[] | Identificadores de las proformas de origen; null si la factura no procede de proformas. | *Llamada · filmo_invoices_upsert_external* ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "filmo_invoices_upsert_external", "arguments": { "originSystem": "", "originExternalId": "orig_8f2a1c", "invoiceNumber": "", "invoiceDate": "2026-09-01", "lines": [ { "description": "", "quantity": "", "unitPrice": "1234.50", "discountPercent": "", "taxType": "1234.50", "taxRate": "1234.50" } ] } } } ``` *Resultado (generado desde el esquema)* ```json { "structuredContent": { "data": { "id": "id_8f2a1c", "invoiceNumber": "", "status": "draft", "isRectification": true, "invoiceDate": "2026-09-01T08:00:00Z", "dueDate": "2026-09-01T08:00:00Z", "currency": "EUR", "contact": { "id": "id_8f2a1c", "name": "Example" }, "orderId": "orde_8f2a1c", "orderNumber": "", "projectId": "proj_8f2a1c", "subTotal": "1234.50", "discountTotal": "1234.50", "taxesPrice": "1234.50", "netPrice": "1234.50", "grossPrice": "1234.50", "totalPaid": "1234.50", "paymentStatus": "unpaid", "paymentMethod": "", "tags": [ { "id": "id_8f2a1c", "name": "Example" } ], "createdAt": "2026-09-01T08:00:00Z", "updatedAt": "2026-09-01T08:00:00Z", "projectName": "Example", "taxBreakdown": [ { "taxType": "1234.50", "label": "Example", "rate": 1, "baseAmount": "1234.50", "amount": "1234.50" } ], "productDiscountTotal": "1234.50", "globalDiscountTotal": "1234.50", "insuranceTotal": "1234.50", "depositTotal": "1234.50", "exchangeRate": 1, "billingAddress": { "label": "Example", "addressLine1": "", "addressLine2": "", "city": "", "province": "", "postcode": "", "country": "ES" }, "sourceQuoteIds": [ "sour_8f2a1c" ], "sourceProformaIds": [ "sour_8f2a1c" ] }, "meta": { "idempotencyKey": "", "rateLimit": { "limit": 120, "remaining": 119, "reset": 42 } } } } ``` ## La misma operación por REST Esta herramienta ejecuta [`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice). --- URL canónica: https://docs.filmo.io/es/mcp/tools/invoices/filmo-invoices-upsert-external Última actualización: 2026-10-25