*API REST › Referencia de endpoints › 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.

`PUT /api/v1/invoices/external/{originSystem}/{originExternalId}` — permiso `invoices:write`

Permiso: `invoices:write` · 120/min · Ámbito estricto · Complemento (402) · Idempotency-Key · MCP: `filmo_invoices_upsert_external`

## Autorizaciones

Clave de API como Bearer, con el permiso de abajo. `invoices:write`

## Cabeceras

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `Idempotency-Key` | string | No | Identificador único de la petición, elegido por el cliente (sirve un UUID). Entre 1 y 255 caracteres: una cabecera vacía se rechaza con 400 `validation_error`, porque el cliente se creería protegido. Repetir la misma clave con el MISMO cuerpo en 24 h devuelve la respuesta guardada sin volver a ejecutar, con la cabecera `Idempotent-Replay: true`. Con un cuerpo DISTINTO devuelve 422. Es la forma segura de reintentar tras un tiempo de espera de red. |

## Parámetros de ruta

| 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. |

## Cuerpo

Esquema del cuerpo: `InvoiceExternalUpsertBody`

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `invoiceNumber` | string | Sí | Número de factura exactamente como lo emitió el sistema de origen. |
| `invoiceDate` | string<date> | Sí | Fecha de emisión. |
| `dueDate` | string<date> | 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<uri> | No | Enlace al documento en el sistema de origen (https). |
| `originFileUrl` | string<uri> | No | PDF original emitido por el sistema de origen (https). |
| `notes` | string | No | Notas internas. |

## Ejemplos de petición

*Crear o actualizar el espejo de una factura emitida externamente*

**cURL**

```bash
curl https://app.filmo.io/api/v1/invoices/external/orig_8f2a1c/orig_8f2a1c \
  --request PUT \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header "Idempotency-Key: $(uuidgen 2>/dev/null || cat /proc/sys/kernel/random/uuid)" \
  --header 'Content-Type: application/json' \
  --data '{
  "invoiceNumber": "FV26-001042",
  "invoiceDate": "2026-09-15",
  "dueDate": "2026-10-15",
  "currency": "EUR",
  "contactTaxId": "B00000000",
  "lines": [
    {
      "description": "Alquiler de equipo de cámara (3 jornadas)",
      "quantity": "3",
      "unitPrice": "450.00",
      "taxRate": "21"
    },
    {
      "description": "Transporte ida y vuelta",
      "quantity": "1",
      "unitPrice": "120.00",
      "taxType": "IVA_21"
    }
  ],
  "total": "1778.70",
  "externalStatus": "issued",
  "paymentStatus": "unpaid",
  "originUrl": "https://businesscentral.dynamics.com/?company=Filmo&page=132&filter=FV26-001042"
}'
```

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/invoices/external/orig_8f2a1c/orig_8f2a1c', {
  method: 'PUT',
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY',
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    invoiceNumber: 'FV26-001042',
    invoiceDate: '2026-09-15',
    dueDate: '2026-10-15',
    currency: 'EUR',
    contactTaxId: 'B00000000',
    lines: [
      {
        description: 'Alquiler de equipo de cámara (3 jornadas)',
        quantity: '3',
        unitPrice: '450.00',
        taxRate: '21'
      },
      {
        description: 'Transporte ida y vuelta',
        quantity: '1',
        unitPrice: '120.00',
        taxType: 'IVA_21'
      }
    ],
    total: '1778.70',
    externalStatus: 'issued',
    paymentStatus: 'unpaid',
    originUrl: 'https://businesscentral.dynamics.com/?company=Filmo&page=132&filter=FV26-001042'
  })
})
```

**Python**

```python
import uuid
import requests

