API de AgencyHandy: actualizar un pedido existente con PUT

El endpoint Update Order le permite modificar un pedido (proyecto) existente en AgencyHandy — cambiar su nombre, estado, presupuesto, cronograma, gestores asignados y más — todo desde un sistema externo o un script de automatización. El endpoint también admite archivos adjuntos, que se agregan a la carpeta del sistema del pedido.

Antes de usar este endpoint, complete la guía Getting Started para obtener su clave de API y su Company ID.

Este endpoint usa Authorization: Bearer <token> (el token de acceso de un miembro con sesión iniciada) en lugar de solo el encabezado x-api-key. Asegúrese de que quien realiza la llamada esté autenticado como un miembro aprobado de la empresa de destino. Las llamadas no autorizadas reciben un 403 PermissionError.

Requisitos previos

✅ Un Bearer token válido de un miembro aprobado del espacio de trabajo
✅ Company ID obtenido de GET {{URL}}/accounts/companies
✅ El Order ID (Project ID, pid) del pedido que desea actualizar

Endpoint

PUT {{URL}}/orders?pid=<ORDER_ID>

Content-Type: multipart/form-data — úselo incluso cuando no se adjunten archivos para satisfacer el analizador multipart del servidor.

Encabezados

Encabezado	Requerido	Descripción
`Authorization`	Sí	`Bearer <ACCESS_TOKEN>` — el token de acceso del miembro con sesión iniciada.
`companyid`	Sí	El ObjectId de Mongo de la empresa a la que pertenece el pedido.
`clientid`	Opcional	El ID del socket del cliente en tiempo real. Cuando se proporciona, las notificaciones lo incluyen.

Parámetros de consulta

string

requerido

El Order / Project ID que se va a actualizar. Páselo como parámetro de la cadena de consulta.

Campos del cuerpo de la solicitud

string

Actualiza el título del pedido. Mínimo 2 caracteres.

string

Nuevo estado para el pedido. Debe ser uno de: Pending, Ongoing, Review, Completed, Cancelled.Transiciones permitidas:

Review solo puede seguir a Ongoing o a otro Review. Pasar de Pending directamente a Review devuelve un 400 ValidationError.
Los pedidos que ya están en Completed o Cancelled no pueden actualizarse.
Los clientes no pueden cancelar un pedido que ha avanzado más allá de Pending.

number

Cifra total del presupuesto. Debe ser ≥ 0. Usa la moneda existente del pedido a menos que también se proporcione currency.

string

Código de moneda para el presupuesto. Ejemplos: USD, CAD, EUR.

number

Número de unidades adquiridas del paquete. Debe ser ≥ 1.

string

Cadena de fecha ISO 8601 para la fecha de vencimiento del pedido. Ejemplo: "2025-12-31T00:00:00.000Z".

string

Cadena de fecha ISO 8601 para la fecha de inicio del proyecto.

string

Notas internas visibles para su equipo.

string

Brief del cliente o resumen del proyecto.

array

Lista completa de los IDs de los miembros gestores de proyecto que se asignarán a este pedido. Los IDs nuevos se añaden al equipo; los IDs eliminados se borran. Cada ID debe pertenecer a un miembro con un rol projectManager dentro de la misma empresa.

boolean

Requerido cuando status es Completed o Cancelled. Cuando es true, todas las tareas del pedido se marcan como hechas después del cambio de estado. Cuando es false, las tareas permanecen en su estado actual.

boolean

Permitido solo cuando status es Completed o Cancelled. Cuando es true, todas las tareas pendientes solicitadas por el cliente se rechazan después de la actualización del estado.

number

Requerido solo para pedidos de suscripción al cambiar la frecuencia de recurrencia. Combínelo con repeatDuration.

string

Requerido junto con repeatCount para los pedidos de suscripción. Uno de: day, week, month, year.

number

Límite opcional sobre los ciclos de facturación recurrentes. Por defecto es 0 (sin límite).

string

Cómo se gestiona cada ciclo de facturación. Uno de: createOrderWithTask, noChange.

