Facturas

Listar facturas

Devuelve las facturas emitidas (solo documentos de tipo factura), paginadas por cursor.

GET

/api/v1/invoices

curl https://app.filmo.io/api/v1/invoices \
  --header "Authorization: Bearer $FILMO_API_KEY"

Node.jsfetch('https://app.filmo.io/api/v1/invoices', { headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY' } })Pythonimport requests requests.get("https://app.filmo.io/api/v1/invoices", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY" } )

{
  "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"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "invoices:read"
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generado a partir del esquema

Filtra por estado del documento o del pago. Aislamiento estricto por suscripción.

Autorizaciones

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

Parámetros de consulta

limitintegerpredeterminado:50

Tamaño de página (1-500). Por defecto es 50.

Límites: mín. 1, máx. 500

cursorstring

Cursor opaco de la página que se devuelve. Pasa el valor de pagination.nextCursor de la respuesta anterior; trátalo como opaco.

Límites: longitud máx. 200

createdOnstring

La fecha de creación del recurso cae en esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdAfterstring

La fecha de creación del recurso es posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdBeforestring

La fecha de creación del recurso es anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdFromstring

La fecha de creación del recurso es igual o posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

createdTostring

La fecha de creación del recurso es igual o anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedOnstring

La fecha de última actualización del recurso cae en esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedAfterstring

La fecha de última actualización del recurso es posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedBeforestring

La fecha de última actualización del recurso es anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedFromstring

La fecha de última actualización del recurso es igual o posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

updatedTostring

La fecha de última actualización del recurso es igual o anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

sortstring

Orden: hasta 3 campos separados por comas, cada uno con un "-" inicial para descendente (p. ej. "-updatedAt,name"). Campos ordenables: createdAt, updatedAt, invoiceNumber, invoiceDate, dueDate, subTotal, grossPrice. Por defecto, "-createdAt". Los empates se resuelven por id, así que el orden es estable entre páginas, y un cursor queda ligado al orden con el que se emitió.

Límites: longitud máx. 200

paymentStatusstring

Filtra por estado de pago, con el mismo vocabulario que devuelve el campo paymentStatus: unpaid (nada cobrado todavía), partially_paid, paid, overpaid (cobrado por encima del total), overdue (vencido y sin pagar) o voided (el documento está anulado).

Opciones disponibles: unpaid, partially_paid, paid, overpaid, overdue, voided

paymentStatusesstring[]

Filtra por paymentStatus, como lista: repite el parámetro o separa los valores con comas. Acepta hasta 50 valores y devuelve lo que coincida con cualquiera de ellos.

Opciones disponibles: unpaid, partially_paid, paid, overpaid, overdue, voided

Límites: mín. 1 elementos, máx. 50 elementos

contactIdstring

Filtra por identificador del contacto de la factura.

Límites: longitud mín. 1, longitud máx. 100

contactIdsstring[]

Filtra por contactId, como lista: repite el parámetro o separa los valores con comas. Acepta hasta 50 valores y devuelve lo que coincida con cualquiera de ellos.

Límites: mín. 1 elementos, máx. 50 elementos, cada uno: longitud mín. 1, cada uno: longitud máx. 100

orderIdstring

Filtra por identificador del pedido de origen de la factura.

Límites: longitud mín. 1, longitud máx. 100

orderIdsstring[]

Filtra por orderId, como lista: repite el parámetro o separa los valores con comas. Acepta hasta 50 valores y devuelve lo que coincida con cualquiera de ellos.

Límites: mín. 1 elementos, máx. 50 elementos, cada uno: longitud mín. 1, cada uno: longitud máx. 100

projectIdstring

Filtra por identificador del proyecto vinculado a la factura.

Límites: longitud mín. 1, longitud máx. 100

projectIdsstring[]

Filtra por projectId, como lista: repite el parámetro o separa los valores con comas. Acepta hasta 50 valores y devuelve lo que coincida con cualquiera de ellos.

Límites: mín. 1 elementos, máx. 50 elementos, cada uno: longitud mín. 1, cada uno: longitud máx. 100

invoiceDateOnstring

La fecha de emisión de la factura cae en esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

invoiceDateAfterstring

La fecha de emisión de la factura es posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

invoiceDateBeforestring

La fecha de emisión de la factura es anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

invoiceDateFromstring

La fecha de emisión de la factura es igual o posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

invoiceDateTostring

La fecha de emisión de la factura es igual o anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

dueOnstring

La fecha de vencimiento de la factura cae en esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

dueAfterstring

La fecha de vencimiento de la factura es posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

dueBeforestring

La fecha de vencimiento de la factura es anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

dueFromstring

La fecha de vencimiento de la factura es igual o posterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

dueTostring

La fecha de vencimiento de la factura es igual o anterior a esta fecha. Una fecha sin hora (YYYY-MM-DD, interpretada en la zona horaria del negocio) o un instante ISO 8601 con desplazamiento.

Límites: patrón ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}(:?\d{2})?))?$