requests.put(
    "https://app.filmo.io/api/v1/invoices/external/orig_8f2a1c/orig_8f2a1c",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY",
      "Idempotency-Key": str(uuid.uuid4()),
      "Content-Type": "application/json"
    },
    json={
      "invoiceNumber": "FV26-001042",
      "invoiceDate": "2026-09-15",
      "dueDate": "2026-10-15",
      "currency": "EUR",
      "contactTaxId": "B00000000",
      "lines": [
        {
          "description": "Alquiler de equipo de cámara (3 jornadas)",
          "quantity": "3",
          "unitPrice": "450.00",
          "taxRate": "21"
        },
        {
          "description": "Transporte ida y vuelta",
          "quantity": "1",
          "unitPrice": "120.00",
          "taxType": "IVA_21"
        }
      ],
      "total": "1778.70",
      "externalStatus": "issued",
      "paymentStatus": "unpaid",
      "originUrl": "https://businesscentral.dynamics.com/?company=Filmo&page=132&filter=FV26-001042"
    }
)
```

## Respuesta

Esquema de la respuesta: `InvoiceDetailDto`

| Estado | Descripción |
| --- | --- |
| 200 | Respuesta correcta. |
| 201 | Creado: el recurso aún no existía y se ha creado. |
| 400 | Petición no válida (validation_error): consulta o cuerpo mal formados. `errors[]` enumera cada campo erróneo con su código estable. |
| 401 | Fallo de autenticación (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin). |
| 402 | Add-on requerido (addon_required): el plan de la cuenta no incluye el add-on que necesita esta operación; `requiredAddon` lo nombra. |
| 403 | No permitido (insufficient_scope: la clave de API no tiene el scope requerido, indicado en `requiredScope`; forbidden: el propietario de la clave carece del permiso que exige la operación). `insufficient_scope` se responde antes de que la petición cuente contra el límite de peticiones, así que no lleva cabeceras `RateLimit-*`; `forbidden` sí. |
| 404 | Recurso no encontrado (not_found): no existe o está fuera del alcance de la clave de API. |
| 409 | Conflicto (conflict): el estado actual del recurso impide la operación, ya hay en curso una petición con esa Idempotency-Key, o otra escritura condicional (`If-Match`) retuvo el recurso durante más de cinco segundos. `errors[0].code` indica cuál: `in_progress` y `lock_timeout` se resuelven reintentando; `invalid_state` no, porque el estado del recurso prohíbe la operación. |
| 422 | Idempotency-Key reutilizada (idempotency_key_reused): la misma clave se usó antes con un cuerpo distinto. Cambia la clave. |
| 429 | Límite de peticiones superado (rate_limited): reintenta tras `Retry-After` segundos; `RateLimit-*` indica qué cuota se ha agotado. |
| 500 | Error interno (internal_error). |

**200**

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `data` | object | La factura completa, tal como la devuelve la API. |
| `data.id` | string | Identificador único de la factura. |
| `data.invoiceNumber` | string | Número de factura; null mientras es un borrador (el número se asigna al validarla). |
| `data.status` | string | Estado del ciclo de vida del documento: draft, validated (validado y numerado) o voided. `draft`, `validated`, `voided` |
| `data.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. |
| `data.invoiceDate` | string<date-time> | Fecha de emisión en ISO 8601 con desfase; null mientras es un borrador. |
| `data.dueDate` | string<date-time> | Fecha de vencimiento en ISO 8601 con desplazamiento; null si no está definida. |
| `data.currency` | string | Moneda de la factura como código ISO 4217 (por ejemplo "EUR"). |
| `data.contact` | object | Referencia compacta al contacto facturado; null si no hay. |
| `data.contact.id` | string | Identificador único del contacto. |
| `data.contact.name` | string | Nombre del contacto. |
| `data.orderId` | string | Identificador del pedido de origen; null si la factura no procede de un pedido. |
| `data.orderNumber` | string | Número del pedido de origen; null si la factura no procede de un pedido. |
| `data.projectId` | string | Identificador del proyecto vinculado; null si no está vinculado. |
| `data.subTotal` | string | Subtotal antes de descuentos e impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.discountTotal` | string | Total de descuentos como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.taxesPrice` | string | Total de impuestos como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.netPrice` | string | Base imponible (neto antes de impuestos) como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.grossPrice` | string | Total con impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.totalPaid` | string | Importe cobrado hasta la fecha como cadena decimal "1234.50" (ROUND_HALF_UP); null si no consta. |
| `data.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` |
| `data.paymentMethod` | string | Método de pago de la factura; null si no se ha registrado. |
| `data.tags` | object[] | Etiquetas adjuntas a la factura, con su identificador y nombre. |
| `data.tags.id` | string | Identificador único de la etiqueta. |
| `data.tags.name` | string | Nombre de la etiqueta. |
| `data.createdAt` | string<date-time> | Fecha de creación en ISO 8601 con desplazamiento. |
| `data.updatedAt` | string<date-time> | Fecha de la última actualización en ISO 8601 con desplazamiento. |
| `data.projectName` | string | Nombre del proyecto vinculado; null si no está vinculado. |
| `data.taxBreakdown` | object[] | Desglose de impuestos por tipo; null si no se ha calculado. |
| `data.taxBreakdown.taxType` | string | Clave del tipo de impuesto (por ejemplo "IVA_21"). |
| `data.taxBreakdown.label` | string | Etiqueta de impuesto legible. |
| `data.taxBreakdown.rate` | number | Tipo impositivo aplicado, como porcentaje (por ejemplo 21 para el 21%). |
| `data.taxBreakdown.baseAmount` | string | Base imponible sobre la que se aplica el impuesto, como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.taxBreakdown.amount` | string | Importe del impuesto como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.productDiscountTotal` | string | Total de descuentos aplicados a nivel de producto, como cadena decimal "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. |
| `data.globalDiscountTotal` | string | Total de descuento global del documento, como cadena decimal "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. |
| `data.insuranceTotal` | string | Total del seguro como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.depositTotal` | string | Total de fianzas como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.exchangeRate` | number | Tipo de cambio aplicado cuando la moneda difiere de la moneda base; null si no aplica. |
| `data.billingAddress` | object | Dirección de facturación; null si no consta. |
| `data.billingAddress.label` | string | Etiqueta descriptiva de la dirección; null si no consta. |
| `data.billingAddress.addressLine1` | string | Primera línea de la dirección; null si no consta. |
| `data.billingAddress.addressLine2` | string | Segunda línea de la dirección; null si no consta. |
| `data.billingAddress.city` | string | Ciudad; null si no consta. |
| `data.billingAddress.province` | string | Provincia o región; null si no se ha registrado. |
| `data.billingAddress.postcode` | string | Código postal; null si no se ha registrado. |
| `data.billingAddress.country` | string | País; null si no consta. |
| `data.sourceQuoteIds` | string[] | Identificadores de los presupuestos de origen; null si la factura no procede de presupuestos. |
| `data.sourceProformaIds` | string[] | Identificadores de las proformas de origen; null si la factura no procede de proformas. |
| `meta` | object | Información adicional sobre la respuesta. |
| `meta.warnings` | object[] | Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta. |
| `meta.warnings.code` | string | Código de aviso estable. `deprecated` |
| `meta.warnings.message` | string | Para personas: qué está obsoleto, hasta cuándo y qué usar. |
| `meta.warnings.sunset` | string | Día (YYYY-MM-DD) en que la operación deja de estar disponible. |
| `meta.warnings.replacement` | string | `operationId` de la operación que hay que usar en su lugar, o null si no hay ninguna. |
| `meta.warnings.link` | string | Dónde está documentada la deprecación (el changelog). |

*Respuesta de ejemplo · 200*

```json
{
  "data": {
    "id": "invoice_9f3a2b",
    "invoiceNumber": "2026-0001",
    "status": "draft",
    "isRectification": true,
    "invoiceDate": "2026-09-01T08:00:00.000Z",
    "dueDate": "2026-09-01T08:00:00.000Z",
    "currency": "EUR",
    "contact": {
      "id": "contact_9f3a2b",
      "name": "Example contact"
    },
    "orderId": "order_9f3a2b",
    "orderNumber": "2026-0001",
    "projectId": "project_9f3a2b",
    "subTotal": "120.00",
    "discountTotal": "120.00",
    "taxesPrice": "120.00",
    "netPrice": "120.00",
    "grossPrice": "120.00",
    "totalPaid": "120.00",
    "paymentStatus": "unpaid",
    "paymentMethod": "Example payment method",
    "tags": [
      {
        "id": "tag_9f3a2b",
        "name": "Example tag"
      }
    ],
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z",
    "projectName": "Example project name",
    "taxBreakdown": [
      {
        "taxType": "120.00",
        "label": "Main",
        "rate": 1,
        "baseAmount": "120.00",
        "amount": "120.00"
      }
    ],
    "productDiscountTotal": "120.00",
    "globalDiscountTotal": "120.00",
    "insuranceTotal": "120.00",
    "depositTotal": "120.00",
    "exchangeRate": 1,
    "billingAddress": {
      "label": "Main",
      "addressLine1": "Calle de Ejemplo 12",
      "addressLine2": "Calle de Ejemplo 12",
      "city": "Madrid",
      "province": "Madrid",
      "postcode": "28001",
      "country": "ES"
    },
    "sourceQuoteIds": [
      "source_quote_9f3a2b"
    ],
    "sourceProformaIds": [
      "source_proforma_9f3a2b"
    ]
  }
}
```

**201**

| Nombre | Tipo | Descripción |
| --- | --- | --- |
| `data` | object | La factura completa, tal como la devuelve la API. |
| `data.id` | string | Identificador único de la factura. |
| `data.invoiceNumber` | string | Número de factura; null mientras es un borrador (el número se asigna al validarla). |
| `data.status` | string | Estado del ciclo de vida del documento: draft, validated (validado y numerado) o voided. `draft`, `validated`, `voided` |
| `data.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. |
| `data.invoiceDate` | string<date-time> | Fecha de emisión en ISO 8601 con desfase; null mientras es un borrador. |
| `data.dueDate` | string<date-time> | Fecha de vencimiento en ISO 8601 con desplazamiento; null si no está definida. |
| `data.currency` | string | Moneda de la factura como código ISO 4217 (por ejemplo "EUR"). |
| `data.contact` | object | Referencia compacta al contacto facturado; null si no hay. |
| `data.contact.id` | string | Identificador único del contacto. |
| `data.contact.name` | string | Nombre del contacto. |
| `data.orderId` | string | Identificador del pedido de origen; null si la factura no procede de un pedido. |
| `data.orderNumber` | string | Número del pedido de origen; null si la factura no procede de un pedido. |
| `data.projectId` | string | Identificador del proyecto vinculado; null si no está vinculado. |
| `data.subTotal` | string | Subtotal antes de descuentos e impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.discountTotal` | string | Total de descuentos como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.taxesPrice` | string | Total de impuestos como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.netPrice` | string | Base imponible (neto antes de impuestos) como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.grossPrice` | string | Total con impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.totalPaid` | string | Importe cobrado hasta la fecha como cadena decimal "1234.50" (ROUND_HALF_UP); null si no consta. |
| `data.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` |
| `data.paymentMethod` | string | Método de pago de la factura; null si no se ha registrado. |
| `data.tags` | object[] | Etiquetas adjuntas a la factura, con su identificador y nombre. |
| `data.tags.id` | string | Identificador único de la etiqueta. |
| `data.tags.name` | string | Nombre de la etiqueta. |
| `data.createdAt` | string<date-time> | Fecha de creación en ISO 8601 con desplazamiento. |
| `data.updatedAt` | string<date-time> | Fecha de la última actualización en ISO 8601 con desplazamiento. |
| `data.projectName` | string | Nombre del proyecto vinculado; null si no está vinculado. |
| `data.taxBreakdown` | object[] | Desglose de impuestos por tipo; null si no se ha calculado. |
| `data.taxBreakdown.taxType` | string | Clave del tipo de impuesto (por ejemplo "IVA_21"). |
| `data.taxBreakdown.label` | string | Etiqueta de impuesto legible. |
| `data.taxBreakdown.rate` | number | Tipo impositivo aplicado, como porcentaje (por ejemplo 21 para el 21%). |
| `data.taxBreakdown.baseAmount` | string | Base imponible sobre la que se aplica el impuesto, como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.taxBreakdown.amount` | string | Importe del impuesto como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.productDiscountTotal` | string | Total de descuentos aplicados a nivel de producto, como cadena decimal "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. |
| `data.globalDiscountTotal` | string | Total de descuento global del documento, como cadena decimal "1234.50" (ROUND_HALF_UP). productDiscountTotal + globalDiscountTotal = discountTotal. |
| `data.insuranceTotal` | string | Total del seguro como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.depositTotal` | string | Total de fianzas como cadena decimal "1234.50" (ROUND_HALF_UP). |
| `data.exchangeRate` | number | Tipo de cambio aplicado cuando la moneda difiere de la moneda base; null si no aplica. |
| `data.billingAddress` | object | Dirección de facturación; null si no consta. |
| `data.billingAddress.label` | string | Etiqueta descriptiva de la dirección; null si no consta. |
| `data.billingAddress.addressLine1` | string | Primera línea de la dirección; null si no consta. |
| `data.billingAddress.addressLine2` | string | Segunda línea de la dirección; null si no consta. |
| `data.billingAddress.city` | string | Ciudad; null si no consta. |
| `data.billingAddress.province` | string | Provincia o región; null si no se ha registrado. |
| `data.billingAddress.postcode` | string | Código postal; null si no se ha registrado. |
| `data.billingAddress.country` | string | País; null si no consta. |
| `data.sourceQuoteIds` | string[] | Identificadores de los presupuestos de origen; null si la factura no procede de presupuestos. |
| `data.sourceProformaIds` | string[] | Identificadores de las proformas de origen; null si la factura no procede de proformas. |
| `meta` | object | Información adicional sobre la respuesta. |
| `meta.warnings` | object[] | Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta. |
| `meta.warnings.code` | string | Código de aviso estable. `deprecated` |
| `meta.warnings.message` | string | Para personas: qué está obsoleto, hasta cuándo y qué usar. |
| `meta.warnings.sunset` | string | Día (YYYY-MM-DD) en que la operación deja de estar disponible. |
| `meta.warnings.replacement` | string | `operationId` de la operación que hay que usar en su lugar, o null si no hay ninguna. |
| `meta.warnings.link` | string | Dónde está documentada la deprecación (el changelog). |

