Создание визита

Подготовка к созданию визита#

• Справочники предварительно синхронизируются отдельными PUT-методами. Создание визита не создаёт и не обновляет вложенные сущности.
• Площадка и контрагент должны существовать и быть активными. Автомобиль и водитель необязательны, но если переданы — тоже должны быть найдены и активны.
• Ответственный обязателен: пользователь активен, имеет действующую учётную запись, роль MANAGER и доступ менеджера к указанной площадке.
• Метод проверяет, может ли указанный пользователь быть ответственным за визит на выбранной площадке.
• Отсутствие настроенных мест обслуживания, зон ожидания, сотрудников КПП и табло само по себе не блокирует создание визита.
• Если запрос отклонён при проверке, визит не создаётся. Ранее созданные справочники остаются без изменений.
• Начальный статус — PLANNED («Запланирован»); допуск определяется правилами площадки.

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

Передайте внешние идентификаторы заранее подготовленных площадки, контрагента и, если используются, автомобиля и водителя. Ответственного сопоставьте в карточке пользователя через поле «Идентификатор для синхронизации с 1С».

Тело запроса передается в формате JSON. В *_source_id передаются идентификаторы из внешней системы.

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

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

{
  "external_id": "ТД00-000015",
  "site_source_id": "WH-SEVER",
  "planned_arrival_at": "2026-11-03 10:30",
  "purpose": "UNLOADING",
  "counterparty_source_id": "CP-0042",
  "responsible_user_source_id": "AfoninGA",
  "vehicle_source_id": "VEH-0085",
  "driver_source_id": "DRV-0017",
  "basis": "Поставка по заявке №123"
}

{
  "external_id": "ТД00-000015",
  "site_source_id": "WH-SEVER",
  "planned_arrival_at": "2026-11-03 10:30",
  "purpose": "UNLOADING",
  "counterparty_source_id": "CP-0042",
  "responsible_user_source_id": "AfoninGA",
  "vehicle_source_id": "VEH-0085",
  "driver_source_id": "DRV-0017",
  "basis": "Поставка по заявке №123"
}

curl --request POST \
  --url "https://app.zaezdo.pro/api/v1/visits" \
  --header "Authorization: Bearer ВАШ_API_ТОКЕН" \
  --header "Content-Type: application/json" \
  --data '{
  "external_id": "ТД00-000015",
  "site_source_id": "WH-SEVER",
  "planned_arrival_at": "2026-11-03 10:30",
  "purpose": "UNLOADING",
  "counterparty_source_id": "CP-0042",
  "responsible_user_source_id": "AfoninGA",
  "vehicle_source_id": "VEH-0085",
  "driver_source_id": "DRV-0017",
  "basis": "Поставка по заявке №123"
}'

vehicle_source_id и driver_source_id можно не передавать. Если они указаны, соответствующие автомобиль и водитель должны существовать и быть активны.

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

{
  "id": "VST-EXAMPLE001",
  "external_id": "ТД00-000015",
  "created": true,
  "status": "PLANNED",
  "admission_status": "UNDEFINED"
}

{
  "id": "VST-EXAMPLE001",
  "external_id": "ТД00-000015",
  "created": false,
  "status": "PLANNED",
  "admission_status": "UNDEFINED"
}

При первом создании визита status = PLANNED («Запланирован»). Значение admission_status зависит от поля «Допуск на площадку» в карточке площадки: UNDEFINED («Не определён») при режиме «Требует ручной проверки»; ALLOWED («Разрешён») при режиме «Разрешен при наличии сведений».

Поля ответа и допуск

ДОПУСТИМЫЕ ЗНАЧЕНИЯ ADMISSION_STATUS

После создания визита статус допуска может изменяться по действующим правилам Заездо; повторный запрос возвращает актуальный статус существующего визита.

Повторная отправка визита#

Один external_id обозначает один визит вашей внешней системы. При потере ответа повторяйте исходный запрос без изменения external_id и его данных.

Для повтора сравниваются первоначально переданные данные, а не текущая карточка визита после ручного редактирования. Успешный повтор возвращает актуальные статусы существующего визита.

Проверка повтора выполняется до поиска справочников и проверки возможности нового создания. Поэтому запрос, по которому визит уже создан, не становится ошибочным только из-за наступившего планового времени или последующего изменения справочников.

