Filtrado y orden

Envía sort con hasta tres campos separados por comas; repetir un campo es un 400. Las listas como incidencias, kits, servicios, pagos, pagos de facturas y cuentas de tesorería admiten un solo campo (consulta la descripción del parámetro). Un - al principio ordena ese campo de forma descendente: sort=-startDate,orderNumber. Cada lista nombra sus campos ordenables en la descripción del parámetro; para los pedidos son createdAt, updatedAt, startDate, endDate, orderNumber, grossPrice, rentalDays y itemsCount, y el valor por defecto es -createdAt.

• Un campo que no está en la lista de campos ordenables se rechaza con 400 validation_error, y el error lo nombra.
• Los empates se deshacen por id, así que el orden es estable entre páginas.
• Un cursor está ligado al orden con el que se emitió: mantén el mismo sort en cada página. Consulta Paginación.
• GET /api/v1/availability/unavailabilities no acepta sort: sigue el cursor de fecha de su origen. Las listas que no están paginadas (consulta Paginación) tampoco se pueden ordenar.
• Si ordenas por un campo que cambia mientras paginas, como updatedAt, un registro puede repetirse u omitirse.

Los campos ordenables de cada lista:

La mayoría de las listas filtran por el momento en que se creó o se actualizó por última vez un registro. Las dos familias comparten cinco sufijos:

Cada valor es una fecha sin hora (YYYY-MM-DD) o un instante ISO 8601 con desplazamiento. Una fecha sin hora se interpreta en la zona horaria del negocio de la cuenta (timezone): From empieza al comienzo de ese día, To termina al final de él, After significa después del final de ese día, Before significa antes de su comienzo y On abarca el día entero. Un instante con desplazamiento se aplica tal cual, salvo con On, que abarca todo el día de negocio que lo contiene.

Los operadores son estrictos donde lo dicen sus nombres: After es >, Before es <, From es >= y To es <=, comparados con precisión de milisegundo. Para una fecha sin hora, From y Before usan las 00:00:00.000 de ese día y To y After usan las 23:59:59.999, de modo que updatedAfter=2026-10-09 excluye todo el 9 de octubre. From junto con Before da una ventana semiabierta, [from, before), cuyos bordes nunca se solapan con la ventana siguiente. Esa es la forma Sincronizar datos en el que se basa. No todas las listas tienen estos filtros: GET /api/v1/tags, GET /api/v1/task-types, GET /api/v1/crm/pipelines, GET /api/v1/custom-fields y GET /api/v1/project-types rechazan con 400 cualquier filtro created* o updated*; GET /api/v1/kits, GET /api/v1/services, GET /api/v1/internal-services, GET /api/v1/crm/opportunities, GET /api/v1/orders/{orderId}/lines, GET /api/v1/invoices/{invoiceId}/lines, GET /api/v1/quotes/{quoteId}/lines y GET /api/v1/invoices/{invoiceId}/payments no tienen filtros updated*, y GET /api/v1/incidents solo tiene created*; GET /api/v1/payment-methods, GET /api/v1/treasury/payments y GET /api/v1/treasury/accounts se pueden ordenar por updatedAt pero no tienen filtros updated*. Comprueba los parámetros de la operación. Las listas añaden además sus propios filtros de fecha; los pedidos filtran también por cuándo empiezan y terminan (por ejemplo startsFrom y endsBefore) y por un periodo de alquiler que se solapa con una ventana (overlapsFrom y overlapsTo).

Algunos filtros tienen un gemelo que admite listas de valores. statuses, contactIds y projectIds admiten hasta 50 valores y devuelven los registros que coinciden con cualquiera de ellos. Repite el parámetro o separa los valores con comas: statuses=reserved,prepared y statuses=reserved&statuses=prepared son el mismo filtro.

• El filtro de un solo valor es otro parámetro: status admite un grupo operativo (draft, reserved, prepared, in_use, returned, completed o cancelled), contactId un contacto.
• Más de 50 valores es un 400. Para filtrar por un conjunto mayor, divídelo en lotes de 50 y combina los resultados.

Cuando una lista ofrece q, es una búsqueda de texto libre cuya descripción indica qué compara. En pedidos busca el número de pedido, el nombre o alias del proyecto y la referencia externa, con una longitud de 1 a 200 caracteres.

Pedidos reservados o preparados, actualizados desde el 1 de octubre y antes del 8 de octubre, cuyo texto coincide con acme, primero los que empiezan antes y, entre inicios iguales, primero los más grandes:

curl -sS --fail-with-body -G "${FILMO_BASE_URL:-https://app.filmo.io}/api/v1/orders" \
  -H "Authorization: Bearer $FILMO_API_KEY" \
  --data-urlencode "statuses=reserved,prepared" \
  --data-urlencode "updatedFrom=2026-10-01" \
  --data-urlencode "updatedBefore=2026-10-08T00:00:00+02:00" \
  --data-urlencode "q=acme" \
  --data-urlencode "sort=startDate,-grossPrice" \
  --data-urlencode "limit=50" |
  jq -r '.data[] | [.orderNumber, .status, .startDate, .grossPrice] | @tsv'

const base = process.env.FILMO_BASE_URL ?? "https://app.filmo.io";
const url = new URL("/api/v1/orders", base);
url.searchParams.set("statuses", "reserved,prepared"); // or repeat: statuses=reserved&statuses=prepared
url.searchParams.set("updatedFrom", "2026-10-01"); // on or after the start of that day (account timezone)
url.searchParams.set("updatedBefore", "2026-10-08T00:00:00+02:00"); // before this instant
url.searchParams.set("q", "acme");
url.searchParams.set("sort", "startDate,-grossPrice"); // soonest start first, then the biggest order
url.searchParams.set("limit", "50");

const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.FILMO_API_KEY}` } });
if (!res.ok) throw new Error(res.status + " " + (await res.text()));
const { data } = await res.json();
for (const order of data) console.log(order.orderNumber, order.status, order.startDate, order.grossPrice);

import os
import requests

base = os.environ.get("FILMO_BASE_URL", "https://app.filmo.io")
params = {
    "statuses": ["reserved", "prepared"],  # sent as repeated parameters; a comma-separated string works too
    "updatedFrom": "2026-10-01",  # on or after the start of that day (account timezone)
    "updatedBefore": "2026-10-08T00:00:00+02:00",  # before this instant
    "q": "acme",
    "sort": "startDate,-grossPrice",  # soonest start first, then the biggest order
    "limit": 50,
}
res = requests.get(
    base + "/api/v1/orders",
    headers={"Authorization": f"Bearer {os.environ['FILMO_API_KEY']}"},
    params=params,
    timeout=30,
)
res.raise_for_status()
for order in res.json()["data"]:
    print(order["orderNumber"], order["status"], order["startDate"], order["grossPrice"])

Combina los filtros con el bucle de Paginación: mantén los mismos filtros, sort y limit en cada página.