*Respuesta de ejemplo · 201*

```json
{
  "data": {
    "id": "invoice_9f3a2b",
    "invoiceNumber": "2026-0001",
    "status": "draft",
    "isRectification": true,
    "invoiceDate": "2026-09-01T08:00:00.000Z",
    "dueDate": "2026-09-01T08:00:00.000Z",
    "currency": "EUR",
    "contact": {
      "id": "contact_9f3a2b",
      "name": "Example contact"
    },
    "orderId": "order_9f3a2b",
    "orderNumber": "2026-0001",
    "projectId": "project_9f3a2b",
    "subTotal": "120.00",
    "discountTotal": "120.00",
    "taxesPrice": "120.00",
    "netPrice": "120.00",
    "grossPrice": "120.00",
    "totalPaid": "120.00",
    "paymentStatus": "unpaid",
    "paymentMethod": "Example payment method",
    "tags": [
      {
        "id": "tag_9f3a2b",
        "name": "Example tag"
      }
    ],
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z",
    "projectName": "Example project name",
    "taxBreakdown": [
      {
        "taxType": "120.00",
        "label": "Main",
        "rate": 1,
        "baseAmount": "120.00",
        "amount": "120.00"
      }
    ],
    "productDiscountTotal": "120.00",
    "globalDiscountTotal": "120.00",
    "insuranceTotal": "120.00",
    "depositTotal": "120.00",
    "exchangeRate": 1,
    "billingAddress": {
      "label": "Main",
      "addressLine1": "Calle de Ejemplo 12",
      "addressLine2": "Calle de Ejemplo 12",
      "city": "Madrid",
      "province": "Madrid",
      "postcode": "28001",
      "country": "ES"
    },
    "sourceQuoteIds": [
      "source_quote_9f3a2b"
    ],
    "sourceProformaIds": [
      "source_proforma_9f3a2b"
    ]
  }
}
```

## Errores

| Estado | Códigos | Significado |
| --- | --- | --- |
| 400 | `validation_error` | Consulta o cuerpo mal formados. `errors[]` enumera cada campo erróneo con su código estable. |
| 402 | `addon_required` | El plan de la cuenta no incluye el add-on que necesita esta operación; `requiredAddon` lo nombra. |
| 404 | `not_found` | No existe o queda fuera del alcance de la clave de API. |
| 409 | `conflict` | El estado actual del recurso impide la operación, ya hay en curso una petición con esa Idempotency-Key, u otra escritura condicional (`If-Match`) retuvo el recurso durante más de cinco segundos. `errors[0].code` indica cuál: `in_progress` y `lock_timeout` se resuelven reintentando; `invalid_state` no, porque el estado del recurso prohíbe la operación. |
| 422 | `idempotency_key_reused` | La misma clave se usó antes con un cuerpo distinto. Cambia la clave. |

## Obsolescencia

Esta operación no está obsoleta. Las obsolescencias se anuncian con la cabecera Deprecation y una fecha de retirada.

---

URL canónica: https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/create-or-update-the-mirror-of-an-externally-issued-invoice  
Última actualización: 2026-10-25