Pedidos

Actualizar la cabecera de un pedido

Cambia la cabecera de un pedido: cliente, proyecto y fechas de alquiler (envía solo los campos que cambian; el resto queda como estaba).

PATCH
/api/v1/orders/{orderId}

Ejemplos de petición

curl https://app.filmo.io/api/v1/orders/orde_8f2a1c \
  --request PATCH \
  --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 '{
  "projectId": "prj_rodaje_otono",
  "startDate": "2026-09-08T08:00:00+02:00",
  "endDate": "2026-09-12T20:00:00+02:00"
}'
{
  "data": {
    "id": "order_9f3a2b",
    "orderNumber": "2026-0001",
    "externalReference": "2026-0001",
    "status": "draft",
    "startDate": "2026-09-01T08:00:00.000Z",
    "endDate": "2026-09-01T08:00:00.000Z",
    "rentalDays": 1,
    "projectId": "project_9f3a2b",
    "projectName": "Example project name",
    "contact": {
      "id": "contact_9f3a2b",
      "name": "Example contact"
    },
    "itemsCount": 1,
    "subTotalPrice": "120.00",
    "discountTotal": "120.00",
    "insuranceTotal": "120.00",
    "depositTotal": "120.00",
    "taxesPrice": "120.00",
    "netPrice": "120.00",
    "grossPrice": "120.00",
    "tags": [
      {
        "id": "tag_9f3a2b",
        "name": "Example tag"
      }
    ],
    "customFields": {
      "example": "example"
    },
    "source": "Example source",
    "createdAt": "2026-09-01T08:00:00.000Z",
    "updatedAt": "2026-09-01T08:00:00.000Z",
    "billingAddress": {
      "label": "Main",
      "addressLine1": "Calle de Ejemplo 12",
      "addressLine2": "Calle de Ejemplo 12",
      "city": "Madrid",
      "province": "Madrid",
      "postcode": "28001",
      "country": "ES"
    },
    "shippingAddress": {
      "label": "Main",
      "addressLine1": "Calle de Ejemplo 12",
      "addressLine2": "Calle de Ejemplo 12",
      "city": "Madrid",
      "province": "Madrid",
      "postcode": "28001",
      "country": "ES"
    },
    "contactPerson": {
      "id": "contact_person_9f3a2b",
      "name": "Example contact person"
    },
    "quotes": [
      {
        "id": "quote_9f3a2b",
        "number": "2026-0001",
        "status": "Example status"
      }
    ],
    "invoices": [
      {
        "id": "invoice_9f3a2b",
        "number": "2026-0001",
        "status": "Example status"
      }
    ],
    "proformas": [
      {
        "id": "proforma_9f3a2b",
        "number": "2026-0001",
        "status": "Example status"
      }
    ]
  }
}

Generado a partir del esquema

Cambiar startDate o endDate mueve el pedido ENTERO: se mueve con él cada línea que hereda el periodo del pedido (las secciones, los grupos por tipo y las líneas ya recepcionadas conservan el suyo), junto con sus reservas de stock y sus tareas de entrega y devolución; los precios no se recalculan. Si el stock no cabe en el nuevo periodo, o el pedido está cancelado o devuelto, responde 409 conflict y no se escribe nada; enviar las fechas que ya tiene no cambia nada. NO añade, quita ni edita líneas: eso pasa por el editor. Tampoco acepta importes ni estado, igual que la creación. El cliente y el proyecto se comprueban contra la cuenta de la clave de API antes de escribir nada. Devuelve el pedido completo, con la misma proyección que su GET.

Autorizaciones

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

Cabeceras

Idempotency-Keystring

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.

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

Ejemplo:"9f1c2f4e-3a5b-4f6d-8e7a-0b1c2d3e4f5a"

If-Matchstring

Bloqueo optimista: el ETag que leíste del recurso (o *). Si el recurso ha cambiado desde entonces, la escritura se rechaza con 412 precondition_failed antes de hacer nada; léelo de nuevo y reintenta. Sin la cabecera, la escritura siempre se realiza.

Ejemplo:"\"3sT3d9pBvZq4h2N0w8x1YkLmQ7c\""

Parámetros de ruta

orderIdstringObligatorio

Identificador del pedido.

Límites: longitud mín. 1

Cuerpo

application/json

Esquema del cuerpo: OrderUpdateBody

contactIdstring

Identificador del cliente del pedido. Debe pertenecer a la cuenta de la clave de API.

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

projectIdstring | null

Proyecto al que está asignado el pedido; null lo desvincula (pedido independiente).

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

startDatestring<date-time>

Inicio del alquiler (ISO 8601 con desplazamiento).

endDatestring<date-time>

Fin del alquiler (ISO 8601 con desplazamiento); debe ser posterior a startDate.

Respuesta

application/json

Respuesta correcta.

Esquema de la respuesta: OrderDetailDto

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

Cabeceras: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay

dataobject

El pedido completo, tal como lo devuelve la API.

Mostrar atributos hijos
data.idstring

Identificador único del pedido.

data.orderNumberstring

Número de pedido legible.

data.externalReferencestring | null

Referencia externa del pedido (por ejemplo, del sistema del cliente); null si no consta.

data.statusstring