HTTP 409 · EXTERNAL_ID УЖЕ ИСПОЛЬЗОВАН С ДРУГИМИ ДАННЫМИ

{
  "code": "VISIT_ALREADY_EXISTS",
  "message": "Визит с указанным external_id уже существует с другими исходными данными.",
  "request_id": "req-example-conflict"
}

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

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

Запрос проходит этапы в порядке, указанном ниже. При ошибке возвращается HTTP-статус соответствующего этапа; последующие этапы не выполняются.

Обработка прекращается на первом этапе с ошибками. В errors[] перечисляются все обнаруженные ошибки только этого этапа. Ошибки поиска и проверки возможности создания не смешиваются в одном ответе.

Когда возвращается 404, а когда 422

404 — идентификатор передан корректно, но запись по нему не найдена. 422 — нужно исправить данные запроса либо условия, при которых допускается создание визита.

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

Конкретные причины HTTP 404 и 422 перечисляются в errors[]. Возвращаются все независимые ошибки того этапа, на котором остановилась проверка.

Ниже приведены точные значения code и message. Подробности ошибок 404 и 422 находятся в массиве errors[].

RESOURCE_NOT_FOUND относится к площадке, контрагенту, ответственному пользователю, автомобилю или водителю, указанным в запросе. Он не означает отсутствие создаваемого визита.

Условия возникновения ошибок

Каждая строка задаёт одну ошибку: field — параметр запроса; code — её машинный код; message — точный текст. Если на этапе найдено несколько независимых ошибок, они возвращаются отдельными элементами errors[].

Параметры запроса · HTTP 422

На этом этапе не выполняются поиск записей, проверка их активности и прав менеджера. Для planned_arrival_at проверяются наличие и корректность даты и времени в формате ГГГГ-ММ-ДД ЧЧ:ММ, но не наступление указанного времени.

Необязательные параметры vehicle_source_id, driver_source_id и basis можно не передавать. Для переданных значений действуют ограничения из таблицы.

Поиск записей справочников · HTTP 404

Поиск начинается после успешной проверки параметров и отсутствия ранее выполненного запроса с тем же external_id. Все переданные идентификаторы проверяются независимо.

Автомобиль и водитель ищутся только при наличии vehicle_source_id и driver_source_id. Отключённая запись считается найденной. Если хотя бы одна запись не найдена, возвращается 404; проверка возможности создания в этом запросе не выполняется.

Возможность создания визита · HTTP 422

Этот этап выполняется, только когда все указанные площадка, контрагент, ответственный пользователь, автомобиль и водитель найдены. В ответ включаются все независимые нарушения этого этапа.

Если у сотрудника вообще нет роли MANAGER, возвращается MANAGER_NOT_MANAGER; MANAGER_NO_SITE_ACCESS применяется, когда роль менеджера есть, но не действует на площадке визита.

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

В HTTP 404 и 422 возвращается один ответ с непустым массивом errors[]. Один ненайденный объект или одна ошибка — один элемент; несколько — несколько элементов. Верхнеуровневый код при этом не меняется.

HTTP 404 · НЕ НАЙДЕНЫ ПЛОЩАДКА И КОНТРАГЕНТ

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "Не найдены записи по переданным идентификаторам.",
  "errors": [
    {
      "field": "site_source_id",
      "code": "SITE_NOT_FOUND",
      "message": "Площадка с указанным site_source_id не найдена."
    },
    {
      "field": "counterparty_source_id",
      "code": "COUNTERPARTY_NOT_FOUND",
      "message": "Контрагент с указанным counterparty_source_id не найден."
    }
  ],
  "request_id": "req-example-404"
}

Примеры HTTP 422

ЭТАП ПАРАМЕТРОВ · НЕ УКАЗАНА ПЛОЩАДКА И НЕВЕРНАЯ ЦЕЛЬ

{
  "code": "VALIDATION_ERROR",
  "message": "Ошибка проверки данных визита.",
  "errors": [
    {
      "field": "site_source_id",
      "code": "REQUIRED",
      "message": "Укажите идентификатор площадки."
    },
    {
      "field": "purpose",
      "code": "INVALID_PURPOSE",
      "message": "Допустимые значения цели визита: LOADING, UNLOADING, SERVICE, OTHER."
    }
  ],
  "request_id": "req-example-format"
}

Поиск справочников не выполнялся. После исправления параметров запрос нужно отправить заново.

