> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agencyhandy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API AgencyHandy: обновление существующего заказа через PUT
> Используйте API AgencyHandy для обновления данных заказа, изменения статуса, переназначения менеджеров проекта и прикрепления файлов к существующему заказу через PUT-запрос.
Конечная точка «Обновление заказа» позволяет изменять существующий заказ (проект) в AgencyHandy — изменять его название, статус, бюджет, сроки, назначенных менеджеров и многое другое — из внешней системы или скрипта автоматизации. Конечная точка также поддерживает вложения файлов, которые добавляются в системную папку заказа.
Перед использованием этой конечной точки выполните руководство [Начало работы](/ru/api/getting-started) для получения API-ключа и идентификатора компании.
Эта конечная точка использует `Authorization: Bearer ` (токен доступа вошедшего участника) вместо заголовка `x-api-key`. Убедитесь, что вызывающий объект аутентифицирован как **утверждённый участник** целевой компании. Неавторизованные вызывающие объекты получат ошибку `403 PermissionError`.
## Предварительные требования
* ✅ Действительный **Bearer-токен** для утверждённого участника рабочего пространства
* ✅ **Идентификатор компании**, полученный из `GET {{URL}}/accounts/companies`
* ✅ **Идентификатор заказа** (идентификатор проекта, `pid`) заказа, который вы хотите обновить
***
## Конечная точка
```
PUT {{URL}}/orders?pid=
```
**Content-Type:** `multipart/form-data` — используйте это даже при отсутствии прикреплённых файлов, чтобы удовлетворить требования парсера multipart на сервере.
## Заголовки
| Заголовок | Обязателен | Описание |
| --------------- | ------------- | ------------------------------------------------------------------------------------------- |
| `Authorization` | Да | `Bearer ` — токен доступа вошедшего участника. |
| `companyid` | Да | Mongo ObjectId компании, которой принадлежит заказ. |
| `clientid` | Необязательно | Идентификатор клиентского сокета в реальном времени. При указании уведомления включают его. |
## Параметры запроса
Идентификатор заказа / проекта для обновления. Передаётся как параметр строки запроса.
## Поля тела запроса
Обновляет название заказа. Минимум 2 символа.
Новый статус заказа. Должен быть одним из: `Pending`, `Ongoing`, `Review`, `Completed`, `Cancelled`.
**Допустимые переходы:**
* `Review` может следовать только за `Ongoing` или другим `Review`. Переход из `Pending` напрямую в `Review` возвращает ошибку `400 ValidationError`.
* Заказы со статусом `Completed` или `Cancelled` не могут быть обновлены.
* Клиенты не могут отменить заказ, вышедший из статуса `Pending`.
Общая сумма бюджета. Должна быть `≥ 0`. Использует существующую валюту заказа, если только `currency` не указан дополнительно.
Код валюты для бюджета. Примеры: `USD`, `CAD`, `EUR`.
Количество единиц, приобретённых для пакета. Должно быть `≥ 1`.
Строка даты в формате ISO 8601 для срока выполнения заказа. Пример: `"2025-12-31T00:00:00.000Z"`.
Строка даты в формате ISO 8601 для даты начала проекта.
Внутренние заметки, видимые вашей команде.
Бриф клиента или краткое описание проекта.
Полный список идентификаторов участников-менеджеров проекта для назначения на этот заказ. Новые идентификаторы добавляются в команду; удалённые идентификаторы исключаются. Каждый идентификатор должен принадлежать участнику с ролью `projectManager` в той же компании.
**Обязателен**, когда `status` равен `Completed` или `Cancelled`. При `true` все задачи в заказе помечаются как выполненные после изменения статуса. При `false` задачи остаются в текущем состоянии.
Допускается только при `status` равном `Completed` или `Cancelled`. При `true` все ожидающие задачи, запрошенные клиентом, отклоняются после обновления статуса.
Требуется только для заказов по **подписке** при изменении частоты повторения. Используйте вместе с `repeatDuration`.
Требуется вместе с `repeatCount` для заказов по подписке. Одно из: `day`, `week`, `month`, `year`.
Необязательное ограничение на количество циклов выставления счетов. По умолчанию `0` (без ограничений).
Порядок обработки каждого цикла выставления счетов. Одно из: `createOrderWithTask`, `noChange`.
Ноль или более вложений файлов. Файлы добавляются в системную папку заказа; существующие файлы никогда не перезаписываются. Используйте кодировку `multipart/form-data` и прикрепляйте каждый файл в поле `files`.
***
## Пример запроса
```bash cURL (no files) theme={null}
curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
--header "Authorization: Bearer " \
--header "companyid: " \
--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."
```
```bash cURL (with file) theme={null}
curl --request PUT "https://api.agencyhandy.com/orders?pid=ORDER_ID_HERE" \
--header "Authorization: Bearer " \
--header "companyid: " \
--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"
```
**Эквивалентные данные в формате JSON** (преобразуйте в записи multipart form при отправке файлов):
```json theme={null}
{
"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` | Необработанное исключение — проверьте журналы сервера. |
### Успешный ответ
```json theme={null}
{
"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` с обновлённым документом заказа и метаданными вложений, если у вас настроен активный вебхук, подписанный на это событие.