Создание или обновление площадки

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

Отправьте полный набор реквизитов записи. По новому source_id метод создаст запись; по существующему — обновит её. В каждом запросе передавайте API-токен в заголовке Authorization.

Адрес: https://app.zaezdo.pro/api/v1/sites/{source_id}. Параметр source_id обязателен, передаётся в пути URL; ограничения указаны в таблице ниже. Query-параметры не используются.

Тело запроса — объект JSON. В таблице ниже перечислены поля тела запроса; они передаются как при создании, так и при обновлении.

Если admission_mode (реквизит «Допуск на площадку») передан, он должен содержать одно из двух указанных строковых значений. null, пустая строка или другое значение приводят к ошибке 422 INVALID_ADMISSION_MODE.

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

PUT /api/v1/sites/WH-SEVER HTTP/1.1
Host: app.zaezdo.pro
Authorization: Bearer ВАШ_API_ТОКЕН
Content-Type: application/json

{
  "name": "Склад Север",
  "code": "СКЛ-000042",
  "address": "Москва, Складская улица, 15",
  "comment": "Основной склад",
  "admission_mode": "MANUAL_REVIEW"
}

{
  "name": "Склад Север",
  "code": "СКЛ-000042",
  "address": "Москва, Складская улица, 15",
  "comment": "Основной склад",
  "admission_mode": "MANUAL_REVIEW"
}

curl --request PUT \
  --url "https://app.zaezdo.pro/api/v1/sites/WH-SEVER" \
  --header "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --header "Content-Type: application/json" \
  --data '{
  "name": "Склад Север",
  "code": "СКЛ-000042",
  "address": "Москва, Складская улица, 15",
  "comment": "Основной склад",
  "admission_mode": "MANUAL_REVIEW"
}'

Чтобы выбрать режим «Разрешен при наличии сведений», передайте в теле JSON "admission_mode": "AUTO_IF_DATA_PRESENT".

Успешные ответы#

{
  "id": "SITE-EXAMPLE001",
  "source_id": "WH-SEVER",
  "created": true,
  "is_active": true,
  "admission_mode": "MANUAL_REVIEW"
}

{
  "id": "SITE-EXAMPLE001",
  "source_id": "WH-SEVER",
  "created": false,
  "is_active": true,
  "admission_mode": "MANUAL_REVIEW"
}

Для существующего source_id возвращается HTTP 200 с тем же набором полей и created: false. Значение id сохраняется, остальные поля отражают результат операции. Если данные не изменились, ответ также 200 и created: false.

Создание, обновление и повторы#

PUT передаёт полное состояние полей, перечисленных в описании метода. При повторе с тем же source_id данные этих полей заменяются значениями из запроса. Поэтому в каждом запросе передавайте все значения, которые нужно сохранить.

Для обычных строк убираются пробелы по краям; пустая строка после этого считается незаполненным значением. Для source_id пробелы не исправляются автоматически. Необязательные поля принимают строку или null; у обязательных полей тип — string. Исключение — admission_mode метода sites: правила его передачи приведены в разделе 5.1.

Активность и повторные запросы

Новая запись активна. При обновлении сохраняется её текущая активность: отключённая запись автоматически не включается. Поле is_active возвращается в ответе, но не принимается для изменения через PUT. Настройки, не входящие в метод, остаются без изменений.

Первая запись возвращает 201 и created: true. Обновление или повтор — 200 и created: false. Повтор одинакового запроса не создаёт новую запись.

Правила для этого справочника

При каждом PUT поле «Допуск на площадку» устанавливается по admission_mode из тела JSON. Если поле отсутствует, выбирается «Требует ручной проверки» (MANUAL_REVIEW), в том числе при обновлении. Новая площадка сразу активна; отдельного подтверждения создания не требуется.

Повторный PUT обновляет name, code, address, comment и admission_mode. При этом он не меняет активность, права сотрудников, зоны ожидания, места обслуживания или табло.

Название и адрес не используются для автоматического объединения площадок. Если code заполнен, совпадение кода с другой площадкой вызывает 409. Сравнивается код после удаления пробелов по краям; регистр символов учитывается. Если code не передан, сопоставление выполняется только по source_id.