file

Cero o más archivos adjuntos. Los archivos se agregan a la carpeta del sistema del pedido; los archivos existentes nunca se sobrescriben. Use la codificación multipart/form-data y adjunte cada archivo bajo el campo files.

Solicitud de ejemplo

curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "companyid: <COMPANY_ID>" \
  --form "name=Website Redesign" \
  --form "status=Review" \
  --form "budget=12000" \
  --form "currency=USD" \
  --form "quantity=1" \
  --form "assignedProjectManagers[]=PROJECT_MANAGER_ID" \
  --form "notes=Scope finalized with client." \
  --form "brief=Launch-ready design refresh."

curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
  --header "Authorization: Bearer <ACCESS_TOKEN>" \
  --header "companyid: <COMPANY_ID>" \
  --form "name=Website Redesign" \
  --form "status=Review" \
  --form "budget=12000" \
  --form "repeatCount=3" \
  --form "repeatDuration=month" \
  --form "billingCycleEvent=createOrderWithTask" \
  --form "files=@/path/to/creative-brief.pdf"

Carga útil JSON equivalente (conviértala en entradas de formulario multipart al enviar archivos):

{
  "name": "Website Redesign",
  "status": "Review",
  "budget": 12000,
  "currency": "USD",
  "quantity": 1,
  "assignedProjectManagers": ["{{PROJECT_MANAGER_ID}}"],
  "repeatCount": 3,
  "repeatDuration": "month",
  "billingCycleEvent": "createOrderWithTask",
  "notes": "Scope finalized with client.",
  "brief": "Launch-ready design refresh."
}

Respuestas

Estado HTTP	Descripción
`200 OK`	La actualización se realizó correctamente.
`400 ValidationError`	ID de pedido no válido, transición de estado bloqueada o carga útil mal formada. La respuesta incluye `fieldName` cuando corresponde.
`403 PermissionError`	Quien realiza la llamada no es un miembro aprobado, carece del rol de la empresa, la suscripción del espacio de trabajo ha caducado o un cliente intentó una cancelación prohibida.
`500 Internal Server Error`	Excepción no controlada — revise los registros del servidor.

Respuesta de éxito

{
  "message": "Project has been updated"
}

Reglas de negocio y efectos secundarios

Las transiciones de estado están restringidas. Review solo puede seguir a Ongoing o a otro Review. Intentar Pending → Review devuelve 400 ValidationError.
Cambiar un estado de Pending a Ongoing, Review o Completed activa la carpeta de archivos del pedido para que los archivos cargados sean accesibles para el equipo del proyecto.
Establecer status en Completed o Cancelled requiere que markTasksAsDone se establezca explícitamente en true o false.
Los cambios de estado a Review, Completed o Cancelled activan automáticamente notificaciones al cliente:
- Review — notifica al cliente que se necesita una revisión.
- Completed — envía la notificación orderCompletion al cliente.
- Cancelled — envía la notificación orderCancellation al cliente.
Cada actualización exitosa dispara un evento de webhook ORDER.UPDATED con el documento del pedido actualizado y los metadatos de los adjuntos, si tiene un webhook activo suscrito a ese evento.

Introducción

Endpoints

API de AgencyHandy: actualizar un pedido existente con PUT

Requisitos previos

Endpoint

Encabezados

Parámetros de consulta

Campos del cuerpo de la solicitud

Solicitud de ejemplo

Respuestas

Respuesta de éxito

Reglas de negocio y efectos secundarios

​Requisitos previos

​Endpoint

​Encabezados

​Parámetros de consulta

​Campos del cuerpo de la solicitud

​Solicitud de ejemplo

​Respuestas

​Respuesta de éxito

​Reglas de negocio y efectos secundarios

Requisitos previos

Endpoint

Encabezados

Parámetros de consulta

Campos del cuerpo de la solicitud

Solicitud de ejemplo

Respuestas

Respuesta de éxito

Reglas de negocio y efectos secundarios