Перейти к основному содержанию
Конечная точка «Обновление заказа» позволяет изменять существующий заказ (проект) в AgencyHandy — изменять его название, статус, бюджет, сроки, назначенных менеджеров и многое другое — из внешней системы или скрипта автоматизации. Конечная точка также поддерживает вложения файлов, которые добавляются в системную папку заказа.
Перед использованием этой конечной точки выполните руководство Начало работы для получения API-ключа и идентификатора компании.
Эта конечная точка использует Authorization: Bearer <token> (токен доступа вошедшего участника) вместо заголовка x-api-key. Убедитесь, что вызывающий объект аутентифицирован как утверждённый участник целевой компании. Неавторизованные вызывающие объекты получат ошибку 403 PermissionError.

​
Предварительные требования

  • ✅ Действительный Bearer-токен для утверждённого участника рабочего пространства
  • ✅ Идентификатор компании, полученный из GET {{URL}}/accounts/companies
  • ✅ Идентификатор заказа (идентификатор проекта, pid) заказа, который вы хотите обновить

​
Конечная точка

PUT {{URL}}/orders?pid=<ORDER_ID>
Content-Type: multipart/form-data — используйте это даже при отсутствии прикреплённых файлов, чтобы удовлетворить требования парсера multipart на сервере.

​
Заголовки

ЗаголовокОбязателенОписание
AuthorizationДаBearer <ACCESS_TOKEN> — токен доступа вошедшего участника.
companyidДаMongo ObjectId компании, которой принадлежит заказ.
clientidНеобязательноИдентификатор клиентского сокета в реальном времени. При указании уведомления включают его.

​
Параметры запроса

​
pid
string
обязательно
Идентификатор заказа / проекта для обновления. Передаётся как параметр строки запроса.

​
Поля тела запроса

​
name
string
Обновляет название заказа. Минимум 2 символа.
​
status
string
Новый статус заказа. Должен быть одним из: Pending, Ongoing, Review, Completed, Cancelled.Допустимые переходы:
  • Review может следовать только за Ongoing или другим Review. Переход из Pending напрямую в Review возвращает ошибку 400 ValidationError.
  • Заказы со статусом Completed или Cancelled не могут быть обновлены.
  • Клиенты не могут отменить заказ, вышедший из статуса Pending.
​
budget
number
Общая сумма бюджета. Должна быть ≥ 0. Использует существующую валюту заказа, если только currency не указан дополнительно.
​
currency
string
Код валюты для бюджета. Примеры: USD, CAD, EUR.
​
quantity
number
Количество единиц, приобретённых для пакета. Должно быть ≥ 1.
​
deadline
string
Строка даты в формате ISO 8601 для срока выполнения заказа. Пример: "2025-12-31T00:00:00.000Z".
​
kickoffDate
string
Строка даты в формате ISO 8601 для даты начала проекта.
​
notes
string
Внутренние заметки, видимые вашей команде.
​
brief
string
Бриф клиента или краткое описание проекта.
​
assignedProjectManagers
array
Полный список идентификаторов участников-менеджеров проекта для назначения на этот заказ. Новые идентификаторы добавляются в команду; удалённые идентификаторы исключаются. Каждый идентификатор должен принадлежать участнику с ролью projectManager в той же компании.
​
markTasksAsDone
boolean
Обязателен, когда status равен Completed или Cancelled. При true все задачи в заказе помечаются как выполненные после изменения статуса. При false задачи остаются в текущем состоянии.
​
rejectRequestedTasks
boolean
Допускается только при status равном Completed или Cancelled. При true все ожидающие задачи, запрошенные клиентом, отклоняются после обновления статуса.
​
repeatCount
number
Требуется только для заказов по подписке при изменении частоты повторения. Используйте вместе с repeatDuration.
​
repeatDuration
string
Требуется вместе с repeatCount для заказов по подписке. Одно из: day, week, month, year.
​
billingCycleCount
number
Необязательное ограничение на количество циклов выставления счетов. По умолчанию 0 (без ограничений).
​
billingCycleEvent
string
Порядок обработки каждого цикла выставления счетов. Одно из: createOrderWithTask, noChange.
​
files
file
Ноль или более вложений файлов. Файлы добавляются в системную папку заказа; существующие файлы никогда не перезаписываются. Используйте кодировку multipart/form-data и прикрепляйте каждый файл в поле files.

​
Пример запроса

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."
Эквивалентные данные в формате JSON (преобразуйте в записи multipart form при отправке файлов): 
{
  "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."
}

​
Ответы

HTTP-статусОписание
200 OKОбновление выполнено успешно.
400 ValidationErrorНеверный идентификатор заказа, недопустимый переход статуса или некорректные данные запроса. Ответ содержит fieldName при наличии.
403 PermissionErrorВызывающий объект не является утверждённым участником, не имеет роли в компании, подписка рабочего пространства истекла, или клиент попытался выполнить запрещённую отмену.
500 Internal Server ErrorНеобработанное исключение — проверьте журналы сервера.

​
Успешный ответ

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

​
Бизнес-правила и побочные эффекты

  • Переходы статусов ограничены. Review может следовать только за Ongoing или другим Review. Попытка перехода Pending → Review возвращает ошибку 400 ValidationError.
  • Переход статуса из Pending в Ongoing, Review или Completed активирует папку файлов заказа, делая загруженные файлы доступными для команды проекта.
  • Установка status в Completed или Cancelled требует явного указания markTasksAsDone со значением true или false.
  • Изменения статуса на Review, Completed или Cancelled автоматически инициируют уведомления для клиента:
    • Review — уведомляет клиента о необходимости проверки.
    • Completed — отправляет уведомление orderCompletion клиенту.
    • Cancelled — отправляет уведомление orderCancellation клиенту.
  • Каждое успешное обновление инициирует событие вебхука ORDER.UPDATED с обновлённым документом заказа и метаданными вложений, если у вас настроен активный вебхук, подписанный на это событие.