Contratos
Cancelar un contrato a efectos operativos
Da el contrato por no firmable: pasa su estado de FIRMA (operativeStatus) a cancelled y deja el documento vivo, con su número.
contracts:write- 120/min
- Ámbito estricto
- Idempotency-Key
- If-Match
- No reversible
- MCP: filmo_contracts_cancel
Ejemplos de petición
curl https://app.filmo.io/api/v1/contracts/cont_8f2a1c/cancel \
--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 '{
"reason": "El cliente se echa atrás antes de firmar"
}'Generado a partir del esquema
No reversible
Esta operación no se puede deshacer.
El motivo es opcional y se guarda en el historial. Un contrato YA FIRMADO no se puede cancelar —rechaza la petición—: para deshacer una firma hay que anular el documento con /void. cancelled es terminal: un contrato cancelado ya no se puede firmar. Devuelve el contrato completo, la misma proyección que su GET.
Autorizaciones
Clave de API como Bearer, con el permiso de abajo. contracts: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"
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
Identificador del contrato.
Límites: longitud mín. 1
Cuerpo
Esquema del cuerpo: ContractCancelBody
Motivo de la cancelación, que se guarda en el historial del contrato.
Límites: longitud mín. 1, longitud máx. 500
Respuesta
Respuesta correcta.
Esquema de la respuesta: ContractDto
Sobre: ContractResponse. meta. solo aparece cuando la operación está obsoleta.
Cabeceras: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag · Idempotent-Replay
Contrato de alquiler. No incluye las cláusulas legales ni la instantánea fiscal del cliente.
Mostrar atributos hijosOcultar atributos hijos
Identificador único del contrato.
Número del contrato, por ejemplo "C260001"; null mientras es un borrador.
Estado del documento.
Opciones disponibles: draft, validated, voided
Estado de la firma.
Opciones disponibles: pending, signed, cancelled
true si el contrato consta como firmado. Es lo que decide si el equipo puede salir.
Fecha de firma en ISO 8601 UTC; null si no está firmado.
Identificador del cliente; null en borradores sin cliente.
Pedido asociado; null si no tiene.
Número del pedido asociado; null si no tiene.
Proyecto asociado; null si no tiene.
Fecha del contrato en ISO 8601 UTC; null si no está definida.
Inicio de la vigencia en ISO 8601 UTC; null si no aplica.
Fin de la vigencia en ISO 8601 UTC; null si no aplica.
Importe total con impuestos como cadena decimal "1234.50"; null si no aplica.
Límites: patrón ^-?\d+\.\d{2}$
Fecha de creación en ISO 8601 UTC; null si no consta.
Fecha de la última modificación en ISO 8601 UTC; null si no está registrada.
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
Precondición fallida (precondition_failed): la etiqueta de entidad If-Match no coincide con la representación actual. Lee el recurso de nuevo y reintenta.
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. |
| 412 | precondition_failed | La etiqueta de entidad If-Match no coincide con la representación actual. Vuelve a leer el recurso y reintenta. |
| 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
Relacionado
Páginas relacionadas
Enlace a esta sección: Páginas relacionadasAlquileres
Contrato
Contrato de alquiler.
¿Te ha resultado útil esta página?