*API REST › Referencia de endpoints › Finanzas › Facturas de proveedor*

# Listar facturas de proveedor

> Devuelve las facturas recibidas de proveedores, paginadas por cursor, con la misma ficha compacta que la lectura de detalle.

Filtra por estado dentro del ciclo de compras, contacto proveedor, pedido de venta vinculado, proyecto, fecha de factura y fecha de vencimiento. Ordenadas por fecha de factura, las más recientes primero.

`GET /api/v1/supplier-invoices` — permiso `supplier-invoices:read`

Permiso: `supplier-invoices:read` · 120/min · Complemento (402) · MCP: `filmo_supplier_invoices_list`

## Autorizaciones

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

## Parámetros de consulta

| Nombre | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- |
| `limit` | integer | No | Tamaño de página (1-500). Por defecto es 50. = `50` |
| `cursor` | string | No | Cursor opaco de la página que se devuelve. Pasa el valor de `pagination.nextCursor` de la respuesta anterior; trátalo como opaco. |
| `createdOn` | string | No | 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. |
| `createdAfter` | string | No | 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. |
| `createdBefore` | string | No | 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. |
| `createdFrom` | string | No | 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. |
| `createdTo` | string | No | 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. |
| `updatedOn` | string | No | 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. |
| `updatedAfter` | string | No | 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. |
| `updatedBefore` | string | No | 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. |
| `updatedFrom` | string | No | 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. |
| `updatedTo` | string | No | 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. |
| `sort` | string | No | Orden: hasta 3 campos separados por comas, cada uno con un "-" inicial para descendente (p. ej. "-updatedAt,name"). Campos ordenables: createdAt, updatedAt, invoiceDate, dueDate. Por defecto, "-invoiceDate". 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ó. |
| `status` | string | No | Filtra por estado dentro del ciclo de compras: draft, validated o voided. `draft`, `validated`, `voided` |
| `statuses` | string[] | No | Filtra por status, 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. `draft`, `validated`, `voided` |
| `contactId` | string | No | Filtra por identificador del contacto proveedor que emitió la factura. |
| `contactIds` | string[] | No | 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. |
| `orderId` | string | No | Filtra por identificador del pedido de venta al que está vinculada la factura. |
| `orderIds` | string[] | No | 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. |
| `projectId` | string | No | Filtra por identificador del proyecto vinculado a la factura, directamente o a través de su pedido. |
| `projectIds` | string[] | No | 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. |
| `invoiceDateOn` | string | No | La fecha que el proveedor puso en 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. |
| `invoiceDateAfter` | string | No | La fecha que el proveedor puso en 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. |
| `invoiceDateBefore` | string | No | La fecha que el proveedor puso en 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. |
| `invoiceDateFrom` | string | No | La fecha que el proveedor puso en 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. |
| `invoiceDateTo` | string | No | La fecha que el proveedor puso en 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. |
| `dueOn` | string | No | La fecha de vencimiento de la factura de proveedor 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. |
| `dueAfter` | string | No | La fecha de vencimiento de la factura de proveedor 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. |
| `dueBefore` | string | No | La fecha de vencimiento de la factura de proveedor 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. |
| `dueFrom` | string | No | La fecha de vencimiento de la factura de proveedor 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. |
| `dueTo` | string | No | La fecha de vencimiento de la factura de proveedor 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. |
| `includeTotal` | boolean | No | 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. = `false` |

## Ejemplos de petición

*Listar facturas de proveedor*

**cURL**

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

**Node.js**

```javascript
fetch('https://app.filmo.io/api/v1/supplier-invoices', {
  headers: {
    Authorization: 'Bearer YOUR_FILMO_API_KEY'
  }
})
```

**Python**

```python
import requests

requests.get(
    "https://app.filmo.io/api/v1/supplier-invoices",
    headers={
      "Authorization": "Bearer YOUR_FILMO_API_KEY"
    }
)
```

## Respuesta

Esquema de la respuesta: `SupplierInvoiceDto`

| Estado | Descripción |
| --- | --- |
| 200 | Respuesta correcta. |
| 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í. |
| 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[] |  |
| `data.id` | string | Identificador de la factura de proveedor. |
| `data.supplierInvoiceNumber` | string | Número que el proveedor puso en la factura; null si no se registró. |
| `data.status` | string | Estado de la factura dentro del ciclo de compras. |
| `data.createdAt` | string<date-time> | Fecha de creación en ISO 8601 UTC. |
| `data.updatedAt` | string<date-time> | Fecha de la última modificación en ISO 8601 UTC. |
| `pagination` | object | Metadatos de paginación por cursor opaco. |
| `pagination.nextCursor` | string | Cursor opaco de la página siguiente; null cuando no hay más resultados. Pásalo como `cursor` en la siguiente petición. |
| `pagination.hasMore` | boolean | Si existen más resultados después de esta página. |
| `pagination.total` | integer | Número de resultados que coinciden con los filtros en todas las páginas. Solo aparece cuando la petición establece `includeTotal=true`. |
| `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": "supplier_invoice_9f3a2b",
      "supplierInvoiceNumber": "2026-0001",
      "status": "Example status",
      "createdAt": "2026-09-01T08:00:00.000Z",
      "updatedAt": "2026-09-01T08:00:00.000Z"
    }
  ],
  "pagination": {
    "nextCursor": "eyJvIjoyMH0",
    "hasMore": true,
    "total": 1
  }
}
```

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

## 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/supplier-invoices/list-supplier-invoices  
Última actualización: 2026-10-25