Planificador

Asignar un recurso a un servicio

Asigna a una persona o a un vehículo a un servicio.

POST
/api/v1/planner/assignments

Ejemplos de petición

curl https://app.filmo.io/api/v1/planner/assignments \
  --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 '{
  "orderId": "ord_0000421",
  "orderServiceId": "osv_0000912",
  "staffId": "stf_luis_perez",
  "role": "Conductor"
}'
{
  "data": {
    "status": "Example status",
    "conflictCount": 1
  }
}

Generado a partir del esquema

El destino es EXACTAMENTE uno: el par orderId + orderServiceId, una tarea o un servicio interno. El recurso, también exactamente uno. conflictCount indica con cuántos compromisos del recurso se solapa esta asignación: la asignación se hace igualmente, y tú decides qué hacer con el número. Responde 400 validation_error, con errors[].path en el campo, cuando staffId, vehicleId o el destino (orderServiceId, taskId, internalServiceId) no existe o pertenece a otra cuenta, cuando el destino no acepta ese tipo de recurso (una tarea solo acepta personal; un servicio, los tipos de recurso que declaran sus requisitos) y cuando la tarea no bloquea la disponibilidad; 409 conflict cuando el recurso ya está asignado a ese destino o no está disponible en ese periodo. En ninguno de esos casos se escribe nada.

Autorizaciones

Clave de API como Bearer, con el permiso de abajo. planner: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: PlannerAssignmentCreateBody

orderIdstring

Pedido al que está asociado el servicio.

orderServiceIdstring

Línea de servicio dentro de ese pedido. Va con orderId.

taskIdstring

Tarea del planificador a la que asignar el recurso.

internalServiceIdstring

Asignación interna que se va a cubrir.

staffIdstring

Miembro del personal que se asigna.

vehicleIdstring

Vehículo que se asigna.

rolestring

Rol con el que se asigna. P. ej.: "Conductor".

Respuesta

application/json

Respuesta correcta.

Esquema de la respuesta: PlannerAssignResultDto

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

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

dataobject

Resultado de asignar un recurso.

Mostrar atributos hijos
data.statusstring

Resultado de la operación.

data.conflictCountnumber

Compromisos del recurso que se solapan con esta asignación.

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