## Удалить фотографию сотрудника

`DELETE /v1/users/:id/personal-photo`

Снимает фотографию профиля сотрудника. Это единственная команда, которая её удаляет: запись поля `personalPhoto` на обновлении фотографию не снимает ни на одной поверхности. Операция **необратима** — Битрикс24 удаляет сам файл, поэтому повторная загрузка того же изображения даст новый идентификатор и новый URL. Требует прав администратора портала либо владения этим профилем — решение принимает Битрикс24.

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `id` (path) | number | да | ID сотрудника. Список: [`GET /v1/users`](/docs/entities/users/list) |

Тела у запроса нет.

## Примеры

### curl — личный ключ

```bash
curl -X DELETE "https://vibecode.bitrix24.tech/v1/users/1331/personal-photo" \
  -H "X-Api-Key: YOUR_API_KEY"
```

### curl — OAuth-приложение

```bash
curl -X DELETE "https://vibecode.bitrix24.tech/v1/users/1331/personal-photo" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

### JavaScript — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/users/1331/personal-photo', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
if (success && data.removed) {
  console.log(`Фотография сотрудника ${data.id} удалена`)
}
```

### JavaScript — OAuth-приложение

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/users/1331/personal-photo', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успешном удалении |
| `data.id` | number | ID сотрудника, у которого снята фотография |
| `data.personalPhoto` | null | Всегда `null` — состояние поля после вызова |
| `data.removed` | boolean | Всегда `true` — явный маркер семантики операции |
| `data.user` | object | Полная запись сотрудника после удаления. Поле отсутствует, если повторное чтение записи не сработало — фотография при этом удалена |

## Пример ответа

```json
{
  "success": true,
  "data": {
    "id": 1331,
    "personalPhoto": null,
    "removed": true,
    "user": {
      "id": 1331,
      "name": "Иван",
      "lastName": "Петров",
      "email": "ivan.petrov@example.com",
      "active": true,
      "workPosition": "Менеджер",
      "departmentId": [1]
    }
  }
}
```

## Пример ответа при ошибке

403 — Битрикс24 отказал в записи, фотография осталась на месте:

```json
{
  "success": false,
  "error": {
    "code": "UPDATE_FAILED",
    "message": "Bitrix24 rejected user.update for the photo removal (result: false)",
    "hint": "Bitrix24 returns false when the calling user lacks portal admin rights (a user may still edit their OWN profile), or when the target user id does not exist. The photo is unchanged."
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_ID` | `:id` не является положительным целым числом |
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `user` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ выдан в режиме только для чтения |
| 403 | `UPDATE_FAILED` | Битрикс24 вернул `result: false`. Так отвечает вызов по чужому профилю без прав администратора портала, а также вызов по несуществующему `:id`. Фотография не изменилась |
| 429 | `RATE_LIMITED` | Превышена частота запросов на стороне Битрикс24 |
| 429 | `OPERATION_TIME_LIMIT` | Битрикс24 приостановил этот метод для вашего ключа: исчерпан бюджет рабочего времени метода. Срок повтора приходит полем `error.retryAfter` и заголовком `Retry-After` |
| 429 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | Очередь запросов портала переполнена или запрос не дождался очереди. Заголовок `Retry-After` подсказывает задержку |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**Идемпотентность.** У сотрудника без фотографии вызов тоже отвечает `200` с `removed: true`. Проверять
наличие фотографии перед очисткой не нужно.

**Запись поля фотографию не снимает.** До этой команды пустая строка в `personalPhoto` доезжала до
Битрикс24 как приказ снять фотографию, и обновление отвечало успехом уже после удаления. Теперь
поведение поля на обновлении такое:

| Поверхность обновления | значение, из которого не собрать файл | `personalPhoto: null` |
|------------------------|--------------------------------------------|------------------------|
| `PATCH /v1/users/:id` | `400 INVALID_PARAMS` до вызова Битрикс24 | принимается, до ветки удаления не доходит, фотография остаётся |
| `POST /v1/users/batch` (`action: update`) | отклоняется с `400 BATCH_ITEM_VALIDATION`, весь пакет не отправлен | принимается, ключ не доезжает до Битрикс24, фотография остаётся |
| `POST /v1/batch` (`action: update`) | отклоняется с `INVALID_PARAMS` в `data.errors` этого подвызова | отклоняется с `INVALID_PARAMS` в `data.errors` этого подвызова |

Различие по `null` не случайность: причина в том, как каждая поверхность кодирует запрос. Одиночный `PATCH` отправляет тело JSON, где `null`
остаётся `null` и Битрикс24 его пропускает. Подзапрос пакета по одной сущности едет строкой запроса, и
кодировщик выбрасывает ключ с `null` целиком. Кодировщик общего пакета вместо этого пишет
`PERSONAL_PHOTO=`, то есть пустую строку — ту же команду снять фотографию, поэтому там `null`
отклоняется. Значение поля не удаляет фотографию ни на одной из трёх поверхностей — удаляет только эта
команда.

**Пакетные вызовы её не умеют.** Подвызов пакета адресуется парой «сущность плюс действие»
(`list`, `get`, `create`, `update`, `delete`, `fields`, `search`), и вложенного ресурса в этой форме не
выразить. Снимайте фотографию одиночным вызовом.

**Замена вместо удаления.** Чтобы поставить другую фотографию, удаление не нужно: отправьте пару
`[имя файла, base64]` в `personalPhoto` на [`POST /v1/users`](/docs/entities/users/create) или
[`PATCH /v1/users/:id`](/docs/entities/users/update).

## Смотрите также

- [Обновить сотрудника](/docs/entities/users/update)
- [Получить сотрудника](/docs/entities/users/get)
- [Деактивировать сотрудника](/docs/entities/users/delete)
- [Запрос и данные](/docs/errors/request)