Estado bruto del pedido tal como se almacena en la base de datos (12 valores): draft, reserved, prepared_partially, prepared, picked_up_partially, picked_up, returned_partially, returned, checked_in_partially, checked_in, archived o cancelled. archived forma parte del conjunto almacenado, pero un pedido archivado no es visible para la API, así que no lo observarás.

Opciones disponibles: draft, reserved, prepared_partially, prepared, picked_up_partially, picked_up, returned_partially, returned, checked_in_partially, checked_in, archived, cancelled

data.startDatestring<date-time>

Inicio del periodo de alquiler en ISO 8601 con desplazamiento.

data.endDatestring<date-time>

Fin del periodo de alquiler en ISO 8601 con desplazamiento.

data.rentalDaysnumber | null

Número de días de alquiler facturables; null si no se ha calculado.

data.projectIdstring | null

Identificador del proyecto al que pertenece el pedido; null si no está vinculado.

data.projectNamestring | null

Nombre del proyecto al que pertenece el pedido; null si no está vinculado.

data.contactobject | null

Referencia compacta al contacto del pedido; null si no hay.

Mostrar atributos hijos
data.contact.idstring

Identificador único del contacto.

data.contact.namestring

Nombre del contacto.

data.itemsCountinteger

Número de artículos del pedido.

data.subTotalPricestring

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

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

data.discountTotalstring | null

Total de descuentos como cadena decimal "1234.50" (ROUND_HALF_UP); null si no hay descuento.

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

data.insuranceTotalstring

Total del seguro como cadena decimal "1234.50" (ROUND_HALF_UP).

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

data.depositTotalstring

Total de fianzas 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.tagsobject[]

Etiquetas adjuntas al pedido, con su identificador y nombre.

Mostrar atributos hijos
data.tags.idstring

Identificador único de la etiqueta.

data.tags.namestring

Nombre de la etiqueta.

data.customFieldsobject<string, any>

Valores de los campos personalizados por identificador de campo personalizado; las definiciones están en /api/v1/custom-fields.

data.sourcestring | null

Origen desde el que se creó el pedido (por ejemplo web, mobile, admin); null si no consta.

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.

data.billingAddressobject | null

Dirección de facturación del pedido; null si no hay.

Mostrar atributos hijos
data.billingAddress.labelstring | null

Etiqueta descriptiva de la dirección; null si no consta.

data.billingAddress.addressLine1string | null

Primera línea de la dirección; null si no consta.

data.billingAddress.addressLine2string | null

Segunda línea de la dirección; null si no consta.

data.billingAddress.citystring | null

Ciudad; null si no consta.

data.billingAddress.provincestring | null

Provincia o región; null si no se ha registrado.

data.billingAddress.postcodestring | null

Código postal; null si no se ha registrado.

data.billingAddress.countrystring | null

País; null si no consta.

data.shippingAddressobject | null

Dirección de envío del pedido; null si no hay.

Mostrar atributos hijos
data.shippingAddress.labelstring | null

Etiqueta descriptiva de la dirección; null si no consta.

data.shippingAddress.addressLine1string | null

Primera línea de la dirección; null si no consta.

data.shippingAddress.addressLine2string | null

Segunda línea de la dirección; null si no consta.

data.shippingAddress.citystring | null

Ciudad; null si no consta.

data.shippingAddress.provincestring | null

Provincia o región; null si no se ha registrado.

data.shippingAddress.postcodestring | null

Código postal; null si no se ha registrado.

data.shippingAddress.countrystring | null

País; null si no consta.

data.contactPersonobject | null

Persona de contacto vinculada al pedido; null si no hay ninguna.

Mostrar atributos hijos
data.contactPerson.idstring

Identificador único del contacto.

data.contactPerson.namestring

Nombre del contacto.

data.quotesobject[]

Referencias informativas a los presupuestos generados a partir del pedido.

Mostrar atributos hijos
data.quotes.idstring

Identificador único del documento referenciado.

data.quotes.numberstring | null

Número del documento; null hasta que se numera.

data.quotes.statusstring | null

Estado del documento en el momento en que se escribió la referencia; null si no consta. Informativo: puede estar desactualizado.

data.invoicesobject[]

Referencias informativas a las facturas generadas a partir del pedido.

Mostrar atributos hijos
data.invoices.idstring

Identificador único del documento referenciado.

data.invoices.numberstring | null

Número del documento; null hasta que se numera.

data.invoices.statusstring | null

Estado del documento en el momento en que se escribió la referencia; null si no consta. Informativo: puede estar desactualizado.

data.proformasobject[]

Referencias informativas a las proformas generadas a partir del pedido.

Mostrar atributos hijos
data.proformas.idstring

Identificador único del documento referenciado.

data.proformas.numberstring | null

Número del documento; null hasta que se numera.

data.proformas.statusstring | null

Estado del documento en el momento en que se escribió la referencia; null si no consta. Informativo: puede estar desactualizado.

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.

Errores

EstadoCódigosSignificado
400validation_errorConsulta o cuerpo mal formados. errors[] enumera cada campo erróneo con su código estable.
404not_foundNo existe o queda fuera del alcance de la clave de API.
409conflictEl 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.
412precondition_failedLa etiqueta de entidad If-Match no coincide con la representación actual. Vuelve a leer el recurso y reintenta.
422idempotency_key_reusedLa misma clave se usó antes con un cuerpo distinto. Cambia la clave.

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

  • Alquileres

    Pedido

    El pedido, tal como lo devuelve la API.