Pedidos
Devolver líneas de pedido
Marca el material que vuelve como devuelto: qué línea, cuántas unidades y en qué estado.
orders:write- 120/min
- Idempotency-Key
- Envía tu propia Idempotency-Key
- MCP: filmo_orders_line_items_return
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"
}'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
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
Esquema del cuerpo: OrderLineItemsReturnBody
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 hijosOcultar atributos hijos
Línea de pedido que se devuelve.
Límites: longitud mín. 1
Unidades que se devuelven, al menos una. Puede ser una devolución parcial.
Límites: mín. 1
Estado físico en el que vuelve el material: good, damaged, lost, needs_repair o incident.
Opciones disponibles: good, damaged, lost, needs_repair, incident
Fecha efectiva de la devolución, en ISO 8601 con desplazamiento. Por defecto, ahora.
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
Respuesta correcta.
Esquema de la respuesta: OrderLineReturnResultDto
Sobre: OrderLineReturnResultItems. meta. solo aparece cuando la operación está obsoleta.
Cabeceras: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Mostrar atributos hijosOcultar atributos hijos
Posición del elemento en el array de la petición.
Identificador del elemento tal como se envió.
returned o failed.
Opciones disponibles: returned, failed
Por qué falló; null cuando es returned.
Mostrar atributos hijosOcultar atributos hijos
Código de error estable del elemento, del mismo catálogo que errors[].
Motivo localizado.
Información adicional sobre la respuesta.
Mostrar atributos hijosOcultar atributos hijos
Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta.
Mostrar atributos hijosOcultar atributos hijos
Código de aviso estable.
Opciones disponibles: deprecated
Para personas: qué está obsoleto, hasta cuándo y qué usar.
Día (YYYY-MM-DD) en que la operación deja de estar disponible.
operationId de la operación que hay que usar en su lugar, o null si no hay ninguna.
Dónde está documentada la deprecación (el changelog).
Multi-Status (atomic: false): el lote se procesó elemento por elemento; lee cada status y error.
Esquema de la respuesta: OrderLineReturnResultDto
Sobre: OrderLineReturnResultItems. meta. solo aparece cuando la operación está obsoleta.
Cabeceras: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Mostrar atributos hijosOcultar atributos hijos
Posición del elemento en el array de la petición.
Identificador del elemento tal como se envió.
returned o failed.
Opciones disponibles: returned, failed
Por qué falló; null cuando es returned.
Mostrar atributos hijosOcultar atributos hijos
Código de error estable del elemento, del mismo catálogo que errors[].
Motivo localizado.
Información adicional sobre la respuesta.
Mostrar atributos hijosOcultar atributos hijos
Avisos del ciclo de vida; solo aparecen cuando la operación está obsoleta.
Mostrar atributos hijosOcultar atributos hijos
Código de aviso estable.
Opciones disponibles: deprecated
Para personas: qué está obsoleto, hasta cuándo y qué usar.
Día (YYYY-MM-DD) en que la operación deja de estar disponible.
operationId de la operación que hay que usar en su lugar, o null si no hay ninguna.
Dónde está documentada la deprecación (el changelog).
Petición no válida (validation_error): consulta o cuerpo mal formados. errors[] enumera cada campo erróneo con su código estable.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Fallo de autenticación (unauthorized, api_key_invalid, api_key_revoked, api_key_expired, api_key_owner_inactive, api_key_owner_not_admin).
Cabeceras: X-Request-Id · Content-Language · Idempotent-Replay
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í.
Cabeceras: X-Request-Id · Content-Language · Idempotent-Replay
Recurso no encontrado (not_found): no existe o está fuera del alcance de la clave de API.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Conflicto (conflict): el estado actual del recurso impide la operación, ya hay en curso una petición con esa Idempotency-Key, o otra escritura condicional (If-Match) retuvo el recurso durante más de cinco segundos. errors[0]. indica cuál: in_progress y lock_timeout se resuelven reintentando; invalid_state no, porque el estado del recurso prohíbe la operación.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Idempotency-Key reutilizada (idempotency_key_reused): la misma clave se usó antes con un cuerpo distinto. Cambia la clave.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Límite de peticiones superado (rate_limited): reintenta tras Retry-After segundos; RateLimit-* indica qué cuota se ha agotado.
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Retry-After · Idempotent-Replay
Error interno (internal_error).
Cabeceras: X-Request-Id · Content-Language · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · Idempotent-Replay
Errores
| Estado | Códigos | Significado |
|---|---|---|
| 400 | validation_error | Consulta o cuerpo mal formados. errors[] enumera cada campo erróneo con su código estable. |
| 404 | not_found | No existe o queda fuera del alcance de la clave de API. |
| 409 | conflict | El 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]. indica cuál: in_progress y lock_timeout se resuelven reintentando; invalid_state no, porque el estado del recurso prohíbe la operación. |
| 422 | idempotency_key_reused | La 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
¿Te ha resultado útil esta página?