Pedidos

Devolver líneas de pedido

Marca el material que vuelve como devuelto: qué línea, cuántas unidades y en qué estado.

POST
/api/v1/orders/line-items/returns

Ejemplos de petición

curl https://app.filmo.io/api/v1/orders/line-items/returns \
  --request POST \
  --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 '{
  "items": [
    {
      "lineItemId": "oli_00913",
      "checkInQuantity": 3,
      "returnCondition": "good"
    },
    {
      "lineItemId": "oli_01120",
      "checkInQuantity": 1,
      "returnCondition": "damaged"
    }
  ],
  "checkedInAt": "2026-09-10T18:30:00+02:00"
}'
{
  "data": [
    {
      "index": 1,
      "id": "order_line_return_result_9f3a2b",
      "status": "returned",
      "error": {
        "code": "Example code",
        "message": "Example text."
      }
    }
  ]
}

Generado a partir del esquema

Envía tu propia Idempotency-Key

Un reintento sin la misma clave duplica el efecto. Envía tu propia Idempotency-Key y sigue la tabla de reintentos. Con atomic: false, un 207 lista las líneas que fallaron: reenvía solo esas, con una clave nueva.

Cuelga del recurso y no de un pedido porque una descarga cruza pedidos, que es lo que esta llamada resuelve de una vez. Envía Idempotency-Key: devolver dos veces la misma línea metería el material en el stock dos veces, y cada línea va como máximo una vez por petición (suma sus cantidades). Es un lote: atomic es true por defecto, así que una línea que no se puede devolver rechaza todo el lote con 409 y una incidencia por línea fallida, sin tocar nada; con atomic: false cada pedido se procesa por separado y la respuesta es 207 con un resultado por elemento, donde los fallidos no se devolvieron y el resto SÍ. Si todo va bien, la respuesta es 200 con un resultado por elemento, en el orden de la petición.

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"

Cuerpo

application/json

Esquema del cuerpo: OrderLineItemsReturnBody

itemsobject[]Obligatorio

Líneas que se devuelven. Al menos una, como máximo 500, cada línea como máximo una vez.

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

Mostrar atributos hijos
items.lineItemIdstringObligatorio

Línea de pedido que se devuelve.

Límites: longitud mín. 1

items.checkInQuantitynumberObligatorio

Unidades que se devuelven, al menos una. Puede ser una devolución parcial.

Límites: mín. 1

items.returnConditionstringObligatorio

Estado físico en el que vuelve el material: good, damaged, lost, needs_repair o incident.

Opciones disponibles: good, damaged, lost, needs_repair, incident

checkedInAtstring<date-time>

Fecha efectiva de la devolución, en ISO 8601 con desplazamiento. Por defecto, ahora.

atomicbooleanpredeterminado:true

Todo o nada (por defecto true): si alguna línea no se puede devolver, no se devuelve ninguna y la respuesta es 409 con una incidencia por línea. Con false, cada pedido se procesa por separado, la respuesta es 207 y cada elemento lleva su propio estado.

Respuesta

application/json

Respuesta correcta.

Esquema de la respuesta: OrderLineReturnResultDto

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

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

dataobject[]

Mostrar atributos hijos
data.indexinteger

Posición del elemento en el array de la petición.

data.idstring

Identificador del elemento tal como se envió.

data.statusstring

returned o failed.

Opciones disponibles: returned, failed

data.errorobject | null

Por qué falló; null cuando es returned.

Mostrar atributos hijos
data.error.codestring

Código de error estable del elemento, del mismo catálogo que errors[].

data.error.messagestring

Motivo localizado.

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