includeTotalbooleanpredeterminado:false

Ponlo en true para incluir pagination.total, el número de resultados que coinciden con los filtros en todas las páginas. Desactivado por defecto.

Respuesta

application/json

Respuesta correcta.

Esquema de la respuesta: InvoiceDto

Sobre: InvoiceList. meta.warnings solo aparece cuando la operación está obsoleta.

Cabeceras: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset

dataobject[]

Mostrar atributos hijos

data.idstring

Identificador único de la factura.

data.invoiceNumberstring | null

Número de factura; null mientras es un borrador (el número se asigna al validarla).

data.statusstring

Estado del ciclo de vida del documento: draft, validated (validado y numerado) o voided.

Opciones disponibles: draft, validated, voided

data.isRectificationboolean

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.invoiceDatestring<date-time> | null

Fecha de emisión en ISO 8601 con desfase; null mientras es un borrador.

data.dueDatestring<date-time> | null

Fecha de vencimiento en ISO 8601 con desplazamiento; null si no está definida.

data.currencystring

Moneda de la factura como código ISO 4217 (por ejemplo "EUR").

data.contactobject | null

Referencia compacta al contacto facturado; null si no hay.

Mostrar atributos hijos

data.contact.idstring

Identificador único del contacto.

data.contact.namestring

Nombre del contacto.

data.orderIdstring | null

Identificador del pedido de origen; null si la factura no procede de un pedido.

data.orderNumberstring | null

Número del pedido de origen; null si la factura no procede de un pedido.

data.projectIdstring | null

Identificador del proyecto vinculado; null si no está vinculado.

data.subTotalstring

Subtotal antes de descuentos e impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP).

Límites: patrón ^-?\d+\.\d{2}$

data.discountTotalstring

Total de descuentos como cadena decimal "1234.50" (ROUND_HALF_UP).

Límites: patrón ^-?\d+\.\d{2}$

data.taxesPricestring

Total de impuestos como cadena decimal "1234.50" (ROUND_HALF_UP).

Límites: patrón ^-?\d+\.\d{2}$

data.netPricestring

Base imponible (neto antes de impuestos) como cadena decimal "1234.50" (ROUND_HALF_UP).

Límites: patrón ^-?\d+\.\d{2}$

data.grossPricestring

Total con impuestos, como cadena decimal "1234.50" (ROUND_HALF_UP).

Límites: patrón ^-?\d+\.\d{2}$

data.totalPaidstring | null

Importe cobrado hasta la fecha como cadena decimal "1234.50" (ROUND_HALF_UP); null si no consta.

Límites: patrón ^-?\d+\.\d{2}$

data.paymentStatusstring

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.

Opciones disponibles: unpaid, partially_paid, paid, overpaid, overdue, voided

data.paymentMethodstring | null

Método de pago de la factura; null si no se ha registrado.

data.tagsobject[]

Etiquetas adjuntas a la factura, con su identificador y nombre.

Mostrar atributos hijos

data.tags.idstring

Identificador único de la etiqueta.

data.tags.namestring

Nombre de la etiqueta.

data.createdAtstring<date-time>

Fecha de creación en ISO 8601 con desplazamiento.

data.updatedAtstring<date-time>

Fecha de la última actualización en ISO 8601 con desplazamiento.

paginationobject

Metadatos de paginación por cursor opaco.

Mostrar atributos hijos

pagination.nextCursorstring | null

Cursor opaco de la página siguiente; null cuando no hay más resultados. Pásalo como cursor en la siguiente petición.

pagination.hasMoreboolean

Si existen más resultados después de esta página.

pagination.totalinteger

Número de resultados que coinciden con los filtros en todas las páginas. Solo aparece cuando la petición establece includeTotal=true.

Límites: mín. 0

metaobject

Información adicional sobre la respuesta.

Mostrar atributos hijos

meta.warningsobject[]

Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta.

Mostrar atributos hijos

meta.warnings.codestring

Código de aviso estable.

Opciones disponibles: deprecated

meta.warnings.messagestring

Para personas: qué está obsoleto, hasta cuándo y qué usar.

meta.warnings.sunsetstring

Día (YYYY-MM-DD) en que la operación deja de estar disponible.

meta.warnings.replacementstring | null

operationId de la operación que hay que usar en su lugar, o null si no hay ninguna.

meta.warnings.linkstring

Dónde está documentada la deprecación (el changelog).

Errores

Estado	Códigos	Significado
400	`validation_error`	Consulta o cuerpo mal formados. `errors[]` enumera cada campo erróneo con su código estable.

401, 403, 429, 500 los puede devolver cualquier operación. Errores

Obsolescencia

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

Finanzas
Factura
La factura, tal como la devuelve la API.

¿Te ha resultado útil esta página?

Ejemplos de petición

Autorizaciones

Parámetros de consulta

Respuesta

Errores

Obsolescencia

Relacionado

Páginas relacionadas

Factura