*API REST › Objetos › Finanzas*

# Factura

> La factura, tal como la devuelve la API.

Una factura emitida. `status` es el ciclo de vida del documento (borrador, validada o anulada) y `paymentStatus` indica cuánto se ha cobrado. Apunta a su contacto, pedido y proyecto, y la lista devuelve solo documentos de tipo factura. Las facturas están acotadas a la suscripción que posee la clave. Las facturas no tienen campo de serie. Solo la lectura de detalle, [`GET /api/v1/invoices/{invoiceId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/get-an-invoice), incluye el desglose de impuestos ([`taxBreakdown`](https://docs.filmo.io/es/rest-api/objects/invoice#response-taxBreakdown): tipo de impuesto, etiqueta, tasa, base e importe). También añade los totales de descuentos, seguro y fianza, el tipo de cambio, la dirección de facturación, el nombre del proyecto y los presupuestos y proformas de los que procede la factura.

Esquemas: `InvoiceDto`, `InvoiceDetailDto`

## Atributos

| 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<date-time> | Fecha de emisión en ISO 8601 con desfase; null mientras es un borrador. |
| `dueDate` | string<date-time> | 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<date-time> | Fecha de creación en ISO 8601 con desplazamiento. |
| `updatedAt` | string<date-time> | 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. |

## Valores

| Campo | Valores |
| --- | --- |
| `status` | `draft`, `validated`, `voided` |
| `paymentStatus` | `unpaid`, `partially_paid`, `paid`, `overpaid`, `overdue`, `voided` |

## Ejemplo

*Invoice · Generado a partir del esquema*

```json
{
  "id": "id_8f2a1c",
  "invoiceNumber": "string",
  "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": "string",
  "orderNumber": "string",
  "projectId": "string",
  "subTotal": "1234.50",
  "discountTotal": "1234.50",
  "taxesPrice": "1234.50",
  "netPrice": "1234.50",
  "grossPrice": "1234.50",
  "totalPaid": "1234.50",
  "paymentStatus": "unpaid",
  "paymentMethod": "string",
  "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": "string",
    "addressLine2": "string",
    "city": "string",
    "province": "string",
    "postcode": "string",
    "country": "ES"
  },
  "sourceQuoteIds": [
    "string"
  ],
  "sourceProformaIds": [
    "string"
  ]
}
```

## Lo devuelven

- [`GET /api/v1/invoices`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/list-invoices) — Listar facturas
- [`GET /api/v1/invoices/{invoiceId}`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/get-an-invoice) — Obtener una factura

## Lo modifican

- [`POST /api/v1/invoices/{invoiceId}/validate`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/validate-an-invoice) — Validar una factura
- [`POST /api/v1/invoices/{invoiceId}/void`](https://docs.filmo.io/es/rest-api/endpoint-reference/invoices/void-an-invoice) — Anular una factura
- [`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) — Crear o actualizar el espejo de una factura emitida externamente

---

URL canónica: https://docs.filmo.io/es/rest-api/objects/invoice  
Última actualización: 2026-10-25