ЭТАП ВОЗМОЖНОСТИ СОЗДАНИЯ · ПЛОЩАДКА ОТКЛЮЧЕНА И ВРЕМЯ ПРОШЛО

{
  "code": "VALIDATION_ERROR",
  "message": "Ошибка проверки данных визита.",
  "errors": [
    {
      "field": "site_source_id",
      "code": "SITE_INACTIVE",
      "message": "Площадка отключена."
    },
    {
      "field": "planned_arrival_at",
      "code": "ARRIVAL_IN_PAST",
      "message": "Плановое время прибытия не может быть в прошлом."
    }
  ],
  "request_id": "req-example-rules"
}

Все переданные записи найдены. Визит не создан из-за перечисленных ограничений.

Что делать во внешней системе

Проверяйте HTTP-статус и code. Если ответ содержит errors[], обрабатывайте каждый элемент по field и code и показывайте пользователю все errors[].message. Если errors[] отсутствует, показывайте общий message.

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

Задача: передать из 1С заявку на разгрузку на складе "WH-SEVER" на 3 ноября 2026 года, 10:30. У контрагента "CP-0042" ответственным назначен менеджер "AfoninGA". Идентификатор заявки — "ТД00-000015".

Шаг 1. Подготовьте доступ и данные

Получите API-токен в настройках интеграции Заездо. Во всех запросах ниже замените ВАШ_API_ТОКЕН его значением. Запросы отправляются по HTTPS на app.zaezdo.pro.

До создания визита передайте справочники отдельными методами. Для примера используются следующие идентификаторы:

В теле каждого PUT-запроса передаются данные соответствующего справочника. Дождитесь успешного ответа 201 или 200. Если автомобиль или водитель пока неизвестен, пропустите их подготовку и не включайте их идентификаторы в запрос визита.

В карточке нужного пользователя Заездо вручную укажите "AfoninGA" в поле «Идентификатор для синхронизации с 1С». Пользователь должен быть активен, иметь действующую учётную запись и роль «Менеджер» на площадке "WH-SEVER".

В 1С закрепите external_id = "ТД00-000015" за этой заявкой до отправки визита. При повторной отправке той же заявки идентификатор не меняйте.

Шаг 2. Проверьте ответственного

GET /api/v1/users/AfoninGA?site_source_id=WH-SEVER HTTP/1.1
Host: app.zaezdo.pro
Authorization: Bearer ВАШ_API_ТОКЕН
Accept: application/json

Тело запроса не передаётся. В ответе HTTP 200 проверьте поле can_be_responsible_for_site.allowed. Для продолжения его значение должно быть true.

Шаг 3. Отправьте запрос создания визита

Сформируйте JSON из данных заявки 1С. Дата передаётся в формате ГГГГ-ММ-ДД ЧЧ:ММ.

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

{
  "external_id": "ТД00-000015",
  "site_source_id": "WH-SEVER",
  "planned_arrival_at": "2026-11-03 10:30",
  "purpose": "UNLOADING",
  "counterparty_source_id": "CP-0042",
  "responsible_user_source_id": "AfoninGA",
  "vehicle_source_id": "VEH-0085",
  "driver_source_id": "DRV-0017",
  "basis": "Поставка по заявке №123"
}

Шаг 4. Сохраните результат в 1С

УСПЕШНОЕ СОЗДАНИЕ · HTTP 201 CREATED

{
  "id": "VST-EXAMPLE001",
  "external_id": "ТД00-000015",
  "created": true,
  "status": "PLANNED",
  "admission_status": "UNDEFINED"
}

Найдите в 1С заявку по external_id = "ТД00-000015". При необходимости сохраните для неё id = "VST-EXAMPLE001" и отметьте успешную передачу. PLANNED означает «Запланирован», UNDEFINED — «Не определён»: визит создан, но допуск на площадку ещё не разрешён. Дальнейшее управление допуском предполагается на стороне Заездо.

Если запрос не завершился успешно

Если users вернул allowed: false, устраните причину из reason до отправки визита. При ошибке POST обработайте все элементы errors[] согласно блоку «Что делать во внешней системе» на этой странице; не отмечайте заявку как успешно переданную.

Если ответ POST потерян, повторите тот же запрос с тем же external_id и теми же данными. Ответ 200 с created: false означает, что визит уже создан: сохраните возвращённый id без создания новой заявки.