Создание или обновление автомобиля

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

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

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

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

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

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

{
  "make": "MAN",
  "model": "TGX",
  "plate_number": "А123ВС77",
  "comment": "Тягач"
}

{
  "make": "MAN",
  "model": "TGX",
  "plate_number": "А123ВС77",
  "comment": "Тягач"
}

curl --request PUT \
  --url "https://app.zaezdo.pro/api/v1/vehicles/VEH-0085" \
  --header "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --header "Content-Type: application/json" \
  --data '{
  "make": "MAN",
  "model": "TGX",
  "plate_number": "А123ВС77",
  "comment": "Тягач"
}'

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

{
  "id": "VEH-EXAMPLE001",
  "source_id": "VEH-0085",
  "created": true,
  "is_active": true
}

{
  "id": "VEH-EXAMPLE001",
  "source_id": "VEH-0085",
  "created": false,
  "is_active": true
}

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

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

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

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

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

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

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

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

Обновляются только make, model, plate_number и comment. Активность автомобиля сохраняется.

Госномер передаётся строкой. Для проверки совпадений из номера удаляются пробелы и буквы приводятся к верхнему регистру. Кириллические и латинские буквы автоматически не подменяются; передавайте единообразное написание.

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

Тип кузова, габариты, грузоподъёмность и привязка водителя в этот метод не входят. Автомобиль и водитель указываются отдельно при создании визита.

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

После ошибки следующий этап не выполняется. Ошибки параметров 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": "plate_number",
      "code": "VEHICLE_PLATE_CONFLICT",
      "message": "Автомобиль с указанным государственным номером уже существует, но не сопоставлен с переданным source_id."
    }
  ],
  "request_id": "req-vehicles-conflict"
}

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

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

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

{
  "code": "VALIDATION_ERROR",
  "message": "Ошибка проверки данных справочника.",
  "errors": [
    {
      "field": "make",
      "code": "REQUIRED",
      "message": "Укажите марку автомобиля."
    },
    {
      "field": "plate_number",
      "code": "REQUIRED",
      "message": "Укажите государственный номер автомобиля."
    }
  ],
  "request_id": "req-vehicles-validation"
}

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

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

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

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

Передайте автомобиль "VEH-0085" отдельным PUT-запросом. При 201 или 200 и is_active: true его идентификатор можно включить в visits. Если автомобиль пока неизвестен, этот PUT не выполняется, а vehicle_source_id в визите не передаётся.

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

{
  "vehicle_source_id": "VEH-0085"
}

Если реквизиты автомобиля изменились, отправьте новый полный набор полей с прежним source_id. Не заменяйте source_id государственным номером: номер может измениться, а соответствие записи должно сохраниться.