Площадку можно использовать в visits сразу после успешного создания, если ответственный менеджер имеет к ней доступ. PUT не назначает сотрудников и не выдаёт им права.

Порядок проверки запроса#

После ошибки следующий этап не выполняется. Ошибки параметров 422 и конфликты 409 не смешиваются. Отсутствие записи по source_id не даёт 404: это штатный случай создания.

Коды и описания ошибок#

При HTTP 409 и 422 конкретные причины возвращаются в errors[]. Ниже приведены все коды этого метода и точные тексты сообщений.

Для BODY_MUST_BE_OBJECT поле field содержит "$" — весь JSON. Для UNKNOWN_FIELD в field возвращается фактически переданное лишнее имя, например is_active.

REQUIRED возвращается, когда обязательного поля нет либо оно равно null или пустой строке. Если поле заполнено, но имеет неверный тип или длину, возвращается соответствующий код INVALID_… . Две ошибки об одном и том же нарушении не дублируются.

Как разрешить конфликт 409

Если другая запись имеет те же реквизиты, по которым проверяются совпадения, метод не объединяет записи автоматически и не меняет их source_id. Критерии совпадения указаны для каждого справочника. Отключённые записи участвуют в проверке конфликтов.

Верхнеуровневый код — RESOURCE_CONFLICT; сообщение — «Невозможно сохранить запись из-за конфликта данных.». В errors[] возвращается:

ПРИМЕР ОТВЕТА · HTTP 409

{
  "code": "RESOURCE_CONFLICT",
  "message": "Невозможно сохранить запись из-за конфликта данных.",
  "errors": [
    {
      "field": "code",
      "code": "SITE_CODE_CONFLICT",
      "message": "Площадка с указанным кодом уже существует, но не сопоставлена с переданным source_id."
    }
  ],
  "request_id": "req-sites-conflict"
}

1. Проверьте, не существует ли соответствующая запись в справочнике Заездо.
2. Если запись существует и соответствует объекту внешней системы, укажите в её карточке правильный «Идентификатор для синхронизации с 1С».
3. Повторите исходный PUT-запрос с тем же source_id.

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

HTTP 422 · НЕСКОЛЬКО ОШИБОК В ОДНОМ ОТВЕТЕ

{
  "code": "VALIDATION_ERROR",
  "message": "Ошибка проверки данных справочника.",
  "errors": [
    {
      "field": "name",
      "code": "REQUIRED",
      "message": "Укажите наименование площадки."
    },
    {
      "field": "address",
      "code": "INVALID_ADDRESS",
      "message": "Адрес площадки должен быть строкой длиной не более 500 символов или null."
    }
  ],
  "request_id": "req-sites-validation"
}

Покажите все errors[].message, исправьте перечисленные поля и повторите PUT с тем же source_id. При 409 сначала разрешите конфликт; при 500, 503 или потере ответа повторяйте прежний запрос после паузы.

Повтор после временной ошибки

При 429 учитывайте Retry-After. При 500, 503 или потере ответа повторите тот же PUT после паузы. Если вместо JSON получен ответ сетевого шлюза, ориентируйтесь на HTTP-статус; request_id в таком ответе может отсутствовать.

Пример использования для 1С#

В 1С закрепите "WH-SEVER" за складом «Склад Север». Выполните PUT с наименованием и актуальными реквизитами. При необходимости укажите admission_mode в теле JSON. После 201 или 200 и is_active: true используйте "WH-SEVER" при создании визитов. Если is_active: false, площадка остаётся отключённой; её нужно активировать в Заездо.

ФРАГМЕНТ ЗАПРОСА POST /api/v1/visits

{
  "site_source_id": "WH-SEVER"
}

При переименовании склада отправьте тот же PUT с новым name и полным набором остальных сохраняемых полей. Используйте тот же source_id. Чтобы сохранить режим допуска, отличный от «Требует ручной проверки», снова передайте соответствующий admission_mode в теле JSON.