Для AI-агентов: markdown этой страницы — /docs-content/entities/users/photo-delete.md индекс документации — /llms.txt

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

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

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

Параметры

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

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

Примеры

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

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

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

Terminal 
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 — Ошибки.

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

Идемпотентность. У сотрудника без фотографии вызов тоже отвечает 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 или PATCH /v1/users/:id.

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