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

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

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

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

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

Ограничения длины действуют для каждой части имени и документа отдельно. Общее ФИО после соединения частей — не более 300 символов.

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

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

{
  "last_name": "Иванов",
  "first_name": "Иван",
  "middle_name": "Иванович",
  "license_series": "77 15",
  "license_number": "123456",
  "passport_series": "4510",
  "passport_number": "123456",
  "comment": ""
}

{
  "last_name": "Иванов",
  "first_name": "Иван",
  "middle_name": "Иванович",
  "license_series": "77 15",
  "license_number": "123456",
  "passport_series": "4510",
  "passport_number": "123456",
  "comment": ""
}

curl --request PUT \
  --url "https://app.zaezdo.pro/api/v1/drivers/DRV-0017" \
  --header "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --header "Content-Type: application/json" \
  --data '{
  "last_name": "Иванов",
  "first_name": "Иван",
  "middle_name": "Иванович",
  "license_series": "77 15",
  "license_number": "123456",
  "passport_series": "4510",
  "passport_number": "123456",
  "comment": ""
}'

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

{
  "id": "DRV-EXAMPLE001",
  "source_id": "DRV-0017",
  "created": true,
  "is_active": true,
  "full_name": "Иванов Иван Иванович"
}

{
  "id": "DRV-EXAMPLE001",
  "source_id": "DRV-0017",
  "created": false,
  "is_active": true,
  "full_name": "Иванов Иван Иванович"
}

Для существующего 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. Повтор одинакового запроса не создаёт новую запись.

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

full_name формируется самим Заездо. В запросе передаются отдельные части имени. Длина собранного ФИО не должна превышать 300 символов.

Паспорт и водительское удостоверение необязательны. Передавайте серии и номера строками, чтобы сохранить ведущие нули. Телефоны и email этим методом не передаются.

Если заполнены серия и номер одного документа, их пара проверяется на совпадение с документом другого водителя. Сравнение выполняется без пробелов и без учёта регистра. Совпадение по любому из двух документов даёт 409.

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

Активность водителя сохраняется. Передача его сведений не создаёт права входа в Заездо и не назначает его ответственным менеджером.

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

После ошибки следующий этап не выполняется. Ошибки параметров 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[] возвращается:

При совпадении удостоверения field = license_number; при совпадении паспорта — passport_number. Если обнаружены оба конфликта, в errors[] возвращаются два элемента с одинаковым code и соответствующими field.

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

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

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

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

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

{
  "code": "VALIDATION_ERROR",
  "message": "Ошибка проверки данных справочника.",
  "errors": [
    {
      "field": "last_name",
      "code": "REQUIRED",
      "message": "Укажите фамилию водителя."
    },
    {
      "field": "first_name",
      "code": "REQUIRED",
      "message": "Укажите имя водителя."
    }
  ],
  "request_id": "req-drivers-validation"
}

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

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

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

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

Передайте водителя "DRV-0017" отдельным PUT-запросом. При 201 или 200 и is_active: true используйте "DRV-0017" в визите. Если водитель ещё не известен, его предварительная передача не требуется: driver_source_id можно опустить.

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

{
  "driver_source_id": "DRV-0017"
}

При уточнении документов или ФИО используйте тот же source_id и передайте полный набор сохраняемых полей. Если паспортные сведения не должны храниться, передайте passport_series: null и passport_number: null; остальные сохраняемые реквизиты повторите.