{ "openapi": "3.1.0", "info": { "title": "Заездо API", "version": "1", "description": "API для подключения внешних систем, подготовки справочников и создания визитов." }, "servers": [ { "url": "https://app.zaezdo.pro/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "ping", "description": "Проверка подключения" }, { "name": "users", "description": "Получение пользователя" }, { "name": "sites", "description": "Создание или обновление площадки" }, { "name": "counterparties", "description": "Создание или обновление контрагента" }, { "name": "vehicles", "description": "Создание или обновление автомобиля" }, { "name": "drivers", "description": "Создание или обновление водителя" }, { "name": "visits", "description": "Создание визита" } ], "paths": { "/ping": { "get": { "operationId": "ping", "summary": "Проверка подключения", "description": "Проверка токена интеграции и доступности API Заездо. Успешный ответ подтверждает, что запрос авторизован. Метод не создаёт визиты и не открывает отдельный сеанс подключения.", "tags": [ "ping" ], "x-docs-sections": [ { "number": "3.1", "title": "Адрес и параметры", "blocks": [ { "k": "p", "i": 82, "style": "Normal", "text": "Параметры пути, query-параметры и тело запроса отсутствуют. Передайте Bearer-токен в заголовке Authorization." }, { "k": "p", "i": 83, "style": "Caption Custom", "text": "ПРИМЕР ЗАПРОСА" }, { "k": "table", "i": 84, "rows": [ [ "GET /api/v1/ping HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nAccept: application/json" ] ] } ] }, { "number": "3.2", "title": "Успешный ответ · HTTP 200", "blocks": [ { "k": "table", "i": 87, "rows": [ [ "{\n \"status\": \"ok\",\n \"integration_id\": \"DEMO-INT-1C\",\n \"tenant_id\": \"CLIENT-DEMO\",\n \"version\": \"0.1.85\"\n}" ] ] }, { "k": "table", "i": 89, "rows": [ [ "Поле", "Значение" ], [ "status", "Строка \"ok\": проверка подключения выполнена успешно." ], [ "integration_id", "Идентификатор интеграции, для которой выпущен токен." ], [ "tenant_id", "Идентификатор вашей компании в Заездо." ], [ "version", "Версия серверного портала. Это не версия API. Значение 0.1.85 приведено как пример." ] ] } ] }, { "number": "3.3", "title": "Коды и описания ошибок", "blocks": [ { "k": "p", "i": 91, "style": "Normal", "text": "В действующем методе ping ошибка авторизации возвращается в поле detail." }, { "k": "table", "i": 92, "rows": [ [ "HTTP", "Условие", "Точное значение detail" ], [ "401", "Нет заголовка Authorization или используется не Bearer.", "Требуется Bearer-токен интеграции." ], [ "401", "После Bearer не передано значение токена.", "Токен интеграции не указан." ], [ "401", "Токен недействителен, заменён или интеграция отключена.", "Недействительный токен интеграции." ], [ "403", "Компания отключена.", "Компания отключена." ] ] }, { "k": "p", "i": 93, "style": "Caption Custom", "text": "HTTP 401 · ТОКЕН НЕ ПЕРЕДАН" }, { "k": "table", "i": 94, "rows": [ [ "{\n \"detail\": \"Требуется Bearer-токен интеграции.\"\n}" ] ] } ] }, { "number": "3.4", "title": "Действия при получении ответа", "blocks": [ { "k": "table", "i": 97, "rows": [ [ "Ответ", "Что делать" ], [ "200, status: \"ok\"", "Можно переходить к подготовке справочников и созданию визита." ], [ "401", "Проверьте заголовок Authorization, токен и активность интеграции. Не повторяйте запрос без исправления причины." ], [ "403", "Обратитесь к администратору Заездо: компания отключена." ], [ "500 / 502 / 503 / 504 или обрыв связи", "Повторите GET после паузы. При повторяющемся сбое обратитесь в поддержку. JSON-тело для инфраструктурной ошибки не гарантируется." ] ] } ] }, { "number": "3.5", "title": "Пример использования для 1С", "blocks": [ { "k": "p", "i": 99, "style": "Normal", "text": "Получите токен в настройках интеграции: https://app.zaezdo.pro/settings/integration. Выполните запрос из раздела 3.1. При 200 и status: \"ok\" результат подключения считается успешным." }, { "k": "p", "i": 100, "style": "Normal", "text": "Передавайте токен в каждом следующем запросе." } ] } ], "x-docs-id": "ping", "x-docs-number": 3, "parameters": [], "x-request-http": "GET /api/v1/ping HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nAccept: application/json", "responses": { "200": { "description": "Успешный ответ", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "integration_id": { "type": "string" }, "tenant_id": { "type": "string" }, "version": { "type": "string" } }, "required": [ "status", "integration_id", "tenant_id", "version" ] }, "examples": { "default": { "summary": "Успешный ответ", "value": { "status": "ok", "integration_id": "DEMO-INT-1C", "tenant_id": "CLIENT-DEMO", "version": "0.1.85" } } } } } }, "401": { "description": "Ошибка авторизации", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "examples": { "case1": { "summary": "Нет заголовка Authorization или используется не Bearer.", "value": { "detail": "Требуется Bearer-токен интеграции." } }, "case2": { "summary": "После Bearer не передано значение токена.", "value": { "detail": "Токен интеграции не указан." } }, "case3": { "summary": "Токен недействителен, заменён или интеграция отключена.", "value": { "detail": "Недействительный токен интеграции." } } } } } }, "403": { "description": "Ошибка авторизации", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "examples": { "case1": { "summary": "Компания отключена.", "value": { "detail": "Компания отключена." } } } } } } }, "x-http-errors": [ { "http": 401, "condition": "Нет заголовка Authorization или используется не Bearer.", "message": "Требуется Bearer-токен интеграции." }, { "http": 401, "condition": "После Bearer не передано значение токена.", "message": "Токен интеграции не указан." }, { "http": 401, "condition": "Токен недействителен, заменён или интеграция отключена.", "message": "Недействительный токен интеграции." }, { "http": 403, "condition": "Компания отключена.", "message": "Компания отключена." } ], "x-field-errors": [] } }, "/users/{source_id}": { "get": { "operationId": "users", "summary": "Получение пользователя", "description": "Поиск пользователя Заездо по внешнему идентификатору (например 1С), получение назначенных ролей и их распределения по площадкам. По запросу дополнительно проверяется возможность назначения сотрудника ответственным за визит – наличие у него права работать с определенной площадкой.", "tags": [ "users" ], "x-docs-sections": [ { "number": "4.1", "title": "Адрес и параметры", "blocks": [ { "k": "p", "i": 108, "style": "Normal", "text": "Можно получить полную информацию о правах пользователя или добавить проверку конкретной площадки." }, { "k": "p", "i": 109, "style": "Caption Custom", "text": "БЕЗ ПРОВЕРКИ ПЛОЩАДКИ" }, { "k": "table", "i": 110, "rows": [ [ "GET https://app.zaezdo.pro/api/v1/users/AfoninGA" ] ] }, { "k": "p", "i": 112, "style": "Caption Custom", "text": "С ПРОВЕРКОЙ ПЛОЩАДКИ" }, { "k": "table", "i": 113, "rows": [ [ "GET https://app.zaezdo.pro/api/v1/users/AfoninGA?site_source_id=WH-SEVER" ] ] }, { "k": "p", "i": 115, "style": "Normal", "text": "Здесь AfoninGA — идентификатор сотрудника в 1С (или внешней системе учёта)." }, { "k": "table", "i": 116, "rows": [ [ "Параметр", "Тип", "Обяз.", "Назначение" ], [ "source_id", "string", "Да", "Идентификатор сотрудника в 1С, передаётся в URL; максимум 80 символов." ], [ "site_source_id", "string", "Нет", "Идентификатор площадки в 1С, передаётся в query-параметре для проверки права назначения ответственным." ] ] } ] }, { "number": "4.2", "title": "Успешный ответ · HTTP 200", "blocks": [ { "k": "p", "i": 119, "style": "Normal", "text": "В обоих режимах метод возвращает данные пользователя и все его роли. Если передан site_source_id, в ответ дополнительно включается can_be_responsible_for_site." }, { "k": "p", "i": 120, "style": "Caption Custom", "text": "GET /api/v1/users/AfoninGA?site_source_id=WH-SEVER · 200 OK" }, { "k": "table", "i": 121, "rows": [ [ "{\n \"source_id\": \"AfoninGA\",\n \"full_name\": \"Анна Соколова\",\n \"is_active\": true,\n \"has_account\": true,\n \"roles\": [\n {\n \"code\": \"MANAGER\",\n \"name\": \"Менеджер\",\n \"scope\": \"SELECTED_SITES\",\n \"sites\": [\n {\"source_id\": \"WH-SEVER\", \"name\": \"Склад Север\"},\n {\"source_id\": \"WH-YUG\", \"name\": \"Склад Юг\"}\n ]\n },\n {\n \"code\": \"DISPATCHER\",\n \"name\": \"Диспетчер\",\n \"scope\": \"ALL_SITES\",\n \"sites\": []\n },\n {\n \"code\": \"CHECKPOINT\",\n \"name\": \"Сотрудник КПП / охрана\",\n \"scope\": \"SELECTED_SITES\",\n \"sites\": [\n {\"source_id\": \"WH-SEVER\", \"name\": \"Склад Север\"}\n ]\n }\n ],\n \"can_be_responsible_for_site\": {\n \"site_source_id\": \"WH-SEVER\",\n \"allowed\": true\n }\n}" ] ] }, { "k": "p", "i": 123, "style": "Normal", "text": "Если site_source_id не передан, ответ содержит все те же данные и роли, но объект can_be_responsible_for_site полностью отсутствует." } ] }, { "number": "4.3", "title": "Структура ответа", "blocks": [ { "k": "table", "i": 125, "rows": [ [ "Поле ответа", "Назначение" ], [ "source_id", "Идентификатор сотрудника в 1С, указанный для синхронизации в Заездо." ], [ "full_name", "ФИО сотрудника в Заездо." ], [ "is_active", "Признак активности сотрудника (true / false)." ], [ "has_account", "Наличие действующей учётной записи для входа в Заездо." ], [ "roles[]", "Массив назначенных сотруднику ролей." ], [ "roles[].code / name", "Код роли и её наименование." ], [ "roles[].scope", "Область действия роли: ALL_SITES или SELECTED_SITES." ], [ "roles[].sites[]", "Список площадок, на которых действует роль, если scope = SELECTED_SITES." ], [ "can_be_responsible_for_site", "Необязательный результат проверки конкретной площадки: site_source_id, allowed и, при отказе, reason." ] ] } ] }, { "number": "4.4", "title": "Роли и область действия", "blocks": [ { "k": "p", "i": 128, "style": "Normal", "text": "Роль и доступные ей площадки описываются вместе — это позволяет внешней системе понять фактическое распределение прав." }, { "k": "table", "i": 129, "rows": [ [ "Значение scope", "Как интерпретировать" ], [ "ALL_SITES", "Роль действует на всех площадках компании. При этом sites = [] — это не отсутствие доступа." ], [ "SELECTED_SITES", "Роль действует только на площадках из массива sites[]." ] ] }, { "k": "p", "i": 131, "style": "Normal", "text": "Поддерживаемые коды ролей:" }, { "k": "table", "i": 132, "rows": [ [ "Код роли", "Наименование" ], [ "CLIENT_ADMIN", "Администратор клиента" ], [ "MANAGER", "Менеджер" ], [ "DISPATCHER", "Диспетчер" ], [ "CHECKPOINT", "Сотрудник КПП / охрана" ], [ "WAREHOUSE_OPERATOR", "Оператор склада" ], [ "LOGISTICS_MANAGER", "Руководитель склада / логистики" ] ] } ] }, { "number": "4.5", "title": "Проверка назначения ответственным", "blocks": [ { "k": "p", "i": 135, "style": "Normal", "text": "Проверка выполняется только при наличии параметра site_source_id. Заездо проверяет одновременно:" }, { "k": "p", "i": 136, "style": "Bullet Custom", "text": "• сотрудник активен (is_active = true);" }, { "k": "p", "i": 137, "style": "Bullet Custom", "text": "• имеет действующую учётную запись (has_account = true);" }, { "k": "p", "i": 138, "style": "Bullet Custom", "text": "• ему назначена роль MANAGER;" }, { "k": "p", "i": 139, "style": "Bullet Custom", "text": "• роль MANAGER действует на указанной активной площадке." }, { "k": "p", "i": 140, "style": "Caption Custom", "text": "РЕЗУЛЬТАТ УСПЕШНОЙ ПРОВЕРКИ · ФРАГМЕНТ ОТВЕТА" }, { "k": "table", "i": 141, "rows": [ [ "{\n \"can_be_responsible_for_site\": {\n \"site_source_id\": \"WH-SEVER\",\n \"allowed\": true\n }\n}" ] ] }, { "k": "p", "i": 143, "style": "Caption Custom", "text": "ОТКАЗ В НАЗНАЧЕНИИ · ФРАГМЕНТ ОТВЕТА" }, { "k": "table", "i": 144, "rows": [ [ "{\n \"can_be_responsible_for_site\": {\n \"site_source_id\": \"WH-SEVER\",\n \"allowed\": false,\n \"reason\": \"MANAGER_NO_SITE_ACCESS\"\n }\n}" ] ] }, { "k": "p", "i": 146, "style": "Normal", "text": "Отказ в назначении не является ошибкой HTTP: метод возвращает 200 OK с данными сотрудника и allowed = false." }, { "k": "table", "i": 147, "rows": [ [ "Код причины", "Что означает" ], [ "MANAGER_INACTIVE", "Сотрудник неактивен." ], [ "MANAGER_NO_ACCOUNT", "Нет действующей учётной записи." ], [ "MANAGER_NOT_MANAGER", "Нет роли менеджера." ], [ "MANAGER_NO_SITE_ACCESS", "Нет роли менеджера на указанной площадке." ], [ "SITE_INACTIVE", "Площадка отключена." ] ] } ] }, { "number": "4.6", "title": "Порядок проверки запроса", "blocks": [ { "k": "p", "i": 150, "style": "Normal", "text": "Проверки выполняются по этапам. При ошибке метод возвращает результат текущего этапа и не переходит к следующему." }, { "k": "table", "i": 151, "rows": [ [ "Этап", "Результат при ошибке" ], [ "1. Авторизация", "401 — нет действующего токена или интеграция отключена. 403 — компания отключена." ], [ "2. Проверка параметров", "422 — source_id или переданный site_source_id некорректен. Все ошибки параметров перечисляются в errors[]." ], [ "3. Поиск записей", "404 — по корректным идентификаторам не найден пользователь и/или площадка. Все ненайденные записи перечисляются в errors[]." ], [ "4. Проверка назначения", "200 — возвращаются данные пользователя и, если передан site_source_id, результат allowed: true или false." ] ] }, { "k": "p", "i": 153, "style": "Normal", "text": "Без site_source_id поиск площадки и проверка назначения не выполняются. Пустой переданный site_source_id — это некорректный параметр, а не отсутствие параметра." }, { "k": "p", "i": 154, "style": "Normal", "text": "Если идентификатор пользователя некорректен, а площадка не существует, сначала возвращается 422. Поиск площадки начнётся только после исправления параметров." } ] }, { "number": "4.7", "title": "Коды и описания ошибок", "blocks": [ { "k": "p", "i": 156, "style": "Normal", "text": "В колонке message приведён точный текст ответа. Конкретная причина для 404 и 422 указывается в errors[]." }, { "k": "table", "i": 157, "rows": [ [ "HTTP", "code", "message" ], [ "401", "UNAUTHORIZED", "Требуется действующий Bearer-токен интеграции." ], [ "403", "TENANT_INACTIVE", "Компания отключена в Заездо." ], [ "404", "RESOURCE_NOT_FOUND", "Не найдены записи по переданным идентификаторам." ], [ "422", "VALIDATION_ERROR", "Ошибка проверки параметров запроса." ], [ "429", "RATE_LIMITED", "Превышено допустимое количество запросов. Повторите запрос позже." ], [ "500", "INTERNAL_ERROR", "Внутренняя ошибка Заездо." ], [ "503", "SERVICE_UNAVAILABLE", "Сервис Заездо временно недоступен." ] ] } ] }, { "number": "4.8", "title": "Конкретные ошибки параметров и поиска", "blocks": [ { "k": "p", "i": 160, "style": "Normal", "text": "Для HTTP 404 поиск выполнен, но запись не найдена. Для HTTP 422 поиск ещё не выполнялся: сначала нужно исправить параметры." }, { "k": "table", "i": 161, "rows": [ [ "HTTP · field / code", "Точное значение errors[].message" ], [ "404 · source_id\nUSER_NOT_FOUND", "Пользователь с указанным source_id не найден." ], [ "404 · site_source_id\nSITE_NOT_FOUND", "Площадка с указанным site_source_id не найдена." ], [ "422 · source_id\nINVALID_SOURCE_ID", "Некорректный идентификатор сотрудника." ], [ "422 · site_source_id\nINVALID_SITE_SOURCE_ID", "Некорректный идентификатор площадки." ] ] }, { "k": "p", "i": 163, "style": "Normal", "text": "Пользователь, у которого не заполнен source_id, не может быть найден по идентификатору из 1С. Неактивный пользователь или отключённая площадка считаются найденными: это не основание для 404." } ] }, { "number": "4.9", "title": "Формат ответа при ошибке", "blocks": [ { "k": "table", "i": 165, "rows": [ [ "Поле", "Как использовать" ], [ "code", "Общая категория ошибки для программной обработки." ], [ "message", "Точный общий текст ошибки." ], [ "errors[]", "Для 404 и 422: все ошибки остановившего этапа. Каждый элемент содержит field, code и message." ], [ "request_id", "Идентификатор запроса. Передайте его поддержке при обращении." ] ] }, { "k": "p", "i": 168, "style": "Caption Custom", "text": "HTTP 404 · НЕ НАЙДЕНЫ ПОЛЬЗОВАТЕЛЬ И ПЛОЩАДКА" }, { "k": "table", "i": 169, "rows": [ [ "{\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Не найдены записи по переданным идентификаторам.\",\n \"errors\": [\n {\n \"field\": \"source_id\",\n \"code\": \"USER_NOT_FOUND\",\n \"message\": \"Пользователь с указанным source_id не найден.\"\n },\n {\n \"field\": \"site_source_id\",\n \"code\": \"SITE_NOT_FOUND\",\n \"message\": \"Площадка с указанным site_source_id не найдена.\"\n }\n ],\n \"request_id\": \"req-123456\"\n}" ] ] }, { "k": "p", "i": 170, "style": "Normal", "text": "Если не найдена только одна запись, errors[] содержит один элемент. Верхнеуровневый code остаётся RESOURCE_NOT_FOUND." }, { "k": "p", "i": 172, "style": "Caption Custom", "text": "HTTP 422 · НЕКОРРЕКТНЫ ОБА ИДЕНТИФИКАТОРА" }, { "k": "table", "i": 173, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки параметров запроса.\",\n \"errors\": [\n {\n \"field\": \"source_id\",\n \"code\": \"INVALID_SOURCE_ID\",\n \"message\": \"Некорректный идентификатор сотрудника.\"\n },\n {\n \"field\": \"site_source_id\",\n \"code\": \"INVALID_SITE_SOURCE_ID\",\n \"message\": \"Некорректный идентификатор площадки.\"\n }\n ],\n \"request_id\": \"req-123457\"\n}" ] ] } ] }, { "number": "4.10", "title": "Действия при получении ответа", "blocks": [ { "k": "p", "i": 175, "style": "Normal", "text": "Для программной обработки используйте HTTP-статус и поля code, errors[].field, errors[].code. Покажите пользователю все errors[].message; если массива нет — общий message. Не определяйте тип ошибки по тексту сообщения." }, { "k": "table", "i": 176, "rows": [ [ "Ответ", "Что делать интегратору" ], [ "401 / 403", "Проверьте токен, активность интеграции и компании. Не повторяйте запрос без устранения причины." ], [ "422", "Исправьте все параметры, перечисленные в errors[], и отправьте запрос повторно." ], [ "404", "Проверьте source_id пользователя и площадки, а также их сопоставление в Заездо. После исправления повторите запрос." ], [ "200, allowed: false", "Запрос выполнен. Причина отказа указана в reason; исправьте её до создания визита." ], [ "429", "Выдержите паузу, указанную в заголовке Retry-After." ], [ "500 / 503", "Повторите GET после паузы; при повторяющейся ошибке передайте request_id поддержке." ] ] }, { "k": "p", "i": 178, "style": "Normal", "text": "Проверка users не закрепляет права на будущее. При создании визита Заездо проверяет возможность назначения ответственного повторно." } ] }, { "number": "4.11", "title": "Использование при создании визита", "blocks": [ { "k": "p", "i": 180, "style": "Normal", "text": "Например, в 1С (или в другой внешней системе) у контрагента ответственным менеджером указан пользователь с кодом AfoninGA. Перед созданием визита можно проверить его права на площадке WH-SEVER." }, { "k": "p", "i": 181, "style": "Caption Custom", "text": "ПРОВЕРКА ПОЛЬЗОВАТЕЛЯ И ПЛОЩАДКИ" }, { "k": "table", "i": 182, "rows": [ [ "GET /api/v1/users/AfoninGA?site_source_id=WH-SEVER" ] ] }, { "k": "p", "i": 184, "style": "Normal", "text": "Если сервер вернул 200 OK и allowed = true, при создании визита передаётся:" }, { "k": "p", "i": 185, "style": "Caption Custom", "text": "ФРАГМЕНТ ЗАПРОСА POST /api/v1/visits" }, { "k": "table", "i": 186, "rows": [ [ "{\n \"responsible_user_source_id\": \"AfoninGA\"\n}" ] ] }, { "k": "p", "i": 188, "style": "Normal", "text": "Заездо назначает указанного сотрудника ответственным за визит. Если сотрудник не может быть назначен, визит не создаётся." } ] } ], "x-docs-id": "users", "x-docs-number": 4, "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?!.*[\\x00-\\x1F\\x7F/\\\\])(?:\\S|.*\\S)$", "description": "Идентификатор записи во внешней системе. Строка от 1 до 80 символов; регистр учитывается. Запрещены управляющие символы, пробелы по краям и разделители / и \\." }, "example": "AfoninGA" }, { "name": "site_source_id", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 80 }, "description": "Площадка для проверки возможности назначения ответственным. Без параметра результат can_be_responsible_for_site отсутствует.", "example": "WH-SEVER" } ], "x-request-http": "GET /api/v1/users/AfoninGA?site_source_id=WH-SEVER HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nAccept: application/json", "responses": { "200": { "description": "С проверкой площадки", "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string" }, "full_name": { "type": "string" }, "is_active": { "type": "boolean" }, "has_account": { "type": "boolean" }, "roles": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "CLIENT_ADMIN", "MANAGER", "DISPATCHER", "CHECKPOINT", "WAREHOUSE_OPERATOR", "LOGISTICS_MANAGER" ] }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "ALL_SITES", "SELECTED_SITES" ] }, "sites": { "type": "array", "items": { "type": "object", "properties": { "source_id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "source_id", "name" ] } } }, "required": [ "code", "name", "scope", "sites" ] } }, "can_be_responsible_for_site": { "type": "object", "properties": { "site_source_id": { "type": "string" }, "allowed": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "MANAGER_INACTIVE", "MANAGER_NO_ACCOUNT", "MANAGER_NOT_MANAGER", "MANAGER_NO_SITE_ACCESS", "SITE_INACTIVE" ] } }, "required": [ "site_source_id", "allowed" ] } }, "required": [ "source_id", "full_name", "is_active", "has_account", "roles" ] }, "examples": { "default": { "summary": "С проверкой площадки", "value": { "source_id": "AfoninGA", "full_name": "Анна Соколова", "is_active": true, "has_account": true, "roles": [ { "code": "MANAGER", "name": "Менеджер", "scope": "SELECTED_SITES", "sites": [ { "source_id": "WH-SEVER", "name": "Склад Север" }, { "source_id": "WH-YUG", "name": "Склад Юг" } ] }, { "code": "DISPATCHER", "name": "Диспетчер", "scope": "ALL_SITES", "sites": [] }, { "code": "CHECKPOINT", "name": "Сотрудник КПП / охрана", "scope": "SELECTED_SITES", "sites": [ { "source_id": "WH-SEVER", "name": "Склад Север" } ] } ], "can_be_responsible_for_site": { "site_source_id": "WH-SEVER", "allowed": true } } }, "withoutSite": { "summary": "Без проверки площадки", "value": { "source_id": "AfoninGA", "full_name": "Анна Соколова", "is_active": true, "has_account": true, "roles": [ { "code": "MANAGER", "name": "Менеджер", "scope": "SELECTED_SITES", "sites": [ { "source_id": "WH-SEVER", "name": "Склад Север" }, { "source_id": "WH-YUG", "name": "Склад Юг" } ] }, { "code": "DISPATCHER", "name": "Диспетчер", "scope": "ALL_SITES", "sites": [] }, { "code": "CHECKPOINT", "name": "Сотрудник КПП / охрана", "scope": "SELECTED_SITES", "sites": [ { "source_id": "WH-SEVER", "name": "Склад Север" } ] } ] } }, "notAllowed": { "summary": "Назначение недоступно", "value": { "source_id": "AfoninGA", "full_name": "Анна Соколова", "is_active": true, "has_account": true, "roles": [ { "code": "MANAGER", "name": "Менеджер", "scope": "SELECTED_SITES", "sites": [ { "source_id": "WH-SEVER", "name": "Склад Север" }, { "source_id": "WH-YUG", "name": "Склад Юг" } ] }, { "code": "DISPATCHER", "name": "Диспетчер", "scope": "ALL_SITES", "sites": [] }, { "code": "CHECKPOINT", "name": "Сотрудник КПП / охрана", "scope": "SELECTED_SITES", "sites": [ { "source_id": "WH-SEVER", "name": "Склад Север" } ] } ], "can_be_responsible_for_site": { "site_source_id": "WH-SEVER", "allowed": false, "reason": "MANAGER_NO_SITE_ACCESS" } } } } } } }, "401": { "description": "Требуется действующий Bearer-токен интеграции.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции.", "request_id": "req-example-401" } } } }, "403": { "description": "Компания отключена в Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо.", "request_id": "req-example-403" } } } }, "404": { "description": "Не найдены записи по переданным идентификаторам.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RESOURCE_NOT_FOUND", "message": "Не найдены записи по переданным идентификаторам.", "request_id": "req-example-404", "errors": [ { "field": "source_id", "code": "USER_NOT_FOUND", "message": "Пользователь с указанным source_id не найден." }, { "field": "site_source_id", "code": "SITE_NOT_FOUND", "message": "Площадка с указанным site_source_id не найдена." } ] } } } }, "422": { "description": "Ошибка проверки параметров запроса.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "VALIDATION_ERROR", "message": "Ошибка проверки параметров запроса.", "request_id": "req-example-422", "errors": [ { "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор сотрудника." }, { "field": "site_source_id", "code": "INVALID_SITE_SOURCE_ID", "message": "Некорректный идентификатор площадки." } ] } } } }, "429": { "description": "Превышено допустимое количество запросов. Повторите запрос позже.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже.", "request_id": "req-example-429" } } }, "headers": { "Retry-After": { "description": "Время ожидания перед повторным запросом.", "schema": { "type": "string" } } } }, "500": { "description": "Внутренняя ошибка Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо.", "request_id": "req-example-500" } } } }, "503": { "description": "Сервис Заездо временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен.", "request_id": "req-example-503" } } } } }, "x-http-errors": [ { "http": 401, "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции." }, { "http": 403, "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо." }, { "http": 404, "code": "RESOURCE_NOT_FOUND", "message": "Не найдены записи по переданным идентификаторам." }, { "http": 422, "code": "VALIDATION_ERROR", "message": "Ошибка проверки параметров запроса." }, { "http": 429, "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже." }, { "http": 500, "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо." }, { "http": 503, "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен." } ], "x-field-errors": [ { "http": 404, "field": "source_id", "code": "USER_NOT_FOUND", "message": "Пользователь с указанным source_id не найден.", "section": "4.8" }, { "http": 404, "field": "site_source_id", "code": "SITE_NOT_FOUND", "message": "Площадка с указанным site_source_id не найдена.", "section": "4.8" }, { "http": 422, "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор сотрудника.", "section": "4.8" }, { "http": 422, "field": "site_source_id", "code": "INVALID_SITE_SOURCE_ID", "message": "Некорректный идентификатор площадки.", "section": "4.8" } ] } }, "/sites/{source_id}": { "put": { "operationId": "sites", "summary": "Создание или обновление площадки", "description": "Передача из 1С основных сведений о складе или территории. Если source_id ещё не зарегистрирован, Заездо создаёт площадку; иначе обновляет её основные сведения.", "tags": [ "sites" ], "x-docs-sections": [ { "number": "5.1", "title": "Адрес и параметры", "blocks": [ { "k": "p", "i": 196, "style": "Normal", "text": "Адрес: https://app.zaezdo.pro/api/v1/sites/{source_id}. Параметр source_id обязателен, передаётся в пути URL; ограничения — в разделе 1.1. Query-параметры не используются." }, { "k": "p", "i": 197, "style": "Normal", "text": "Тело запроса — объект JSON. В таблице ниже перечислены поля тела запроса; они передаются как при создании, так и при обновлении." }, { "k": "table", "i": 198, "rows": [ [ "Параметр", "Обяз.", "Назначение" ], [ "name", "Да", "Наименование площадки. Строка от 1 до 200 символов." ], [ "code", "Нет", "Код площадки. Строка до 60 символов; это не source_id." ], [ "address", "Нет", "Адрес площадки. Строка до 500 символов." ], [ "comment", "Нет", "Комментарий. Строка; ограничение длины на уровне поля не установлено." ], [ "admission_mode", "Нет", "Строка: MANUAL_REVIEW — «Требует ручной проверки»; AUTO_IF_DATA_PRESENT — «Разрешен при наличии сведений». Если поле отсутствует, устанавливается MANUAL_REVIEW, в том числе при обновлении." ] ] }, { "k": "p", "i": 199, "style": "Normal", "text": "Если admission_mode (реквизит «Допуск на площадку») передан, он должен содержать одно из двух указанных строковых значений. null, пустая строка или другое значение приводят к ошибке 422 INVALID_ADMISSION_MODE." } ] }, { "number": "5.2", "title": "Пример запроса", "blocks": [ { "k": "table", "i": 201, "rows": [ [ "PUT /api/v1/sites/WH-SEVER HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"name\": \"Склад Север\",\n \"code\": \"СКЛ-000042\",\n \"address\": \"Москва, Складская улица, 15\",\n \"comment\": \"Основной склад\",\n \"admission_mode\": \"MANUAL_REVIEW\"\n}" ] ] }, { "k": "p", "i": 202, "style": "Normal", "text": "Чтобы выбрать режим «Разрешен при наличии сведений», передайте в теле JSON \"admission_mode\": \"AUTO_IF_DATA_PRESENT\"." } ] }, { "number": "5.3", "title": "Успешные ответы", "blocks": [ { "k": "p", "i": 205, "style": "Caption Custom", "text": "НОВАЯ ЗАПИСЬ · HTTP 201 CREATED" }, { "k": "table", "i": 206, "rows": [ [ "{\n \"id\": \"SITE-EXAMPLE001\",\n \"source_id\": \"WH-SEVER\",\n \"created\": true,\n \"is_active\": true,\n \"admission_mode\": \"MANUAL_REVIEW\"\n}" ] ] }, { "k": "p", "i": 208, "style": "Normal", "text": "Для существующего source_id возвращается HTTP 200 с тем же набором полей и created: false. Значение id сохраняется, остальные поля отражают результат операции. Если данные не изменились, ответ также 200 и created: false." }, { "k": "table", "i": 209, "rows": [ [ "Поле ответа", "Значение" ], [ "id", "Идентификатор записи в Заездо. Для последующих PUT и создания визита сохранять его не обязательно." ], [ "source_id", "Идентификатор из URL. Используйте его в соответствующем поле запроса visits." ], [ "created", "true — запись создана; false — обработана существующая запись." ], [ "is_active", "true — запись активна; false — отключена и не может использоваться для нового визита." ], [ "admission_mode", "Значение поля «Допуск на площадку». MANUAL_REVIEW — «Требует ручной проверки»; AUTO_IF_DATA_PRESENT — «Разрешен при наличии сведений»." ] ] } ] }, { "number": "5.4", "title": "Правила создания и обновления", "blocks": [ { "k": "p", "i": 211, "style": "Normal", "text": "Полные правила передачи значений и очистки необязательных полей приведены в разделе 1.1." }, { "k": "p", "i": 212, "style": "Normal", "text": "При каждом PUT поле «Допуск на площадку» устанавливается по admission_mode из тела JSON. Если поле отсутствует, выбирается «Требует ручной проверки» (MANUAL_REVIEW), в том числе при обновлении. Новая площадка сразу активна; отдельного подтверждения создания не требуется." }, { "k": "p", "i": 213, "style": "Normal", "text": "Повторный PUT обновляет name, code, address, comment и admission_mode. При этом он не меняет активность, права сотрудников, зоны ожидания, места обслуживания или табло." }, { "k": "p", "i": 214, "style": "Normal", "text": "Название и адрес не используются для автоматического объединения площадок. Если code заполнен, совпадение кода с другой площадкой вызывает 409. Сравнивается код после удаления пробелов по краям; регистр символов учитывается. Если code не передан, сопоставление выполняется только по source_id." }, { "k": "p", "i": 215, "style": "Normal", "text": "Площадку можно использовать в visits сразу после успешного создания, если ответственный менеджер имеет к ней доступ. PUT не назначает сотрудников и не выдаёт им права." } ] }, { "number": "5.5", "title": "Порядок проверки запроса", "blocks": [ { "k": "table", "i": 217, "rows": [ [ "Этап", "Результат" ], [ "1. Авторизация", "401 при проблеме с токеном; 403 при отключённой компании." ], [ "2. Чтение JSON", "415 при неверном Content-Type; 400 при нечитаемом JSON." ], [ "3. Проверка параметров", "422: в errors[] возвращаются все независимые ошибки обязательности, типов, длины, реквизитов и значения admission_mode в теле JSON." ], [ "4. Поиск и проверка конфликтов", "Запись ищется по source_id. Проверяются совпадения, описанные в правилах метода. При конфликте — 409; изменений нет." ], [ "5. Сохранение", "Если запись не найдена — создать и вернуть 201. Если найдена — обновить и вернуть 200. При отклонении запроса данные не меняются." ] ] }, { "k": "p", "i": 218, "style": "Normal", "text": "После ошибки следующий этап не выполняется. Ошибки параметров 422 и конфликты 409 не смешиваются. Отсутствие записи по source_id не даёт 404: это штатный случай создания." } ] }, { "number": "5.6", "title": "Коды и описания ошибок", "blocks": [ { "k": "p", "i": 220, "style": "Normal", "text": "Общие HTTP-коды, верхнеуровневые message и ошибки source_id, JSON, лишних полей и comment приведены в разделах 1.2–1.3. Ниже — точные значения errors[].message этого метода." }, { "k": "table", "i": 221, "rows": [ [ "HTTP · field / code", "Точное значение errors[].message" ], [ "422 · name\nREQUIRED", "Укажите наименование площадки." ], [ "422 · name\nINVALID_NAME", "Наименование площадки должно быть строкой длиной от 1 до 200 символов." ], [ "422 · code\nINVALID_CODE", "Код площадки должен быть строкой длиной не более 60 символов или null." ], [ "422 · address\nINVALID_ADDRESS", "Адрес площадки должен быть строкой длиной не более 500 символов или null." ], [ "422 · admission_mode\nINVALID_ADMISSION_MODE", "Допустимые значения admission_mode: MANUAL_REVIEW, AUTO_IF_DATA_PRESENT." ] ] } ] }, { "number": "5.7", "title": "Конфликт записей · HTTP 409", "blocks": [ { "k": "p", "i": 223, "style": "Normal", "text": "Верхнеуровневый код — RESOURCE_CONFLICT; сообщение — «Невозможно сохранить запись из-за конфликта данных.». В errors[] возвращается:" }, { "k": "table", "i": 224, "rows": [ [ "field / code", "Точное значение errors[].message" ], [ "code\nSITE_CODE_CONFLICT", "Площадка с указанным кодом уже существует, но не сопоставлена с переданным source_id." ] ] }, { "k": "p", "i": 225, "style": "Caption Custom", "text": "ПРИМЕР ОТВЕТА · HTTP 409" }, { "k": "table", "i": 226, "rows": [ [ "{\n \"code\": \"RESOURCE_CONFLICT\",\n \"message\": \"Невозможно сохранить запись из-за конфликта данных.\",\n \"errors\": [\n {\n \"field\": \"code\",\n \"code\": \"SITE_CODE_CONFLICT\",\n \"message\": \"Площадка с указанным кодом уже существует, но не сопоставлена с переданным source_id.\"\n }\n ],\n \"request_id\": \"req-sites-conflict\"\n}" ] ] } ] }, { "number": "5.8", "title": "Пример ошибки параметров", "blocks": [ { "k": "p", "i": 229, "style": "Caption Custom", "text": "HTTP 422 · НЕСКОЛЬКО ОШИБОК В ОДНОМ ОТВЕТЕ" }, { "k": "table", "i": 230, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки данных справочника.\",\n \"errors\": [\n {\n \"field\": \"name\",\n \"code\": \"REQUIRED\",\n \"message\": \"Укажите наименование площадки.\"\n },\n {\n \"field\": \"address\",\n \"code\": \"INVALID_ADDRESS\",\n \"message\": \"Адрес площадки должен быть строкой длиной не более 500 символов или null.\"\n }\n ],\n \"request_id\": \"req-sites-validation\"\n}" ] ] }, { "k": "p", "i": 232, "style": "Normal", "text": "Покажите все errors[].message, исправьте перечисленные поля и повторите PUT с тем же source_id. При 409 сначала разрешите конфликт; при 500, 503 или потере ответа повторяйте прежний запрос после паузы." } ] }, { "number": "5.9", "title": "Пример использования для 1С", "blocks": [ { "k": "p", "i": 234, "style": "Normal", "text": "В 1С закрепите WH-SEVER за складом «Склад Север». Выполните PUT с наименованием и актуальными реквизитами. При необходимости укажите admission_mode в теле JSON. После 201 или 200 и is_active: true используйте WH-SEVER при создании визитов. Если is_active: false, площадка остаётся отключённой; её нужно активировать в Заездо." }, { "k": "p", "i": 235, "style": "Caption Custom", "text": "ФРАГМЕНТ ЗАПРОСА POST /api/v1/visits" }, { "k": "table", "i": 236, "rows": [ [ "{\n \"site_source_id\": \"WH-SEVER\"\n}" ] ] }, { "k": "p", "i": 238, "style": "Normal", "text": "При переименовании склада отправьте тот же PUT с новым name и полным набором остальных сохраняемых полей. Используйте тот же source_id. Чтобы сохранить режим допуска, отличный от «Требует ручной проверки», снова передайте соответствующий admission_mode в теле JSON." } ] } ], "x-docs-id": "sites", "x-docs-number": 5, "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?!.*[\\x00-\\x1F\\x7F/\\\\])(?:\\S|.*\\S)$", "description": "Идентификатор записи во внешней системе. Строка от 1 до 80 символов; регистр учитывается. Запрещены управляющие символы, пробелы по краям и разделители / и \\." }, "example": "WH-SEVER" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Наименование площадки. Строка от 1 до 200 символов.", "minLength": 1, "maxLength": 200 }, "code": { "type": [ "string", "null" ], "description": "Код площадки. Строка до 60 символов; это не source_id.", "maxLength": 60 }, "address": { "type": [ "string", "null" ], "description": "Адрес площадки. Строка до 500 символов.", "maxLength": 500 }, "comment": { "type": [ "string", "null" ], "description": "Комментарий. Строка; ограничение длины на уровне поля не установлено." }, "admission_mode": { "type": "string", "description": "Строка: MANUAL_REVIEW — «Требует ручной проверки»; AUTO_IF_DATA_PRESENT — «Разрешен при наличии сведений». Если поле отсутствует, устанавливается MANUAL_REVIEW, в том числе при обновлении.", "enum": [ "MANUAL_REVIEW", "AUTO_IF_DATA_PRESENT" ], "default": "MANUAL_REVIEW" } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "Склад Север", "code": "СКЛ-000042", "address": "Москва, Складская улица, 15", "comment": "Основной склад", "admission_mode": "MANUAL_REVIEW" } } } }, "x-request-http": "PUT /api/v1/sites/WH-SEVER HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"name\": \"Склад Север\",\n \"code\": \"СКЛ-000042\",\n \"address\": \"Москва, Складская улица, 15\",\n \"comment\": \"Основной склад\",\n \"admission_mode\": \"MANUAL_REVIEW\"\n}", "responses": { "201": { "description": "Создано", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" }, "admission_mode": { "type": "string", "enum": [ "MANUAL_REVIEW", "AUTO_IF_DATA_PRESENT" ] } }, "required": [ "id", "source_id", "created", "is_active", "admission_mode" ] }, "examples": { "default": { "summary": "Создано", "value": { "id": "SITE-EXAMPLE001", "source_id": "WH-SEVER", "created": true, "is_active": true, "admission_mode": "MANUAL_REVIEW" } } } } } }, "200": { "description": "Обновлено / повтор", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" }, "admission_mode": { "type": "string", "enum": [ "MANUAL_REVIEW", "AUTO_IF_DATA_PRESENT" ] } }, "required": [ "id", "source_id", "created", "is_active", "admission_mode" ] }, "examples": { "default": { "summary": "Обновлено / повтор", "value": { "id": "SITE-EXAMPLE001", "source_id": "WH-SEVER", "created": false, "is_active": true, "admission_mode": "MANUAL_REVIEW" } } } } } }, "400": { "description": "Не удалось прочитать JSON тела запроса.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса.", "request_id": "req-example-400" } } } }, "401": { "description": "Требуется действующий Bearer-токен интеграции.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции.", "request_id": "req-example-401" } } } }, "403": { "description": "Компания отключена в Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо.", "request_id": "req-example-403" } } } }, "409": { "description": "Невозможно сохранить запись из-за конфликта данных.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных.", "request_id": "req-example-409", "errors": [ { "field": "code", "code": "SITE_CODE_CONFLICT", "message": "Площадка с указанным кодом уже существует, но не сопоставлена с переданным source_id." } ] } } } }, "415": { "description": "Передайте тело запроса с Content-Type: application/json.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json.", "request_id": "req-example-415" } } } }, "422": { "description": "Ошибка проверки данных справочника.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника.", "request_id": "req-example-422", "errors": [ { "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON." }, { "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе." } ] } } } }, "429": { "description": "Превышено допустимое количество запросов. Повторите запрос позже.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже.", "request_id": "req-example-429" } } }, "headers": { "Retry-After": { "description": "Время ожидания перед повторным запросом.", "schema": { "type": "string" } } } }, "500": { "description": "Внутренняя ошибка Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо.", "request_id": "req-example-500" } } } }, "503": { "description": "Сервис Заездо временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен.", "request_id": "req-example-503" } } } } }, "x-http-errors": [ { "http": 400, "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса." }, { "http": 401, "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции." }, { "http": 403, "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо." }, { "http": 409, "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных." }, { "http": 415, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json." }, { "http": 422, "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника." }, { "http": 429, "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже." }, { "http": 500, "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо." }, { "http": 503, "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен." } ], "x-field-errors": [ { "http": 422, "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON.", "section": "1.3" }, { "http": 422, "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе.", "section": "1.3" }, { "http": 422, "field": "Имя лишнего поля", "code": "UNKNOWN_FIELD", "message": "Параметр не поддерживается этим методом.", "section": "1.3" }, { "http": 422, "field": "comment", "code": "INVALID_COMMENT", "message": "Комментарий должен быть строкой или null.", "section": "1.3" }, { "http": 422, "field": "name", "code": "REQUIRED", "message": "Укажите наименование площадки.", "section": "5.6" }, { "http": 422, "field": "name", "code": "INVALID_NAME", "message": "Наименование площадки должно быть строкой длиной от 1 до 200 символов.", "section": "5.6" }, { "http": 422, "field": "code", "code": "INVALID_CODE", "message": "Код площадки должен быть строкой длиной не более 60 символов или null.", "section": "5.6" }, { "http": 422, "field": "address", "code": "INVALID_ADDRESS", "message": "Адрес площадки должен быть строкой длиной не более 500 символов или null.", "section": "5.6" }, { "http": 422, "field": "admission_mode", "code": "INVALID_ADMISSION_MODE", "message": "Допустимые значения admission_mode: MANUAL_REVIEW, AUTO_IF_DATA_PRESENT.", "section": "5.6" }, { "http": 409, "field": "code", "code": "SITE_CODE_CONFLICT", "message": "Площадка с указанным кодом уже существует, но не сопоставлена с переданным source_id.", "section": "5.7" } ] } }, "/counterparties/{source_id}": { "put": { "operationId": "counterparties", "summary": "Создание или обновление контрагента", "description": "Передача контрагента из 1С в Заездо. Метод создаёт запись по новому source_id или обновляет реквизиты ранее переданной записи. Контактные лица, телефоны и email этим методом не передаются.", "tags": [ "counterparties" ], "x-docs-sections": [ { "number": "6.1", "title": "Адрес и параметры", "blocks": [ { "k": "p", "i": 246, "style": "Normal", "text": "Адрес: https://app.zaezdo.pro/api/v1/counterparties/{source_id}. Параметр source_id обязателен, передаётся в URL; ограничения — в разделе 1.1. Query-параметры не используются." }, { "k": "p", "i": 247, "style": "Normal", "text": "Тело запроса — объект JSON. Параметры ниже передаются как при создании, так и при обновлении." }, { "k": "table", "i": 248, "rows": [ [ "Параметр", "Обяз.", "Назначение" ], [ "name", "Да", "Наименование. Строка от 1 до 300 символов." ], [ "inn", "Нет*", "ИНН. Строка из 10 или 12 цифр с корректным контрольным числом." ], [ "kpp", "Нет*", "КПП. Строка из 9 цифр; требуется при ИНН из 10 цифр." ], [ "comment", "Нет", "Комментарий. Строка; ограничение длины на уровне поля не установлено." ] ] }, { "k": "p", "i": 249, "style": "Normal", "text": "* ИНН и КПП можно не передавать вместе. При ИНН из 10 цифр КПП обязателен. При ИНН из 12 цифр КПП должен быть пустым. КПП без ИНН не допускается." } ] }, { "number": "6.2", "title": "Пример запроса", "blocks": [ { "k": "table", "i": 251, "rows": [ [ "PUT /api/v1/counterparties/CP-0042 HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"name\": \"ООО «Пример Логистика»\",\n \"inn\": \"7701234560\",\n \"kpp\": \"770101001\",\n \"comment\": \"Поставщик\"\n}" ] ] } ] }, { "number": "6.3", "title": "Успешные ответы", "blocks": [ { "k": "p", "i": 254, "style": "Caption Custom", "text": "НОВАЯ ЗАПИСЬ · HTTP 201 CREATED" }, { "k": "table", "i": 255, "rows": [ [ "{\n \"id\": \"CP-EXAMPLE001\",\n \"source_id\": \"CP-0042\",\n \"created\": true,\n \"is_active\": true\n}" ] ] }, { "k": "p", "i": 257, "style": "Normal", "text": "Для существующего source_id возвращается HTTP 200 с тем же набором полей и created: false. Значение id сохраняется, остальные поля отражают результат операции. Если данные не изменились, ответ также 200 и created: false." }, { "k": "table", "i": 258, "rows": [ [ "Поле ответа", "Значение" ], [ "id", "Идентификатор записи в Заездо. Для последующих PUT и создания визита сохранять его не обязательно." ], [ "source_id", "Идентификатор из URL. Используйте его в соответствующем поле запроса visits." ], [ "created", "true — запись создана; false — обработана существующая запись." ], [ "is_active", "true — запись активна; false — отключена и не может использоваться для нового визита." ] ] } ] }, { "number": "6.4", "title": "Правила создания и обновления", "blocks": [ { "k": "p", "i": 260, "style": "Normal", "text": "Полные правила передачи значений и очистки необязательных полей приведены в разделе 1.1." }, { "k": "p", "i": 261, "style": "Normal", "text": "Обновляются только name, inn, kpp и comment. Активность и контактные лица не изменяются." }, { "k": "p", "i": 262, "style": "Normal", "text": "Для совпадений проверяется пара ИНН + КПП у организаций либо ИНН из 12 цифр у ИП. Если эти реквизиты принадлежат другой записи, возвращается 409: автоматического объединения нет." }, { "k": "p", "i": 263, "style": "Normal", "text": "При отсутствии ИНН поиск по наименованию не выполняется. Чтобы не создать дубликаты, используйте неизменный source_id; одинаковые названия сами по себе не доказывают совпадение контрагентов." }, { "k": "p", "i": 264, "style": "Normal", "text": "Идентификатор ответственного менеджера в этом методе не передаётся. При создании визита 1С отдельно указывает responsible_user_source_id своего ответственного за контрагента." }, { "k": "p", "i": 265, "style": "Heading 3", "text": "Проверка ИНН и КПП" }, { "k": "table", "i": 266, "rows": [ [ "Переданные реквизиты", "Условие сохранения" ], [ "ИНН и КПП не заполнены", "Допускается: для создания достаточно наименования." ], [ "ИНН организации: 10 цифр", "Контрольное число ИНН корректно; КПП заполнен и содержит 9 цифр." ], [ "ИНН ИП: 12 цифр", "Контрольные числа ИНН корректны; КПП не заполнен." ], [ "КПП заполнен, ИНН пуст", "Ошибка INN_REQUIRED_FOR_KPP." ] ] }, { "k": "p", "i": 267, "style": "Normal", "text": "Если формат ИНН некорректен, проверка контрольного числа не выполняется. Условия КПП, зависящие от длины ИНН, проверяются после определения его типа. Для одного КПП возвращается одна причина: отсутствие, неверный формат либо запрет для ИП." } ] }, { "number": "6.5", "title": "Порядок проверки запроса", "blocks": [ { "k": "table", "i": 269, "rows": [ [ "Этап", "Результат" ], [ "1. Авторизация", "401 при проблеме с токеном; 403 при отключённой компании." ], [ "2. Чтение JSON", "415 при неверном Content-Type; 400 при нечитаемом JSON." ], [ "3. Проверка параметров", "422: в errors[] возвращаются все независимые ошибки обязательности, типов, длины и реквизитов." ], [ "4. Поиск и проверка конфликтов", "Запись ищется по source_id. Проверяются совпадения, описанные в правилах метода. При конфликте — 409; изменений нет." ], [ "5. Сохранение", "Если запись не найдена — создать и вернуть 201. Если найдена — обновить и вернуть 200. При отклонении запроса данные не меняются." ] ] }, { "k": "p", "i": 270, "style": "Normal", "text": "После ошибки следующий этап не выполняется. Ошибки параметров 422 и конфликты 409 не смешиваются. Отсутствие записи по source_id не даёт 404: это штатный случай создания." } ] }, { "number": "6.6", "title": "Коды и описания ошибок", "blocks": [ { "k": "p", "i": 272, "style": "Normal", "text": "Общие HTTP-коды, верхнеуровневые message и ошибки source_id, JSON, лишних полей и comment приведены в разделах 1.2–1.3. Ниже — точные значения errors[].message этого метода." }, { "k": "table", "i": 273, "rows": [ [ "HTTP · field / code", "Точное значение errors[].message" ], [ "422 · name\nREQUIRED", "Укажите наименование контрагента." ], [ "422 · name\nINVALID_NAME", "Наименование контрагента должно быть строкой длиной от 1 до 300 символов." ], [ "422 · inn\nINVALID_INN", "ИНН должен содержать 10 цифр для организации или 12 цифр для ИП." ], [ "422 · inn\nINVALID_INN_CHECKSUM", "Некорректный ИНН: не совпадает контрольное число." ], [ "422 · inn\nINN_REQUIRED_FOR_KPP", "Укажите ИНН, если передан КПП." ], [ "422 · kpp\nINVALID_KPP", "КПП должен содержать 9 цифр." ], [ "422 · kpp\nKPP_REQUIRED", "Требуется указать КПП." ], [ "422 · kpp\nKPP_NOT_ALLOWED", "Для ИП КПП не указывается." ] ] } ] }, { "number": "6.7", "title": "Конфликт записей · HTTP 409", "blocks": [ { "k": "p", "i": 275, "style": "Normal", "text": "Верхнеуровневый код — RESOURCE_CONFLICT; сообщение — «Невозможно сохранить запись из-за конфликта данных.». В errors[] возвращается:" }, { "k": "table", "i": 276, "rows": [ [ "field / code", "Точное значение errors[].message" ], [ "inn\nCOUNTERPARTY_DETAILS_CONFLICT", "Контрагент с указанными ИНН и КПП либо ИНН ИП уже существует, но не сопоставлен с переданным source_id." ] ] }, { "k": "p", "i": 277, "style": "Caption Custom", "text": "ПРИМЕР ОТВЕТА · HTTP 409" }, { "k": "table", "i": 278, "rows": [ [ "{\n \"code\": \"RESOURCE_CONFLICT\",\n \"message\": \"Невозможно сохранить запись из-за конфликта данных.\",\n \"errors\": [\n {\n \"field\": \"inn\",\n \"code\": \"COUNTERPARTY_DETAILS_CONFLICT\",\n \"message\": \"Контрагент с указанными ИНН и КПП либо ИНН ИП уже существует, но не сопоставлен с переданным source_id.\"\n }\n ],\n \"request_id\": \"req-counterparties-conflict\"\n}" ] ] } ] }, { "number": "6.8", "title": "Пример ошибки параметров", "blocks": [ { "k": "p", "i": 281, "style": "Caption Custom", "text": "HTTP 422 · НЕСКОЛЬКО ОШИБОК В ОДНОМ ОТВЕТЕ" }, { "k": "table", "i": 282, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки данных справочника.\",\n \"errors\": [\n {\n \"field\": \"name\",\n \"code\": \"REQUIRED\",\n \"message\": \"Укажите наименование контрагента.\"\n },\n {\n \"field\": \"kpp\",\n \"code\": \"KPP_REQUIRED\",\n \"message\": \"Требуется указать КПП.\"\n }\n ],\n \"request_id\": \"req-counterparties-validation\"\n}" ] ] }, { "k": "p", "i": 284, "style": "Normal", "text": "Покажите все errors[].message, исправьте перечисленные поля и повторите PUT с тем же source_id. При 409 сначала разрешите конфликт; при 500, 503 или потере ответа повторяйте прежний запрос после паузы." } ] }, { "number": "6.9", "title": "Пример использования для 1С", "blocks": [ { "k": "p", "i": 286, "style": "Normal", "text": "Перед передачей заявки выполните PUT /api/v1/counterparties/CP-0042 с реквизитами контрагента. После успешного ответа и is_active: true используйте CP-0042 в визите. При 409 сначала разрешите сопоставление, не создавая новый внешний идентификатор." }, { "k": "p", "i": 287, "style": "Caption Custom", "text": "ФРАГМЕНТ ЗАПРОСА POST /api/v1/visits" }, { "k": "table", "i": 288, "rows": [ [ "{\n \"counterparty_source_id\": \"CP-0042\"\n}" ] ] }, { "k": "p", "i": 290, "style": "Normal", "text": "При изменении наименования или реквизитов в 1С отправьте полный набор полей на тот же URL. Чтобы удалить комментарий, передайте comment: \"\". Если нужно сохранить ИНН и КПП, их необходимо повторить в запросе." } ] } ], "x-docs-id": "counterparties", "x-docs-number": 6, "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?!.*[\\x00-\\x1F\\x7F/\\\\])(?:\\S|.*\\S)$", "description": "Идентификатор записи во внешней системе. Строка от 1 до 80 символов; регистр учитывается. Запрещены управляющие символы, пробелы по краям и разделители / и \\." }, "example": "CP-0042" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Наименование. Строка от 1 до 300 символов.", "minLength": 1, "maxLength": 300 }, "inn": { "type": [ "string", "null" ], "description": "ИНН. Строка из 10 или 12 цифр с корректным контрольным числом.", "pattern": "^(?:[0-9]{10}|[0-9]{12}|)$" }, "kpp": { "type": [ "string", "null" ], "description": "КПП. Строка из 9 цифр; требуется при ИНН из 10 цифр.", "pattern": "^(?:[0-9]{9}|)$" }, "comment": { "type": [ "string", "null" ], "description": "Комментарий. Строка; ограничение длины на уровне поля не установлено." } }, "required": [ "name" ], "additionalProperties": false }, "example": { "name": "ООО «Пример Логистика»", "inn": "7701234560", "kpp": "770101001", "comment": "Поставщик" } } } }, "x-request-http": "PUT /api/v1/counterparties/CP-0042 HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"name\": \"ООО «Пример Логистика»\",\n \"inn\": \"7701234560\",\n \"kpp\": \"770101001\",\n \"comment\": \"Поставщик\"\n}", "responses": { "201": { "description": "Создано", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "required": [ "id", "source_id", "created", "is_active" ] }, "examples": { "default": { "summary": "Создано", "value": { "id": "CP-EXAMPLE001", "source_id": "CP-0042", "created": true, "is_active": true } } } } } }, "200": { "description": "Обновлено / повтор", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "required": [ "id", "source_id", "created", "is_active" ] }, "examples": { "default": { "summary": "Обновлено / повтор", "value": { "id": "CP-EXAMPLE001", "source_id": "CP-0042", "created": false, "is_active": true } } } } } }, "400": { "description": "Не удалось прочитать JSON тела запроса.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса.", "request_id": "req-example-400" } } } }, "401": { "description": "Требуется действующий Bearer-токен интеграции.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции.", "request_id": "req-example-401" } } } }, "403": { "description": "Компания отключена в Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо.", "request_id": "req-example-403" } } } }, "409": { "description": "Невозможно сохранить запись из-за конфликта данных.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных.", "request_id": "req-example-409", "errors": [ { "field": "inn", "code": "COUNTERPARTY_DETAILS_CONFLICT", "message": "Контрагент с указанными ИНН и КПП либо ИНН ИП уже существует, но не сопоставлен с переданным source_id." } ] } } } }, "415": { "description": "Передайте тело запроса с Content-Type: application/json.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json.", "request_id": "req-example-415" } } } }, "422": { "description": "Ошибка проверки данных справочника.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника.", "request_id": "req-example-422", "errors": [ { "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON." }, { "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе." } ] } } } }, "429": { "description": "Превышено допустимое количество запросов. Повторите запрос позже.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже.", "request_id": "req-example-429" } } }, "headers": { "Retry-After": { "description": "Время ожидания перед повторным запросом.", "schema": { "type": "string" } } } }, "500": { "description": "Внутренняя ошибка Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо.", "request_id": "req-example-500" } } } }, "503": { "description": "Сервис Заездо временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен.", "request_id": "req-example-503" } } } } }, "x-http-errors": [ { "http": 400, "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса." }, { "http": 401, "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции." }, { "http": 403, "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо." }, { "http": 409, "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных." }, { "http": 415, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json." }, { "http": 422, "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника." }, { "http": 429, "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже." }, { "http": 500, "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо." }, { "http": 503, "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен." } ], "x-field-errors": [ { "http": 422, "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON.", "section": "1.3" }, { "http": 422, "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе.", "section": "1.3" }, { "http": 422, "field": "Имя лишнего поля", "code": "UNKNOWN_FIELD", "message": "Параметр не поддерживается этим методом.", "section": "1.3" }, { "http": 422, "field": "comment", "code": "INVALID_COMMENT", "message": "Комментарий должен быть строкой или null.", "section": "1.3" }, { "http": 422, "field": "name", "code": "REQUIRED", "message": "Укажите наименование контрагента.", "section": "6.6" }, { "http": 422, "field": "name", "code": "INVALID_NAME", "message": "Наименование контрагента должно быть строкой длиной от 1 до 300 символов.", "section": "6.6" }, { "http": 422, "field": "inn", "code": "INVALID_INN", "message": "ИНН должен содержать 10 цифр для организации или 12 цифр для ИП.", "section": "6.6" }, { "http": 422, "field": "inn", "code": "INVALID_INN_CHECKSUM", "message": "Некорректный ИНН: не совпадает контрольное число.", "section": "6.6" }, { "http": 422, "field": "inn", "code": "INN_REQUIRED_FOR_KPP", "message": "Укажите ИНН, если передан КПП.", "section": "6.6" }, { "http": 422, "field": "kpp", "code": "INVALID_KPP", "message": "КПП должен содержать 9 цифр.", "section": "6.6" }, { "http": 422, "field": "kpp", "code": "KPP_REQUIRED", "message": "Требуется указать КПП.", "section": "6.6" }, { "http": 422, "field": "kpp", "code": "KPP_NOT_ALLOWED", "message": "Для ИП КПП не указывается.", "section": "6.6" }, { "http": 409, "field": "inn", "code": "COUNTERPARTY_DETAILS_CONFLICT", "message": "Контрагент с указанными ИНН и КПП либо ИНН ИП уже существует, но не сопоставлен с переданным source_id.", "section": "6.7" } ] } }, "/vehicles/{source_id}": { "put": { "operationId": "vehicles", "summary": "Создание или обновление автомобиля", "description": "Передача транспортного средства из 1С. Метод создаёт автомобиль по новому source_id либо обновляет марку, модель, госномер и комментарий существующей записи.", "tags": [ "vehicles" ], "x-docs-sections": [ { "number": "7.1", "title": "Адрес и параметры", "blocks": [ { "k": "p", "i": 298, "style": "Normal", "text": "Адрес: https://app.zaezdo.pro/api/v1/vehicles/{source_id}. Параметр source_id обязателен, передаётся в URL; ограничения — в разделе 1.1. Query-параметры не используются." }, { "k": "p", "i": 299, "style": "Normal", "text": "Тело запроса — объект JSON. Параметры ниже передаются как при создании, так и при обновлении." }, { "k": "table", "i": 300, "rows": [ [ "Параметр", "Обяз.", "Назначение" ], [ "make", "Да", "Марка автомобиля. Строка от 1 до 120 символов." ], [ "model", "Нет", "Модель. Строка до 120 символов." ], [ "plate_number", "Да", "Государственный номер. Строка от 1 до 30 символов." ], [ "comment", "Нет", "Комментарий. Строка; ограничение длины на уровне поля не установлено." ] ] } ] }, { "number": "7.2", "title": "Пример запроса", "blocks": [ { "k": "table", "i": 302, "rows": [ [ "PUT /api/v1/vehicles/VEH-0085 HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"make\": \"MAN\",\n \"model\": \"TGX\",\n \"plate_number\": \"А123ВС77\",\n \"comment\": \"Тягач\"\n}" ] ] } ] }, { "number": "7.3", "title": "Успешные ответы", "blocks": [ { "k": "p", "i": 305, "style": "Caption Custom", "text": "НОВАЯ ЗАПИСЬ · HTTP 201 CREATED" }, { "k": "table", "i": 306, "rows": [ [ "{\n \"id\": \"VEH-EXAMPLE001\",\n \"source_id\": \"VEH-0085\",\n \"created\": true,\n \"is_active\": true\n}" ] ] }, { "k": "p", "i": 308, "style": "Normal", "text": "Для существующего source_id возвращается HTTP 200 с тем же набором полей и created: false. Значение id сохраняется, остальные поля отражают результат операции. Если данные не изменились, ответ также 200 и created: false." }, { "k": "table", "i": 309, "rows": [ [ "Поле ответа", "Значение" ], [ "id", "Идентификатор записи в Заездо. Для последующих PUT и создания визита сохранять его не обязательно." ], [ "source_id", "Идентификатор из URL. Используйте его в соответствующем поле запроса visits." ], [ "created", "true — запись создана; false — обработана существующая запись." ], [ "is_active", "true — запись активна; false — отключена и не может использоваться для нового визита." ] ] } ] }, { "number": "7.4", "title": "Правила создания и обновления", "blocks": [ { "k": "p", "i": 311, "style": "Normal", "text": "Полные правила передачи значений и очистки необязательных полей приведены в разделе 1.1." }, { "k": "p", "i": 312, "style": "Normal", "text": "Обновляются только make, model, plate_number и comment. Активность автомобиля сохраняется." }, { "k": "p", "i": 313, "style": "Normal", "text": "Госномер передаётся строкой. Для проверки совпадений из номера удаляются пробелы и буквы приводятся к верхнему регистру. Кириллические и латинские буквы автоматически не подменяются; передавайте единообразное написание." }, { "k": "p", "i": 314, "style": "Normal", "text": "Если номер совпадает с номером другого автомобиля, возвращается 409. Совпадение марки и модели не используется для объединения записей." }, { "k": "p", "i": 315, "style": "Normal", "text": "Тип кузова, габариты, грузоподъёмность и привязка водителя в этот метод не входят. Автомобиль и водитель указываются отдельно при создании визита." } ] }, { "number": "7.5", "title": "Порядок проверки запроса", "blocks": [ { "k": "table", "i": 317, "rows": [ [ "Этап", "Результат" ], [ "1. Авторизация", "401 при проблеме с токеном; 403 при отключённой компании." ], [ "2. Чтение JSON", "415 при неверном Content-Type; 400 при нечитаемом JSON." ], [ "3. Проверка параметров", "422: в errors[] возвращаются все независимые ошибки обязательности, типов, длины и реквизитов." ], [ "4. Поиск и проверка конфликтов", "Запись ищется по source_id. Проверяются совпадения, описанные в правилах метода. При конфликте — 409; изменений нет." ], [ "5. Сохранение", "Если запись не найдена — создать и вернуть 201. Если найдена — обновить и вернуть 200. При отклонении запроса данные не меняются." ] ] }, { "k": "p", "i": 318, "style": "Normal", "text": "После ошибки следующий этап не выполняется. Ошибки параметров 422 и конфликты 409 не смешиваются. Отсутствие записи по source_id не даёт 404: это штатный случай создания." } ] }, { "number": "7.6", "title": "Коды и описания ошибок", "blocks": [ { "k": "p", "i": 320, "style": "Normal", "text": "Общие HTTP-коды, верхнеуровневые message и ошибки source_id, JSON, лишних полей и comment приведены в разделах 1.2–1.3. Ниже — точные значения errors[].message этого метода." }, { "k": "table", "i": 321, "rows": [ [ "HTTP · field / code", "Точное значение errors[].message" ], [ "422 · make\nREQUIRED", "Укажите марку автомобиля." ], [ "422 · make\nINVALID_MAKE", "Марка автомобиля должна быть строкой длиной от 1 до 120 символов." ], [ "422 · model\nINVALID_MODEL", "Модель автомобиля должна быть строкой длиной не более 120 символов или null." ], [ "422 · plate_number\nREQUIRED", "Укажите государственный номер автомобиля." ], [ "422 · plate_number\nINVALID_PLATE_NUMBER", "Государственный номер должен быть строкой длиной от 1 до 30 символов." ] ] } ] }, { "number": "7.7", "title": "Конфликт записей · HTTP 409", "blocks": [ { "k": "p", "i": 323, "style": "Normal", "text": "Верхнеуровневый код — RESOURCE_CONFLICT; сообщение — «Невозможно сохранить запись из-за конфликта данных.». В errors[] возвращается:" }, { "k": "table", "i": 324, "rows": [ [ "field / code", "Точное значение errors[].message" ], [ "plate_number\nVEHICLE_PLATE_CONFLICT", "Автомобиль с указанным государственным номером уже существует, но не сопоставлен с переданным source_id." ] ] }, { "k": "p", "i": 325, "style": "Caption Custom", "text": "ПРИМЕР ОТВЕТА · HTTP 409" }, { "k": "table", "i": 326, "rows": [ [ "{\n \"code\": \"RESOURCE_CONFLICT\",\n \"message\": \"Невозможно сохранить запись из-за конфликта данных.\",\n \"errors\": [\n {\n \"field\": \"plate_number\",\n \"code\": \"VEHICLE_PLATE_CONFLICT\",\n \"message\": \"Автомобиль с указанным государственным номером уже существует, но не сопоставлен с переданным source_id.\"\n }\n ],\n \"request_id\": \"req-vehicles-conflict\"\n}" ] ] } ] }, { "number": "7.8", "title": "Пример ошибки параметров", "blocks": [ { "k": "p", "i": 329, "style": "Caption Custom", "text": "HTTP 422 · НЕСКОЛЬКО ОШИБОК В ОДНОМ ОТВЕТЕ" }, { "k": "table", "i": 330, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки данных справочника.\",\n \"errors\": [\n {\n \"field\": \"make\",\n \"code\": \"REQUIRED\",\n \"message\": \"Укажите марку автомобиля.\"\n },\n {\n \"field\": \"plate_number\",\n \"code\": \"REQUIRED\",\n \"message\": \"Укажите государственный номер автомобиля.\"\n }\n ],\n \"request_id\": \"req-vehicles-validation\"\n}" ] ] }, { "k": "p", "i": 332, "style": "Normal", "text": "Покажите все errors[].message, исправьте перечисленные поля и повторите PUT с тем же source_id. При 409 сначала разрешите конфликт; при 500, 503 или потере ответа повторяйте прежний запрос после паузы." } ] }, { "number": "7.9", "title": "Пример использования для 1С", "blocks": [ { "k": "p", "i": 334, "style": "Normal", "text": "Передайте автомобиль VEH-0085 отдельным PUT-запросом. При 201 или 200 и is_active: true его идентификатор можно включить в visits. Если автомобиль пока неизвестен, этот PUT не выполняется, а vehicle_source_id в визите не передаётся." }, { "k": "p", "i": 335, "style": "Caption Custom", "text": "ФРАГМЕНТ ЗАПРОСА POST /api/v1/visits" }, { "k": "table", "i": 336, "rows": [ [ "{\n \"vehicle_source_id\": \"VEH-0085\"\n}" ] ] }, { "k": "p", "i": 338, "style": "Normal", "text": "Если реквизиты автомобиля изменились, отправьте новый полный набор полей с прежним source_id. Не заменяйте source_id государственным номером: номер может измениться, а соответствие записи должно сохраниться." } ] } ], "x-docs-id": "vehicles", "x-docs-number": 7, "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?!.*[\\x00-\\x1F\\x7F/\\\\])(?:\\S|.*\\S)$", "description": "Идентификатор записи во внешней системе. Строка от 1 до 80 символов; регистр учитывается. Запрещены управляющие символы, пробелы по краям и разделители / и \\." }, "example": "VEH-0085" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "make": { "type": "string", "description": "Марка автомобиля. Строка от 1 до 120 символов.", "minLength": 1, "maxLength": 120 }, "model": { "type": [ "string", "null" ], "description": "Модель. Строка до 120 символов.", "maxLength": 120 }, "plate_number": { "type": "string", "description": "Государственный номер. Строка от 1 до 30 символов.", "minLength": 1, "maxLength": 30 }, "comment": { "type": [ "string", "null" ], "description": "Комментарий. Строка; ограничение длины на уровне поля не установлено." } }, "required": [ "make", "plate_number" ], "additionalProperties": false }, "example": { "make": "MAN", "model": "TGX", "plate_number": "А123ВС77", "comment": "Тягач" } } } }, "x-request-http": "PUT /api/v1/vehicles/VEH-0085 HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"make\": \"MAN\",\n \"model\": \"TGX\",\n \"plate_number\": \"А123ВС77\",\n \"comment\": \"Тягач\"\n}", "responses": { "201": { "description": "Создано", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "required": [ "id", "source_id", "created", "is_active" ] }, "examples": { "default": { "summary": "Создано", "value": { "id": "VEH-EXAMPLE001", "source_id": "VEH-0085", "created": true, "is_active": true } } } } } }, "200": { "description": "Обновлено / повтор", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "required": [ "id", "source_id", "created", "is_active" ] }, "examples": { "default": { "summary": "Обновлено / повтор", "value": { "id": "VEH-EXAMPLE001", "source_id": "VEH-0085", "created": false, "is_active": true } } } } } }, "400": { "description": "Не удалось прочитать JSON тела запроса.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса.", "request_id": "req-example-400" } } } }, "401": { "description": "Требуется действующий Bearer-токен интеграции.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции.", "request_id": "req-example-401" } } } }, "403": { "description": "Компания отключена в Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо.", "request_id": "req-example-403" } } } }, "409": { "description": "Невозможно сохранить запись из-за конфликта данных.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных.", "request_id": "req-example-409", "errors": [ { "field": "plate_number", "code": "VEHICLE_PLATE_CONFLICT", "message": "Автомобиль с указанным государственным номером уже существует, но не сопоставлен с переданным source_id." } ] } } } }, "415": { "description": "Передайте тело запроса с Content-Type: application/json.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json.", "request_id": "req-example-415" } } } }, "422": { "description": "Ошибка проверки данных справочника.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника.", "request_id": "req-example-422", "errors": [ { "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON." }, { "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе." } ] } } } }, "429": { "description": "Превышено допустимое количество запросов. Повторите запрос позже.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже.", "request_id": "req-example-429" } } }, "headers": { "Retry-After": { "description": "Время ожидания перед повторным запросом.", "schema": { "type": "string" } } } }, "500": { "description": "Внутренняя ошибка Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо.", "request_id": "req-example-500" } } } }, "503": { "description": "Сервис Заездо временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен.", "request_id": "req-example-503" } } } } }, "x-http-errors": [ { "http": 400, "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса." }, { "http": 401, "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции." }, { "http": 403, "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо." }, { "http": 409, "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных." }, { "http": 415, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json." }, { "http": 422, "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника." }, { "http": 429, "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже." }, { "http": 500, "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо." }, { "http": 503, "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен." } ], "x-field-errors": [ { "http": 422, "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON.", "section": "1.3" }, { "http": 422, "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе.", "section": "1.3" }, { "http": 422, "field": "Имя лишнего поля", "code": "UNKNOWN_FIELD", "message": "Параметр не поддерживается этим методом.", "section": "1.3" }, { "http": 422, "field": "comment", "code": "INVALID_COMMENT", "message": "Комментарий должен быть строкой или null.", "section": "1.3" }, { "http": 422, "field": "make", "code": "REQUIRED", "message": "Укажите марку автомобиля.", "section": "7.6" }, { "http": 422, "field": "make", "code": "INVALID_MAKE", "message": "Марка автомобиля должна быть строкой длиной от 1 до 120 символов.", "section": "7.6" }, { "http": 422, "field": "model", "code": "INVALID_MODEL", "message": "Модель автомобиля должна быть строкой длиной не более 120 символов или null.", "section": "7.6" }, { "http": 422, "field": "plate_number", "code": "REQUIRED", "message": "Укажите государственный номер автомобиля.", "section": "7.6" }, { "http": 422, "field": "plate_number", "code": "INVALID_PLATE_NUMBER", "message": "Государственный номер должен быть строкой длиной от 1 до 30 символов.", "section": "7.6" }, { "http": 409, "field": "plate_number", "code": "VEHICLE_PLATE_CONFLICT", "message": "Автомобиль с указанным государственным номером уже существует, но не сопоставлен с переданным source_id.", "section": "7.7" } ] } }, "/drivers/{source_id}": { "put": { "operationId": "drivers", "summary": "Создание или обновление водителя", "description": "Передача водителя из 1С. Метод создаёт запись по новому source_id либо обновляет ФИО, сведения о документах и комментарий. Это справочник водителей, а не пользователей Заездо: учётная запись и роли не создаются.", "tags": [ "drivers" ], "x-docs-sections": [ { "number": "8.1", "title": "Адрес и параметры", "blocks": [ { "k": "p", "i": 346, "style": "Normal", "text": "Адрес: https://app.zaezdo.pro/api/v1/drivers/{source_id}. Параметр source_id обязателен, передаётся в URL; ограничения — в разделе 1.1. Query-параметры не используются." }, { "k": "p", "i": 347, "style": "Normal", "text": "Тело запроса — объект JSON. Параметры ниже передаются как при создании, так и при обновлении." }, { "k": "table", "i": 348, "rows": [ [ "Параметр", "Обяз.", "Назначение" ], [ "last_name", "Да", "Фамилия. Строка от 1 до 120 символов." ], [ "first_name", "Да", "Имя. Строка от 1 до 120 символов." ], [ "middle_name", "Нет", "Отчество. Строка до 120 символов." ], [ "license_series", "Нет", "Серия водительского удостоверения. Строка до 30 символов." ], [ "license_number", "Нет", "Номер водительского удостоверения. Строка до 50 символов." ], [ "passport_series", "Нет", "Серия паспорта. Строка до 30 символов." ], [ "passport_number", "Нет", "Номер паспорта. Строка до 50 символов." ], [ "comment", "Нет", "Комментарий. Строка; ограничение длины на уровне поля не установлено." ] ] }, { "k": "p", "i": 349, "style": "Normal", "text": "Ограничения длины действуют для каждой части имени и документа отдельно. Общее ФИО после соединения частей — не более 300 символов." } ] }, { "number": "8.2", "title": "Пример запроса", "blocks": [ { "k": "table", "i": 351, "rows": [ [ "PUT /api/v1/drivers/DRV-0017 HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"last_name\": \"Иванов\",\n \"first_name\": \"Иван\",\n \"middle_name\": \"Иванович\",\n \"license_series\": \"77 15\",\n \"license_number\": \"123456\",\n \"passport_series\": \"4510\",\n \"passport_number\": \"123456\",\n \"comment\": \"\"\n}" ] ] } ] }, { "number": "8.3", "title": "Успешные ответы", "blocks": [ { "k": "p", "i": 354, "style": "Caption Custom", "text": "НОВАЯ ЗАПИСЬ · HTTP 201 CREATED" }, { "k": "table", "i": 355, "rows": [ [ "{\n \"id\": \"DRV-EXAMPLE001\",\n \"source_id\": \"DRV-0017\",\n \"created\": true,\n \"is_active\": true,\n \"full_name\": \"Иванов Иван Иванович\"\n}" ] ] }, { "k": "p", "i": 357, "style": "Normal", "text": "Для существующего source_id возвращается HTTP 200 с тем же набором полей и created: false. Значение id сохраняется, остальные поля отражают результат операции. Если данные не изменились, ответ также 200 и created: false." }, { "k": "table", "i": 358, "rows": [ [ "Поле ответа", "Значение" ], [ "id", "Идентификатор записи в Заездо. Для последующих PUT и создания визита сохранять его не обязательно." ], [ "source_id", "Идентификатор из URL. Используйте его в соответствующем поле запроса visits." ], [ "created", "true — запись создана; false — обработана существующая запись." ], [ "is_active", "true — запись активна; false — отключена и не может использоваться для нового визита." ], [ "full_name", "ФИО, сформированное из last_name, first_name и заполненного middle_name через пробел." ] ] } ] }, { "number": "8.4", "title": "Правила создания и обновления", "blocks": [ { "k": "p", "i": 360, "style": "Normal", "text": "Полные правила передачи значений и очистки необязательных полей приведены в разделе 1.1." }, { "k": "p", "i": 361, "style": "Normal", "text": "full_name формируется самим Заездо. В запросе передаются отдельные части имени. Длина собранного ФИО не должна превышать 300 символов." }, { "k": "p", "i": 362, "style": "Normal", "text": "Паспорт и водительское удостоверение необязательны. Передавайте серии и номера строками, чтобы сохранить ведущие нули. Телефоны и email этим методом не передаются." }, { "k": "p", "i": 363, "style": "Normal", "text": "Если заполнены серия и номер одного документа, их пара проверяется на совпадение с документом другого водителя. Сравнение выполняется без пробелов и без учёта регистра. Совпадение по любому из двух документов даёт 409." }, { "k": "p", "i": 364, "style": "Normal", "text": "Если полных реквизитов документов нет, сопоставление возможно только по source_id. Одинаковое ФИО не используется для автоматического объединения водителей." }, { "k": "p", "i": 365, "style": "Normal", "text": "Активность водителя сохраняется. Передача его сведений не создаёт права входа в Заездо и не назначает его ответственным менеджером." } ] }, { "number": "8.5", "title": "Порядок проверки запроса", "blocks": [ { "k": "table", "i": 367, "rows": [ [ "Этап", "Результат" ], [ "1. Авторизация", "401 при проблеме с токеном; 403 при отключённой компании." ], [ "2. Чтение JSON", "415 при неверном Content-Type; 400 при нечитаемом JSON." ], [ "3. Проверка параметров", "422: в errors[] возвращаются все независимые ошибки обязательности, типов, длины и реквизитов." ], [ "4. Поиск и проверка конфликтов", "Запись ищется по source_id. Проверяются совпадения, описанные в правилах метода. При конфликте — 409; изменений нет." ], [ "5. Сохранение", "Если запись не найдена — создать и вернуть 201. Если найдена — обновить и вернуть 200. При отклонении запроса данные не меняются." ] ] }, { "k": "p", "i": 368, "style": "Normal", "text": "После ошибки следующий этап не выполняется. Ошибки параметров 422 и конфликты 409 не смешиваются. Отсутствие записи по source_id не даёт 404: это штатный случай создания." } ] }, { "number": "8.6", "title": "Коды и описания ошибок", "blocks": [ { "k": "p", "i": 370, "style": "Normal", "text": "Общие HTTP-коды, верхнеуровневые message и ошибки source_id, JSON, лишних полей и comment приведены в разделах 1.2–1.3. Ниже — точные значения errors[].message этого метода." }, { "k": "table", "i": 371, "rows": [ [ "HTTP · field / code", "Точное значение errors[].message" ], [ "422 · last_name\nREQUIRED", "Укажите фамилию водителя." ], [ "422 · last_name\nINVALID_LAST_NAME", "Фамилия должна быть строкой длиной от 1 до 120 символов." ], [ "422 · first_name\nREQUIRED", "Укажите имя водителя." ], [ "422 · first_name\nINVALID_FIRST_NAME", "Имя должно быть строкой длиной от 1 до 120 символов." ], [ "422 · middle_name\nINVALID_MIDDLE_NAME", "Отчество должно быть строкой длиной не более 120 символов или null." ], [ "422 · $\nFULL_NAME_TOO_LONG", "ФИО, составленное из фамилии, имени и отчества, не должно превышать 300 символов." ], [ "422 · license_series\nINVALID_LICENSE_SERIES", "Серия водительского удостоверения должна быть строкой длиной не более 30 символов или null." ], [ "422 · license_number\nINVALID_LICENSE_NUMBER", "Номер водительского удостоверения должен быть строкой длиной не более 50 символов или null." ], [ "422 · passport_series\nINVALID_PASSPORT_SERIES", "Серия паспорта должна быть строкой длиной не более 30 символов или null." ], [ "422 · passport_number\nINVALID_PASSPORT_NUMBER", "Номер паспорта должен быть строкой длиной не более 50 символов или null." ] ] } ] }, { "number": "8.7", "title": "Конфликт записей · HTTP 409", "blocks": [ { "k": "p", "i": 373, "style": "Normal", "text": "Верхнеуровневый код — RESOURCE_CONFLICT; сообщение — «Невозможно сохранить запись из-за конфликта данных.». В errors[] возвращается:" }, { "k": "table", "i": 374, "rows": [ [ "field / code", "Точное значение errors[].message" ], [ "license_number или passport_number\nDRIVER_DOCUMENT_CONFLICT", "Водитель с указанными серией и номером документа уже существует, но не сопоставлен с переданным source_id." ] ] }, { "k": "p", "i": 375, "style": "Normal", "text": "При совпадении удостоверения field = license_number; при совпадении паспорта — passport_number. Если обнаружены оба конфликта, в errors[] возвращаются два элемента с одинаковым code и соответствующими field." }, { "k": "p", "i": 376, "style": "Caption Custom", "text": "ПРИМЕР ОТВЕТА · HTTP 409" }, { "k": "table", "i": 377, "rows": [ [ "{\n \"code\": \"RESOURCE_CONFLICT\",\n \"message\": \"Невозможно сохранить запись из-за конфликта данных.\",\n \"errors\": [\n {\n \"field\": \"license_number\",\n \"code\": \"DRIVER_DOCUMENT_CONFLICT\",\n \"message\": \"Водитель с указанными серией и номером документа уже существует, но не сопоставлен с переданным source_id.\"\n }\n ],\n \"request_id\": \"req-drivers-conflict\"\n}" ] ] } ] }, { "number": "8.8", "title": "Пример ошибки параметров", "blocks": [ { "k": "p", "i": 380, "style": "Caption Custom", "text": "HTTP 422 · НЕСКОЛЬКО ОШИБОК В ОДНОМ ОТВЕТЕ" }, { "k": "table", "i": 381, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки данных справочника.\",\n \"errors\": [\n {\n \"field\": \"last_name\",\n \"code\": \"REQUIRED\",\n \"message\": \"Укажите фамилию водителя.\"\n },\n {\n \"field\": \"first_name\",\n \"code\": \"REQUIRED\",\n \"message\": \"Укажите имя водителя.\"\n }\n ],\n \"request_id\": \"req-drivers-validation\"\n}" ] ] }, { "k": "p", "i": 383, "style": "Normal", "text": "Покажите все errors[].message, исправьте перечисленные поля и повторите PUT с тем же source_id. При 409 сначала разрешите конфликт; при 500, 503 или потере ответа повторяйте прежний запрос после паузы." } ] }, { "number": "8.9", "title": "Пример использования для 1С", "blocks": [ { "k": "p", "i": 385, "style": "Normal", "text": "Передайте водителя DRV-0017 отдельным PUT-запросом. При 201 или 200 и is_active: true используйте DRV-0017 в визите. Если водитель ещё не известен, его предварительная передача не требуется: driver_source_id можно опустить." }, { "k": "p", "i": 386, "style": "Caption Custom", "text": "ФРАГМЕНТ ЗАПРОСА POST /api/v1/visits" }, { "k": "table", "i": 387, "rows": [ [ "{\n \"driver_source_id\": \"DRV-0017\"\n}" ] ] }, { "k": "p", "i": 389, "style": "Normal", "text": "При уточнении документов или ФИО используйте тот же source_id и передайте полный набор сохраняемых полей. Если паспортные сведения не должны храниться, передайте passport_series: null и passport_number: null; остальные сохраняемые реквизиты повторите." } ] } ], "x-docs-id": "drivers", "x-docs-number": 8, "parameters": [ { "name": "source_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^(?!\\s)(?!.*[\\x00-\\x1F\\x7F/\\\\])(?:\\S|.*\\S)$", "description": "Идентификатор записи во внешней системе. Строка от 1 до 80 символов; регистр учитывается. Запрещены управляющие символы, пробелы по краям и разделители / и \\." }, "example": "DRV-0017" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "last_name": { "type": "string", "description": "Фамилия. Строка от 1 до 120 символов.", "minLength": 1, "maxLength": 120 }, "first_name": { "type": "string", "description": "Имя. Строка от 1 до 120 символов.", "minLength": 1, "maxLength": 120 }, "middle_name": { "type": [ "string", "null" ], "description": "Отчество. Строка до 120 символов.", "maxLength": 120 }, "license_series": { "type": [ "string", "null" ], "description": "Серия водительского удостоверения. Строка до 30 символов.", "maxLength": 30 }, "license_number": { "type": [ "string", "null" ], "description": "Номер водительского удостоверения. Строка до 50 символов.", "maxLength": 50 }, "passport_series": { "type": [ "string", "null" ], "description": "Серия паспорта. Строка до 30 символов.", "maxLength": 30 }, "passport_number": { "type": [ "string", "null" ], "description": "Номер паспорта. Строка до 50 символов.", "maxLength": 50 }, "comment": { "type": [ "string", "null" ], "description": "Комментарий. Строка; ограничение длины на уровне поля не установлено." } }, "required": [ "last_name", "first_name" ], "additionalProperties": false }, "example": { "last_name": "Иванов", "first_name": "Иван", "middle_name": "Иванович", "license_series": "77 15", "license_number": "123456", "passport_series": "4510", "passport_number": "123456", "comment": "" } } } }, "x-request-http": "PUT /api/v1/drivers/DRV-0017 HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"last_name\": \"Иванов\",\n \"first_name\": \"Иван\",\n \"middle_name\": \"Иванович\",\n \"license_series\": \"77 15\",\n \"license_number\": \"123456\",\n \"passport_series\": \"4510\",\n \"passport_number\": \"123456\",\n \"comment\": \"\"\n}", "responses": { "201": { "description": "Создано", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" }, "full_name": { "type": "string" } }, "required": [ "id", "source_id", "created", "is_active", "full_name" ] }, "examples": { "default": { "summary": "Создано", "value": { "id": "DRV-EXAMPLE001", "source_id": "DRV-0017", "created": true, "is_active": true, "full_name": "Иванов Иван Иванович" } } } } } }, "200": { "description": "Обновлено / повтор", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "source_id": { "type": "string" }, "created": { "type": "boolean" }, "is_active": { "type": "boolean" }, "full_name": { "type": "string" } }, "required": [ "id", "source_id", "created", "is_active", "full_name" ] }, "examples": { "default": { "summary": "Обновлено / повтор", "value": { "id": "DRV-EXAMPLE001", "source_id": "DRV-0017", "created": false, "is_active": true, "full_name": "Иванов Иван Иванович" } } } } } }, "400": { "description": "Не удалось прочитать JSON тела запроса.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса.", "request_id": "req-example-400" } } } }, "401": { "description": "Требуется действующий Bearer-токен интеграции.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции.", "request_id": "req-example-401" } } } }, "403": { "description": "Компания отключена в Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо.", "request_id": "req-example-403" } } } }, "409": { "description": "Невозможно сохранить запись из-за конфликта данных.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных.", "request_id": "req-example-409", "errors": [ { "field": "license_number или passport_number", "code": "DRIVER_DOCUMENT_CONFLICT", "message": "Водитель с указанными серией и номером документа уже существует, но не сопоставлен с переданным source_id." } ] } } } }, "415": { "description": "Передайте тело запроса с Content-Type: application/json.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json.", "request_id": "req-example-415" } } } }, "422": { "description": "Ошибка проверки данных справочника.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника.", "request_id": "req-example-422", "errors": [ { "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON." }, { "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе." } ] } } } }, "429": { "description": "Превышено допустимое количество запросов. Повторите запрос позже.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже.", "request_id": "req-example-429" } } }, "headers": { "Retry-After": { "description": "Время ожидания перед повторным запросом.", "schema": { "type": "string" } } } }, "500": { "description": "Внутренняя ошибка Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо.", "request_id": "req-example-500" } } } }, "503": { "description": "Сервис Заездо временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен.", "request_id": "req-example-503" } } } } }, "x-http-errors": [ { "http": 400, "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса." }, { "http": 401, "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции." }, { "http": 403, "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо." }, { "http": 409, "code": "RESOURCE_CONFLICT", "message": "Невозможно сохранить запись из-за конфликта данных." }, { "http": 415, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json." }, { "http": 422, "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных справочника." }, { "http": 429, "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже." }, { "http": 500, "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо." }, { "http": 503, "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен." } ], "x-field-errors": [ { "http": 422, "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON.", "section": "1.3" }, { "http": 422, "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе.", "section": "1.3" }, { "http": 422, "field": "Имя лишнего поля", "code": "UNKNOWN_FIELD", "message": "Параметр не поддерживается этим методом.", "section": "1.3" }, { "http": 422, "field": "comment", "code": "INVALID_COMMENT", "message": "Комментарий должен быть строкой или null.", "section": "1.3" }, { "http": 422, "field": "last_name", "code": "REQUIRED", "message": "Укажите фамилию водителя.", "section": "8.6" }, { "http": 422, "field": "last_name", "code": "INVALID_LAST_NAME", "message": "Фамилия должна быть строкой длиной от 1 до 120 символов.", "section": "8.6" }, { "http": 422, "field": "first_name", "code": "REQUIRED", "message": "Укажите имя водителя.", "section": "8.6" }, { "http": 422, "field": "first_name", "code": "INVALID_FIRST_NAME", "message": "Имя должно быть строкой длиной от 1 до 120 символов.", "section": "8.6" }, { "http": 422, "field": "middle_name", "code": "INVALID_MIDDLE_NAME", "message": "Отчество должно быть строкой длиной не более 120 символов или null.", "section": "8.6" }, { "http": 422, "field": "$", "code": "FULL_NAME_TOO_LONG", "message": "ФИО, составленное из фамилии, имени и отчества, не должно превышать 300 символов.", "section": "8.6" }, { "http": 422, "field": "license_series", "code": "INVALID_LICENSE_SERIES", "message": "Серия водительского удостоверения должна быть строкой длиной не более 30 символов или null.", "section": "8.6" }, { "http": 422, "field": "license_number", "code": "INVALID_LICENSE_NUMBER", "message": "Номер водительского удостоверения должен быть строкой длиной не более 50 символов или null.", "section": "8.6" }, { "http": 422, "field": "passport_series", "code": "INVALID_PASSPORT_SERIES", "message": "Серия паспорта должна быть строкой длиной не более 30 символов или null.", "section": "8.6" }, { "http": 422, "field": "passport_number", "code": "INVALID_PASSPORT_NUMBER", "message": "Номер паспорта должен быть строкой длиной не более 50 символов или null.", "section": "8.6" }, { "http": 409, "field": "license_number или passport_number", "code": "DRIVER_DOCUMENT_CONFLICT", "message": "Водитель с указанными серией и номером документа уже существует, но не сопоставлен с переданным source_id.", "section": "8.7" } ] } }, "/visits": { "post": { "operationId": "visits", "summary": "Создание визита", "description": "Создание визита транспорта на площадке Заездо с использованием ранее синхронизированных справочников и ответственного менеджера. Метод не создаёт площадки, контрагентов, автомобили или водителей.", "tags": [ "visits" ], "x-docs-sections": [ { "number": "9.1", "title": "Адрес и назначение", "blocks": [ { "k": "p", "i": 397, "style": "Caption Custom", "text": "АДРЕС ЗАПРОСА" }, { "k": "table", "i": 398, "rows": [ [ "POST https://app.zaezdo.pro/api/v1/visits\nContent-Type: application/json" ] ] }, { "k": "p", "i": 399, "style": "Normal", "text": "Передайте внешние идентификаторы заранее подготовленных площадки, контрагента и, если используются, автомобиля и водителя. Ответственного сопоставьте в карточке пользователя через поле «Идентификатор для синхронизации с 1С»." } ] }, { "number": "9.2", "title": "Входные параметры", "blocks": [ { "k": "p", "i": 401, "style": "Normal", "text": "Тело запроса передается в формате JSON. В *_source_id передаются идентификаторы из внешней системы." }, { "k": "table", "i": 402, "rows": [ [ "Параметр", "Обяз.", "Назначение" ], [ "external_id", "Да", "Постоянный ID визита во внешней системе, до 80 символов." ], [ "site_source_id", "Да", "ID площадки во внешней системе." ], [ "planned_arrival_at", "Да", "Дата и время прибытия в формате ГГГГ-ММ-ДД ЧЧ:ММ." ], [ "purpose", "Да", "Цель визита: LOADING — «Погрузка»; UNLOADING — «Разгрузка»; SERVICE — «Служебный визит»; OTHER — «Другое»." ], [ "counterparty_source_id", "Да", "ID ранее зарегистрированного контрагента." ], [ "responsible_user_source_id", "Да", "ID пользователя в 1С, сопоставленного с пользователем Заездо. Назначается ответственным за визит после проверки его прав." ], [ "vehicle_source_id", "Нет", "ID автомобиля, если он известен на этапе планирования." ], [ "driver_source_id", "Нет", "ID водителя, если он известен на этапе планирования." ], [ "basis", "Нет", "Основание визита, не более 500 символов." ] ] } ] }, { "number": "9.3", "title": "Пример запроса", "blocks": [ { "k": "p", "i": 405, "style": "Caption Custom", "text": "СОЗДАНИЕ ВИЗИТА НА СКЛАДЕ WH-SEVER" }, { "k": "table", "i": 406, "rows": [ [ "{\n \"external_id\": \"ТД00-000015\",\n \"site_source_id\": \"WH-SEVER\",\n \"planned_arrival_at\": \"2026-11-03 10:30\",\n \"purpose\": \"UNLOADING\",\n \"counterparty_source_id\": \"CP-0042\",\n \"responsible_user_source_id\": \"AfoninGA\",\n \"vehicle_source_id\": \"VEH-0085\",\n \"driver_source_id\": \"DRV-0017\",\n \"basis\": \"Поставка по заявке №123\"\n}" ] ] }, { "k": "p", "i": 408, "style": "Normal", "text": "vehicle_source_id и driver_source_id можно не передавать. Если они указаны, соответствующие автомобиль и водитель должны существовать и быть активны." } ] }, { "number": "9.4", "title": "Успешные ответы", "blocks": [ { "k": "p", "i": 410, "style": "Caption Custom", "text": "ПЕРВОЕ СОЗДАНИЕ · HTTP 201 CREATED" }, { "k": "table", "i": 411, "rows": [ [ "{\n \"id\": \"VST-EXAMPLE001\",\n \"external_id\": \"ТД00-000015\",\n \"created\": true,\n \"status\": \"PLANNED\",\n \"admission_status\": \"UNDEFINED\"\n}" ] ] }, { "k": "p", "i": 413, "style": "Normal", "text": "При первом создании визита status = PLANNED («Запланирован»). Значение admission_status зависит от поля «Допуск на площадку» в карточке площадки: UNDEFINED («Не определён») при режиме «Требует ручной проверки»; ALLOWED («Разрешён») при режиме «Разрешен при наличии сведений»." }, { "k": "p", "i": 414, "style": "Caption Custom", "text": "ПОВТОР ТОГО ЖЕ ЗАПРОСА · HTTP 200 OK" }, { "k": "table", "i": 415, "rows": [ [ "{\n \"id\": \"VST-EXAMPLE001\",\n \"external_id\": \"ТД00-000015\",\n \"created\": false,\n \"status\": \"PLANNED\",\n \"admission_status\": \"UNDEFINED\"\n}" ] ] } ] }, { "number": "9.5", "title": "Структура успешного ответа", "blocks": [ { "k": "table", "i": 417, "rows": [ [ "Поле", "Значение" ], [ "id", "Внутренний идентификатор созданного визита в Заездо." ], [ "external_id", "Идентификатор визита во внешней системе, полученный в запросе." ], [ "created", "true — создан новый; false — возвращён уже существующий." ], [ "status", "Статус визита. При первом создании — PLANNED («Запланирован»); при повторе — актуальное значение." ], [ "admission_status", "Статус допуска. При создании — UNDEFINED («Не определён») или ALLOWED («Разрешён»); в дальнейшем возможны DENIED («Запрещён») и REVOKED («Отозван»)." ] ] }, { "k": "p", "i": 418, "style": "Caption Custom", "text": "ДОПУСТИМЫЕ ЗНАЧЕНИЯ ADMISSION_STATUS" }, { "k": "table", "i": 419, "rows": [ [ "Значение", "Описание", "При создании" ], [ "UNDEFINED", "Допуск не определён; требуется решение по допуску.", "Устанавливается, если в карточке площадки поле «Допуск на площадку» имеет значение «Требует ручной проверки»." ], [ "ALLOWED", "Допуск разрешён.", "Устанавливается, если в карточке площадки поле «Допуск на площадку» имеет значение «Разрешен при наличии сведений»." ], [ "DENIED", "Допуск запрещён.", "Нет" ], [ "REVOKED", "Ранее выданный допуск отозван.", "Нет" ] ] }, { "k": "p", "i": 421, "style": "Normal", "text": "После создания визита статус допуска может изменяться по действующим правилам Заездо; повторный запрос возвращает актуальный статус существующего визита." } ] }, { "number": "9.6", "title": "Правила создания визита", "blocks": [ { "k": "p", "i": 423, "style": "Bullet Custom", "text": "• Справочники предварительно синхронизируются отдельными PUT-методами. Создание визита не создаёт и не обновляет вложенные сущности." }, { "k": "p", "i": 424, "style": "Bullet Custom", "text": "• Площадка и контрагент должны существовать и быть активными. Автомобиль и водитель необязательны, но если переданы — тоже должны быть найдены и активны." }, { "k": "p", "i": 425, "style": "Bullet Custom", "text": "• Ответственный обязателен: пользователь активен, имеет действующую учётную запись, роль MANAGER и доступ менеджера к указанной площадке." }, { "k": "p", "i": 426, "style": "Bullet Custom", "text": "• Метод проверяет, может ли указанный пользователь быть ответственным за визит на выбранной площадке." }, { "k": "p", "i": 427, "style": "Bullet Custom", "text": "• Отсутствие настроенных мест обслуживания, зон ожидания, сотрудников КПП и табло само по себе не блокирует создание визита." }, { "k": "p", "i": 428, "style": "Bullet Custom", "text": "• Если запрос отклонён при проверке, визит не создаётся. Ранее созданные справочники остаются без изменений." }, { "k": "p", "i": 429, "style": "Bullet Custom", "text": "• Начальный статус — PLANNED («Запланирован»); допуск определяется правилами площадки." } ] }, { "number": "9.7", "title": "Порядок проверки запроса", "blocks": [ { "k": "p", "i": 431, "style": "Normal", "text": "Метод использует внешний идентификатор площадки, контрагента и ответственного пользователя, а также автомобиля и водителя, если они указаны. Проверка наличия этих записей выполняется отдельно от проверки параметров и возможности создания визита." }, { "k": "p", "i": 432, "style": "Normal", "text": "Запрос проходит этапы в порядке, указанном ниже. При ошибке возвращается HTTP-статус соответствующего этапа; последующие этапы не выполняются." }, { "k": "table", "i": 433, "rows": [ [ "Этап", "Результат" ], [ "1. Авторизация", "401 — нет действующего токена или интеграция отключена. 403 — компания отключена." ], [ "2. Чтение тела запроса", "415 — неверный Content-Type. 400 — JSON не удалось прочитать." ], [ "3. Проверка параметров", "422 — отсутствуют обязательные параметры, неверны тип, длина, формат даты или значение purpose. Поиск справочников ещё не выполняется." ], [ "4. Проверка повтора", "200 — этот визит уже создан по тому же исходному запросу. 409 — external_id уже использован с другими исходными данными." ], [ "5. Поиск записей справочников", "404 — не найдена площадка, контрагент, ответственный пользователь, указанный автомобиль или водитель. Возвращаются все ошибки поиска." ], [ "6. Проверка возможности создания", "422 — все записи найдены, но одна из них отключена, ответственного нельзя назначить или время прибытия прошло. Возвращаются все независимые нарушения этого этапа." ], [ "7. Создание визита", "201 — визит создан. Дальнейшая обработка визита выполняется в Заездо." ] ] }, { "k": "p", "i": 435, "style": "Normal", "text": "Обработка прекращается на первом этапе с ошибками. В errors[] перечисляются все обнаруженные ошибки только этого этапа. Ошибки поиска и проверки возможности создания не смешиваются в одном ответе." } ] }, { "number": "9.8", "title": "Как различать 404 и 422", "blocks": [ { "k": "p", "i": 437, "style": "Normal", "text": "404 — идентификатор передан корректно, но запись по нему не найдена. 422 — нужно исправить данные запроса либо условия, при которых допускается создание визита." }, { "k": "table", "i": 438, "rows": [ [ "Ситуация", "Ответ" ], [ "Не передан обязательный site_source_id.", "422 · REQUIRED" ], [ "site_source_id передан с неверным типом или превышает допустимую длину.", "422 · INVALID_SITE_SOURCE_ID" ], [ "site_source_id корректен, но площадки с таким идентификатором нет.", "404 · SITE_NOT_FOUND" ], [ "Площадка найдена, но отключена; все остальные переданные записи тоже найдены.", "422 · SITE_INACTIVE" ], [ "Площадка не найдена, а менеджер неактивен.", "Сначала 404 · SITE_NOT_FOUND. Активность менеджера проверяется после успешного поиска всех записей." ], [ "purpose некорректен, а контрагент не найден.", "Сначала 422 · INVALID_PURPOSE. Поиск контрагента начнётся после исправления параметров." ], [ "Дата корректна по формату, но уже прошла; площадка не найдена.", "Сначала 404 · SITE_NOT_FOUND. Проверка прошедшего времени выполняется после поиска." ], [ "Не найдены площадка и контрагент.", "Один ответ 404 с двумя элементами errors[]." ], [ "Все записи найдены; площадка отключена и время прибытия прошло.", "Один ответ 422 с двумя элементами errors[]." ] ] } ] }, { "number": "9.9", "title": "Коды и описания ошибок", "blocks": [ { "k": "p", "i": 441, "style": "Normal", "text": "Ниже приведены точные значения code и message. Подробности ошибок 404 и 422 находятся в массиве errors[]." }, { "k": "table", "i": 442, "rows": [ [ "HTTP", "code", "message" ], [ "400", "INVALID_JSON", "Не удалось прочитать JSON тела запроса." ], [ "401", "UNAUTHORIZED", "Требуется действующий Bearer-токен интеграции." ], [ "403", "TENANT_INACTIVE", "Компания отключена в Заездо." ], [ "404", "RESOURCE_NOT_FOUND", "Не найдены записи по переданным идентификаторам." ], [ "409", "VISIT_ALREADY_EXISTS", "Визит с указанным external_id уже существует с другими исходными данными." ], [ "415", "UNSUPPORTED_MEDIA_TYPE", "Передайте тело запроса с Content-Type: application/json." ], [ "422", "VALIDATION_ERROR", "Ошибка проверки данных визита." ], [ "429", "RATE_LIMITED", "Превышено допустимое количество запросов. Повторите запрос позже." ], [ "500", "INTERNAL_ERROR", "Внутренняя ошибка Заездо." ], [ "503", "SERVICE_UNAVAILABLE", "Сервис Заездо временно недоступен." ] ] }, { "k": "p", "i": 445, "style": "Normal", "text": "RESOURCE_NOT_FOUND относится к площадке, контрагенту, ответственному пользователю, автомобилю или водителю, указанным в запросе. Он не означает отсутствие создаваемого визита." } ] }, { "number": "9.10", "title": "Конкретные ошибки", "blocks": [ { "k": "p", "i": 447, "style": "Normal", "text": "Каждая строка задаёт одну ошибку: field — параметр запроса; code — её машинный код; message — точный текст. Если на этапе найдено несколько независимых ошибок, они возвращаются отдельными элементами errors[]." }, { "k": "p", "i": 448, "style": "Heading 3", "text": "9.10.1 Параметры запроса · HTTP 422" }, { "k": "p", "i": 449, "style": "Normal", "text": "На этом этапе не выполняются поиск записей, проверка их активности и прав менеджера. Для planned_arrival_at проверяются наличие и корректность даты и времени в формате ГГГГ-ММ-ДД ЧЧ:ММ, но не наступление указанного времени." }, { "k": "table", "i": 450, "rows": [ [ "errors[].field / errors[].code", "Точное значение errors[].message" ], [ "external_id\nREQUIRED", "Укажите идентификатор визита во внешней системе." ], [ "external_id\nINVALID_EXTERNAL_ID", "external_id должен быть строкой длиной от 1 до 80 символов." ], [ "site_source_id\nREQUIRED", "Укажите идентификатор площадки." ], [ "site_source_id\nINVALID_SITE_SOURCE_ID", "Идентификатор площадки должен быть строкой длиной от 1 до 80 символов." ], [ "counterparty_source_id\nREQUIRED", "Укажите идентификатор контрагента." ], [ "counterparty_source_id\nINVALID_COUNTERPARTY_SOURCE_ID", "Идентификатор контрагента должен быть строкой длиной от 1 до 80 символов." ], [ "responsible_user_source_id\nREQUIRED", "Укажите идентификатор ответственного менеджера." ], [ "responsible_user_source_id\nINVALID_RESPONSIBLE_USER_SOURCE_ID", "Идентификатор ответственного должен быть строкой длиной от 1 до 80 символов." ], [ "vehicle_source_id\nINVALID_VEHICLE_SOURCE_ID", "Идентификатор автомобиля должен быть строкой длиной от 1 до 80 символов." ], [ "driver_source_id\nINVALID_DRIVER_SOURCE_ID", "Идентификатор водителя должен быть строкой длиной от 1 до 80 символов." ], [ "planned_arrival_at\nREQUIRED", "Укажите плановую дату и время прибытия." ], [ "planned_arrival_at\nINVALID_DATETIME", "Передайте плановую дату и время в формате ГГГГ-ММ-ДД ЧЧ:ММ." ], [ "purpose\nREQUIRED", "Укажите цель визита." ], [ "purpose\nINVALID_PURPOSE", "Допустимые значения цели визита: LOADING, UNLOADING, SERVICE, OTHER." ], [ "basis\nINVALID_BASIS", "Основание визита должно быть строкой." ], [ "basis\nMAX_LENGTH_EXCEEDED", "Основание визита не должно превышать 500 символов." ] ] }, { "k": "p", "i": 452, "style": "Normal", "text": "Необязательные параметры vehicle_source_id, driver_source_id и basis можно не передавать. Для переданных значений действуют ограничения из таблицы." }, { "k": "p", "i": 453, "style": "Heading 3", "text": "9.10.2 Поиск записей справочников · HTTP 404" }, { "k": "p", "i": 454, "style": "Normal", "text": "Поиск начинается после успешной проверки параметров и отсутствия ранее выполненного запроса с тем же external_id. Все переданные идентификаторы проверяются независимо." }, { "k": "table", "i": 455, "rows": [ [ "errors[].field / errors[].code", "Точное значение errors[].message" ], [ "site_source_id\nSITE_NOT_FOUND", "Площадка с указанным site_source_id не найдена." ], [ "counterparty_source_id\nCOUNTERPARTY_NOT_FOUND", "Контрагент с указанным counterparty_source_id не найден." ], [ "responsible_user_source_id\nMANAGER_NOT_FOUND", "Пользователь с указанным responsible_user_source_id не найден." ], [ "vehicle_source_id\nVEHICLE_NOT_FOUND", "Автомобиль с указанным vehicle_source_id не найден." ], [ "driver_source_id\nDRIVER_NOT_FOUND", "Водитель с указанным driver_source_id не найден." ] ] }, { "k": "p", "i": 457, "style": "Normal", "text": "Автомобиль и водитель ищутся только при наличии vehicle_source_id и driver_source_id. Отключённая запись считается найденной. Если хотя бы одна запись не найдена, возвращается 404; проверка возможности создания в этом запросе не выполняется." }, { "k": "p", "i": 458, "style": "Heading 3", "text": "9.10.3 Возможность создания визита · HTTP 422" }, { "k": "p", "i": 459, "style": "Normal", "text": "Этот этап выполняется, только когда все указанные площадка, контрагент, ответственный пользователь, автомобиль и водитель найдены. В ответ включаются все независимые нарушения этого этапа." }, { "k": "table", "i": 460, "rows": [ [ "errors[].field / errors[].code", "Точное значение errors[].message" ], [ "site_source_id\nSITE_INACTIVE", "Площадка отключена." ], [ "counterparty_source_id\nCOUNTERPARTY_INACTIVE", "Контрагент отключён." ], [ "responsible_user_source_id\nMANAGER_INACTIVE", "Ответственный сотрудник отключён." ], [ "responsible_user_source_id\nMANAGER_NO_ACCOUNT", "У ответственного сотрудника нет действующей учётной записи в Заездо." ], [ "responsible_user_source_id\nMANAGER_NOT_MANAGER", "Ответственному сотруднику не назначена роль «Менеджер»." ], [ "responsible_user_source_id\nMANAGER_NO_SITE_ACCESS", "Ответственный менеджер не имеет доступа к указанной площадке." ], [ "vehicle_source_id\nVEHICLE_INACTIVE", "Автомобиль отключён." ], [ "driver_source_id\nDRIVER_INACTIVE", "Водитель отключён." ], [ "planned_arrival_at\nARRIVAL_IN_PAST", "Плановое время прибытия не может быть в прошлом." ] ] }, { "k": "p", "i": 462, "style": "Normal", "text": "Если у сотрудника вообще нет роли MANAGER, возвращается MANAGER_NOT_MANAGER; MANAGER_NO_SITE_ACCESS применяется, когда роль менеджера есть, но не действует на площадке визита." } ] }, { "number": "9.11", "title": "Формат ответа и примеры", "blocks": [ { "k": "table", "i": 464, "rows": [ [ "Поле", "Как использовать" ], [ "code", "Общая категория ошибки: например, RESOURCE_NOT_FOUND или VALIDATION_ERROR." ], [ "message", "Точное общее сообщение из таблицы 9.9." ], [ "errors[]", "Для 404 и 422: полный список ошибок остановившего этапа." ], [ "errors[].field", "Имя параметра запроса, к которому относится ошибка." ], [ "errors[].code", "Конкретная причина для программной обработки." ], [ "errors[].message", "Точный текст конкретной ошибки из раздела 9.10." ], [ "request_id", "Идентификатор запроса для обращения в поддержку." ] ] }, { "k": "p", "i": 466, "style": "Normal", "text": "В HTTP 404 и 422 возвращается один ответ с непустым массивом errors[]. Один ненайденный объект или одна ошибка — один элемент; несколько — несколько элементов. Верхнеуровневый код при этом не меняется." }, { "k": "p", "i": 467, "style": "Caption Custom", "text": "HTTP 404 · НЕ НАЙДЕНЫ ПЛОЩАДКА И КОНТРАГЕНТ" }, { "k": "table", "i": 468, "rows": [ [ "{\n \"code\": \"RESOURCE_NOT_FOUND\",\n \"message\": \"Не найдены записи по переданным идентификаторам.\",\n \"errors\": [\n {\n \"field\": \"site_source_id\",\n \"code\": \"SITE_NOT_FOUND\",\n \"message\": \"Площадка с указанным site_source_id не найдена.\"\n },\n {\n \"field\": \"counterparty_source_id\",\n \"code\": \"COUNTERPARTY_NOT_FOUND\",\n \"message\": \"Контрагент с указанным counterparty_source_id не найден.\"\n }\n ],\n \"request_id\": \"req-example-404\"\n}" ] ] }, { "k": "p", "i": 469, "style": "Heading 3", "text": "Примеры HTTP 422" }, { "k": "p", "i": 470, "style": "Caption Custom", "text": "ЭТАП ПАРАМЕТРОВ · НЕ УКАЗАНА ПЛОЩАДКА И НЕВЕРНАЯ ЦЕЛЬ" }, { "k": "table", "i": 471, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки данных визита.\",\n \"errors\": [\n {\n \"field\": \"site_source_id\",\n \"code\": \"REQUIRED\",\n \"message\": \"Укажите идентификатор площадки.\"\n },\n {\n \"field\": \"purpose\",\n \"code\": \"INVALID_PURPOSE\",\n \"message\": \"Допустимые значения цели визита: LOADING, UNLOADING, SERVICE, OTHER.\"\n }\n ],\n \"request_id\": \"req-example-format\"\n}" ] ] }, { "k": "p", "i": 472, "style": "Normal", "text": "Поиск справочников не выполнялся. После исправления параметров запрос нужно отправить заново." }, { "k": "p", "i": 473, "style": "Caption Custom", "text": "ЭТАП ВОЗМОЖНОСТИ СОЗДАНИЯ · ПЛОЩАДКА ОТКЛЮЧЕНА И ВРЕМЯ ПРОШЛО" }, { "k": "table", "i": 474, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки данных визита.\",\n \"errors\": [\n {\n \"field\": \"site_source_id\",\n \"code\": \"SITE_INACTIVE\",\n \"message\": \"Площадка отключена.\"\n },\n {\n \"field\": \"planned_arrival_at\",\n \"code\": \"ARRIVAL_IN_PAST\",\n \"message\": \"Плановое время прибытия не может быть в прошлом.\"\n }\n ],\n \"request_id\": \"req-example-rules\"\n}" ] ] }, { "k": "p", "i": 475, "style": "Normal", "text": "Все переданные записи найдены. Визит не создан из-за перечисленных ограничений." } ] }, { "number": "9.12", "title": "Обработка ошибок во внешней системе", "blocks": [ { "k": "p", "i": 477, "style": "Normal", "text": "Проверяйте HTTP-статус и code. Если ответ содержит errors[], обрабатывайте каждый элемент по field и code и показывайте пользователю все errors[].message. Если errors[] отсутствует, показывайте общий message." }, { "k": "table", "i": 478, "rows": [ [ "Ответ", "Что делать" ], [ "400 / 415", "Исправьте JSON или заголовок Content-Type." ], [ "401 / 403", "Проверьте токен, активность интеграции и компании." ], [ "422", "Исправьте указанные данные или устраните ограничения в Заездо. Повторите запрос с тем же external_id." ], [ "404", "Передайте отсутствующие справочники соответствующими PUT-методами. Для пользователя проверьте ручное сопоставление source_id. Затем повторите запрос с тем же external_id." ], [ "409", "Визит уже создан с другими исходными данными. Не меняйте external_id только ради обхода ошибки: это может создать лишний визит." ], [ "429", "Выдержите паузу из заголовка Retry-After и повторите запрос без изменения external_id и данных." ], [ "500 / 503 или обрыв связи", "Результат записи может быть неизвестен. После паузы повторите исходный запрос с тем же external_id и теми же данными. При повторяющемся сбое передайте request_id поддержке." ] ] } ] }, { "number": "9.13", "title": "Повторные запросы", "blocks": [ { "k": "p", "i": 481, "style": "Normal", "text": "Один external_id обозначает один визит вашей внешней системы. При потере ответа повторяйте исходный запрос без изменения external_id и его данных." }, { "k": "table", "i": 482, "rows": [ [ "Ситуация", "Результат" ], [ "Визит ещё не создан.", "Выполняются поиск и проверки. При успехе — 201, created: true." ], [ "Визит создан по тому же исходному запросу.", "200, created: false. Возвращается тот же id; новый визит не создаётся." ], [ "Визит создан, но исходные данные запроса отличаются.", "409, VISIT_ALREADY_EXISTS. Существующий визит не изменяется." ] ] }, { "k": "p", "i": 484, "style": "Normal", "text": "Для повтора сравниваются первоначально переданные данные, а не текущая карточка визита после ручного редактирования. Успешный повтор возвращает актуальные статусы существующего визита." }, { "k": "p", "i": 485, "style": "Normal", "text": "Проверка повтора выполняется до поиска справочников и проверки возможности нового создания. Поэтому запрос, по которому визит уже создан, не становится ошибочным только из-за наступившего планового времени или последующего изменения справочников." }, { "k": "p", "i": 486, "style": "Caption Custom", "text": "HTTP 409 · EXTERNAL_ID УЖЕ ИСПОЛЬЗОВАН С ДРУГИМИ ДАННЫМИ" }, { "k": "table", "i": 487, "rows": [ [ "{\n \"code\": \"VISIT_ALREADY_EXISTS\",\n \"message\": \"Визит с указанным external_id уже существует с другими исходными данными.\",\n \"request_id\": \"req-example-conflict\"\n}" ] ] } ] }, { "number": "9.14", "title": "Пример использования для 1С", "blocks": [ { "k": "p", "i": 489, "style": "Normal", "text": "Задача: передать из 1С заявку на разгрузку на складе WH-SEVER на 3 ноября 2026 года, 10:30. У контрагента CP-0042 ответственным назначен менеджер AfoninGA. Идентификатор заявки — ТД00-000015." }, { "k": "p", "i": 490, "style": "Heading 3", "text": "Шаг 1. Подготовьте доступ и данные" }, { "k": "p", "i": 491, "style": "Normal", "text": "Получите API-токен в настройках интеграции Заездо. Во всех запросах ниже замените ВАШ_API_ТОКЕН его значением. Запросы отправляются по HTTPS на app.zaezdo.pro." }, { "k": "p", "i": 492, "style": "Normal", "text": "До создания визита передайте справочники отдельными методами. Для примера используются следующие идентификаторы:" }, { "k": "table", "i": 493, "rows": [ [ "Справочник и идентификатор", "Подготовительный запрос" ], [ "Площадка WH-SEVER", "PUT /api/v1/sites/WH-SEVER" ], [ "Контрагент CP-0042", "PUT /api/v1/counterparties/CP-0042" ], [ "Автомобиль VEH-0085", "PUT /api/v1/vehicles/VEH-0085" ], [ "Водитель DRV-0017", "PUT /api/v1/drivers/DRV-0017" ] ] }, { "k": "p", "i": 495, "style": "Normal", "text": "В теле каждого PUT-запроса передаются данные соответствующего справочника. Дождитесь успешного ответа 201 или 200. Если автомобиль или водитель пока неизвестен, пропустите их подготовку и не включайте их идентификаторы в запрос визита." }, { "k": "p", "i": 496, "style": "Normal", "text": "В карточке нужного пользователя Заездо вручную укажите AfoninGA в поле «Идентификатор для синхронизации с 1С». Пользователь должен быть активен, иметь действующую учётную запись и роль «Менеджер» на площадке WH-SEVER." }, { "k": "p", "i": 497, "style": "Normal", "text": "В 1С закрепите external_id = ТД00-000015 за этой заявкой до отправки визита. При повторной отправке той же заявки идентификатор не меняйте." }, { "k": "p", "i": 498, "style": "Heading 3", "text": "Шаг 2. Проверьте ответственного" }, { "k": "table", "i": 499, "rows": [ [ "GET /api/v1/users/AfoninGA?site_source_id=WH-SEVER HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nAccept: application/json" ] ] }, { "k": "p", "i": 501, "style": "Normal", "text": "Тело запроса не передаётся. В ответе HTTP 200 проверьте поле can_be_responsible_for_site.allowed. Для продолжения его значение должно быть true." }, { "k": "p", "i": 502, "style": "Heading 3", "text": "Шаг 3. Отправьте запрос создания визита" }, { "k": "p", "i": 503, "style": "Normal", "text": "Сформируйте JSON из данных заявки 1С. Дата передаётся в формате ГГГГ-ММ-ДД ЧЧ:ММ." }, { "k": "table", "i": 504, "rows": [ [ "POST /api/v1/visits HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"external_id\": \"ТД00-000015\",\n \"site_source_id\": \"WH-SEVER\",\n \"planned_arrival_at\": \"2026-11-03 10:30\",\n \"purpose\": \"UNLOADING\",\n \"counterparty_source_id\": \"CP-0042\",\n \"responsible_user_source_id\": \"AfoninGA\",\n \"vehicle_source_id\": \"VEH-0085\",\n \"driver_source_id\": \"DRV-0017\",\n \"basis\": \"Поставка по заявке №123\"\n}" ] ] }, { "k": "p", "i": 505, "style": "Heading 3", "text": "Шаг 4. Сохраните результат в 1С" }, { "k": "p", "i": 506, "style": "Caption Custom", "text": "УСПЕШНОЕ СОЗДАНИЕ · HTTP 201 CREATED" }, { "k": "table", "i": 507, "rows": [ [ "{\n \"id\": \"VST-EXAMPLE001\",\n \"external_id\": \"ТД00-000015\",\n \"created\": true,\n \"status\": \"PLANNED\",\n \"admission_status\": \"UNDEFINED\"\n}" ] ] }, { "k": "p", "i": 509, "style": "Normal", "text": "Найдите в 1С заявку по external_id = ТД00-000015. При необходимости сохраните для неё id = VST-EXAMPLE001 и отметьте успешную передачу. PLANNED означает «Запланирован», UNDEFINED — «Не определён»: визит создан, но допуск на площадку ещё не разрешён. Дальнейшее управление допуском предполагается на стороне Заездо." }, { "k": "p", "i": 510, "style": "Heading 3", "text": "Если запрос не завершился успешно" }, { "k": "p", "i": 511, "style": "Normal", "text": "Если users вернул allowed: false, устраните причину из reason до отправки визита. При ошибке POST обработайте все элементы errors[] согласно разделу 9.12; не отмечайте заявку как успешно переданную." }, { "k": "p", "i": 512, "style": "Normal", "text": "Если ответ POST потерян, повторите тот же запрос с тем же external_id и теми же данными. Ответ 200 с created: false означает, что визит уже создан: сохраните возвращённый id без создания новой заявки." } ] } ], "x-docs-id": "visits", "x-docs-number": 9, "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string", "description": "Постоянный ID визита во внешней системе, до 80 символов.", "minLength": 1, "maxLength": 80 }, "site_source_id": { "type": "string", "description": "ID площадки во внешней системе.", "minLength": 1, "maxLength": 80 }, "planned_arrival_at": { "type": "string", "description": "Плановая дата и время. Формат ГГГГ-ММ-ДД ЧЧ:ММ. Переданное значение сохраняется без пересчёта часового пояса.", "minLength": 1, "pattern": "^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}$" }, "purpose": { "type": "string", "description": "Цель визита: LOADING — «Погрузка»; UNLOADING — «Разгрузка»; SERVICE — «Служебный визит»; OTHER — «Другое».", "minLength": 1, "enum": [ "LOADING", "UNLOADING", "SERVICE", "OTHER" ] }, "counterparty_source_id": { "type": "string", "description": "ID ранее зарегистрированного контрагента.", "minLength": 1, "maxLength": 80 }, "responsible_user_source_id": { "type": "string", "description": "ID пользователя в 1С, сопоставленного с пользователем Заездо. Назначается ответственным за визит после проверки его прав.", "minLength": 1, "maxLength": 80 }, "vehicle_source_id": { "type": "string", "description": "ID автомобиля, если он известен на этапе планирования.", "maxLength": 80 }, "driver_source_id": { "type": "string", "description": "ID водителя, если он известен на этапе планирования.", "maxLength": 80 }, "basis": { "type": "string", "description": "Основание визита, не более 500 символов.", "maxLength": 500 } }, "required": [ "external_id", "site_source_id", "planned_arrival_at", "purpose", "counterparty_source_id", "responsible_user_source_id" ] }, "example": { "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" } } } }, "x-request-http": "POST /api/v1/visits HTTP/1.1\nHost: app.zaezdo.pro\nAuthorization: Bearer ВАШ_API_ТОКЕН\nContent-Type: application/json\n\n{\n \"external_id\": \"ТД00-000015\",\n \"site_source_id\": \"WH-SEVER\",\n \"planned_arrival_at\": \"2026-11-03 10:30\",\n \"purpose\": \"UNLOADING\",\n \"counterparty_source_id\": \"CP-0042\",\n \"responsible_user_source_id\": \"AfoninGA\",\n \"vehicle_source_id\": \"VEH-0085\",\n \"driver_source_id\": \"DRV-0017\",\n \"basis\": \"Поставка по заявке №123\"\n}", "responses": { "201": { "description": "Создано", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "created": { "type": "boolean" }, "status": { "type": "string" }, "admission_status": { "type": "string", "enum": [ "UNDEFINED", "ALLOWED", "DENIED", "REVOKED" ] } }, "required": [ "id", "external_id", "created", "status", "admission_status" ] }, "examples": { "default": { "summary": "Создано", "value": { "id": "VST-EXAMPLE001", "external_id": "ТД00-000015", "created": true, "status": "PLANNED", "admission_status": "UNDEFINED" } } } } } }, "200": { "description": "Успешный ответ", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "external_id": { "type": "string" }, "created": { "type": "boolean" }, "status": { "type": "string" }, "admission_status": { "type": "string", "enum": [ "UNDEFINED", "ALLOWED", "DENIED", "REVOKED" ] } }, "required": [ "id", "external_id", "created", "status", "admission_status" ] }, "examples": { "default": { "summary": "Успешный ответ", "value": { "id": "VST-EXAMPLE001", "external_id": "ТД00-000015", "created": false, "status": "PLANNED", "admission_status": "UNDEFINED" } } } } } }, "400": { "description": "Не удалось прочитать JSON тела запроса.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса.", "request_id": "req-example-400" } } } }, "401": { "description": "Требуется действующий Bearer-токен интеграции.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции.", "request_id": "req-example-401" } } } }, "403": { "description": "Компания отключена в Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо.", "request_id": "req-example-403" } } } }, "404": { "description": "Не найдены записи по переданным идентификаторам.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RESOURCE_NOT_FOUND", "message": "Не найдены записи по переданным идентификаторам.", "request_id": "req-example-404", "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 не найден." } ] } } } }, "409": { "description": "Визит с указанным external_id уже существует с другими исходными данными.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "VISIT_ALREADY_EXISTS", "message": "Визит с указанным external_id уже существует с другими исходными данными.", "request_id": "req-example-409" } } } }, "415": { "description": "Передайте тело запроса с Content-Type: application/json.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json.", "request_id": "req-example-415" } } } }, "422": { "description": "Ошибка проверки данных визита.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных визита.", "request_id": "req-example-422", "errors": [ { "field": "external_id", "code": "REQUIRED", "message": "Укажите идентификатор визита во внешней системе." }, { "field": "external_id", "code": "INVALID_EXTERNAL_ID", "message": "external_id должен быть строкой длиной от 1 до 80 символов." } ] } } } }, "429": { "description": "Превышено допустимое количество запросов. Повторите запрос позже.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже.", "request_id": "req-example-429" } } }, "headers": { "Retry-After": { "description": "Время ожидания перед повторным запросом.", "schema": { "type": "string" } } } }, "500": { "description": "Внутренняя ошибка Заездо.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо.", "request_id": "req-example-500" } } } }, "503": { "description": "Сервис Заездо временно недоступен.", "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } } } } }, "example": { "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен.", "request_id": "req-example-503" } } } } }, "x-http-errors": [ { "http": 400, "code": "INVALID_JSON", "message": "Не удалось прочитать JSON тела запроса." }, { "http": 401, "code": "UNAUTHORIZED", "message": "Требуется действующий Bearer-токен интеграции." }, { "http": 403, "code": "TENANT_INACTIVE", "message": "Компания отключена в Заездо." }, { "http": 404, "code": "RESOURCE_NOT_FOUND", "message": "Не найдены записи по переданным идентификаторам." }, { "http": 409, "code": "VISIT_ALREADY_EXISTS", "message": "Визит с указанным external_id уже существует с другими исходными данными." }, { "http": 415, "code": "UNSUPPORTED_MEDIA_TYPE", "message": "Передайте тело запроса с Content-Type: application/json." }, { "http": 422, "code": "VALIDATION_ERROR", "message": "Ошибка проверки данных визита." }, { "http": 429, "code": "RATE_LIMITED", "message": "Превышено допустимое количество запросов. Повторите запрос позже." }, { "http": 500, "code": "INTERNAL_ERROR", "message": "Внутренняя ошибка Заездо." }, { "http": 503, "code": "SERVICE_UNAVAILABLE", "message": "Сервис Заездо временно недоступен." } ], "x-field-errors": [ { "http": 422, "field": "external_id", "code": "REQUIRED", "message": "Укажите идентификатор визита во внешней системе.", "section": "9.10" }, { "http": 422, "field": "external_id", "code": "INVALID_EXTERNAL_ID", "message": "external_id должен быть строкой длиной от 1 до 80 символов.", "section": "9.10" }, { "http": 422, "field": "site_source_id", "code": "REQUIRED", "message": "Укажите идентификатор площадки.", "section": "9.10" }, { "http": 422, "field": "site_source_id", "code": "INVALID_SITE_SOURCE_ID", "message": "Идентификатор площадки должен быть строкой длиной от 1 до 80 символов.", "section": "9.10" }, { "http": 422, "field": "counterparty_source_id", "code": "REQUIRED", "message": "Укажите идентификатор контрагента.", "section": "9.10" }, { "http": 422, "field": "counterparty_source_id", "code": "INVALID_COUNTERPARTY_SOURCE_ID", "message": "Идентификатор контрагента должен быть строкой длиной от 1 до 80 символов.", "section": "9.10" }, { "http": 422, "field": "responsible_user_source_id", "code": "REQUIRED", "message": "Укажите идентификатор ответственного менеджера.", "section": "9.10" }, { "http": 422, "field": "responsible_user_source_id", "code": "INVALID_RESPONSIBLE_USER_SOURCE_ID", "message": "Идентификатор ответственного должен быть строкой длиной от 1 до 80 символов.", "section": "9.10" }, { "http": 422, "field": "vehicle_source_id", "code": "INVALID_VEHICLE_SOURCE_ID", "message": "Идентификатор автомобиля должен быть строкой длиной от 1 до 80 символов.", "section": "9.10" }, { "http": 422, "field": "driver_source_id", "code": "INVALID_DRIVER_SOURCE_ID", "message": "Идентификатор водителя должен быть строкой длиной от 1 до 80 символов.", "section": "9.10" }, { "http": 422, "field": "planned_arrival_at", "code": "REQUIRED", "message": "Укажите плановую дату и время прибытия.", "section": "9.10" }, { "http": 422, "field": "planned_arrival_at", "code": "INVALID_DATETIME", "message": "Передайте плановую дату и время в формате ГГГГ-ММ-ДД ЧЧ:ММ.", "section": "9.10" }, { "http": 422, "field": "purpose", "code": "REQUIRED", "message": "Укажите цель визита.", "section": "9.10" }, { "http": 422, "field": "purpose", "code": "INVALID_PURPOSE", "message": "Допустимые значения цели визита: LOADING, UNLOADING, SERVICE, OTHER.", "section": "9.10" }, { "http": 422, "field": "basis", "code": "INVALID_BASIS", "message": "Основание визита должно быть строкой.", "section": "9.10" }, { "http": 422, "field": "basis", "code": "MAX_LENGTH_EXCEEDED", "message": "Основание визита не должно превышать 500 символов.", "section": "9.10" }, { "http": 404, "field": "site_source_id", "code": "SITE_NOT_FOUND", "message": "Площадка с указанным site_source_id не найдена.", "section": "9.10" }, { "http": 404, "field": "counterparty_source_id", "code": "COUNTERPARTY_NOT_FOUND", "message": "Контрагент с указанным counterparty_source_id не найден.", "section": "9.10" }, { "http": 404, "field": "responsible_user_source_id", "code": "MANAGER_NOT_FOUND", "message": "Пользователь с указанным responsible_user_source_id не найден.", "section": "9.10" }, { "http": 404, "field": "vehicle_source_id", "code": "VEHICLE_NOT_FOUND", "message": "Автомобиль с указанным vehicle_source_id не найден.", "section": "9.10" }, { "http": 404, "field": "driver_source_id", "code": "DRIVER_NOT_FOUND", "message": "Водитель с указанным driver_source_id не найден.", "section": "9.10" }, { "http": 422, "field": "site_source_id", "code": "SITE_INACTIVE", "message": "Площадка отключена.", "section": "9.10" }, { "http": 422, "field": "counterparty_source_id", "code": "COUNTERPARTY_INACTIVE", "message": "Контрагент отключён.", "section": "9.10" }, { "http": 422, "field": "responsible_user_source_id", "code": "MANAGER_INACTIVE", "message": "Ответственный сотрудник отключён.", "section": "9.10" }, { "http": 422, "field": "responsible_user_source_id", "code": "MANAGER_NO_ACCOUNT", "message": "У ответственного сотрудника нет действующей учётной записи в Заездо.", "section": "9.10" }, { "http": 422, "field": "responsible_user_source_id", "code": "MANAGER_NOT_MANAGER", "message": "Ответственному сотруднику не назначена роль «Менеджер».", "section": "9.10" }, { "http": 422, "field": "responsible_user_source_id", "code": "MANAGER_NO_SITE_ACCESS", "message": "Ответственный менеджер не имеет доступа к указанной площадке.", "section": "9.10" }, { "http": 422, "field": "vehicle_source_id", "code": "VEHICLE_INACTIVE", "message": "Автомобиль отключён.", "section": "9.10" }, { "http": 422, "field": "driver_source_id", "code": "DRIVER_INACTIVE", "message": "Водитель отключён.", "section": "9.10" }, { "http": 422, "field": "planned_arrival_at", "code": "ARRIVAL_IN_PAST", "message": "Плановое время прибытия не может быть в прошлом.", "section": "9.10" } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API-токен из настроек интеграции Заездо." } } }, "x-docs-common": { "n": 1, "title": "Общие правила интеграции", "intro": [ { "k": "p", "i": 12, "style": "Normal", "text": "Для обмена с Заездо внешняя система использует HTTPS-запросы и получает ответы в формате JSON." }, { "k": "p", "i": 13, "style": "Text Body", "text": "Получение токена — администратор клиента создаёт API-токен в настройках интеграции Заездо: https://app.zaezdo.pro/settings/integration." }, { "k": "p", "i": 14, "style": "Text Body", "text": "Передача токена — каждый запрос содержит заголовок Authorization: Bearer <токен>." }, { "k": "p", "i": 15, "style": "Text Body", "text": "Базовый адрес — https://app.zaezdo.pro/api/v1" }, { "k": "p", "i": 16, "style": "Caption Custom", "text": "ПРИМЕР ЗАГОЛОВКА АВТОРИЗАЦИИ" }, { "k": "table", "i": 17, "rows": [ [ "Authorization: Bearer ВАШ_API_ТОКЕН" ] ] } ], "sections": [ { "number": "1.1", "title": "Общие правила PUT-методов", "blocks": [ { "k": "p", "i": 20, "style": "Normal", "text": "PUT-методы используются для создания или обновления данных следующих сущностей Заездо:" }, { "k": "p", "i": 21, "style": "List Paragraph", "text": "Площадки: https://app.zaezdo.pro/directory/sites" }, { "k": "p", "i": 22, "style": "List Paragraph", "text": "Контрагенты: https://app.zaezdo.pro/directory/counterparties" }, { "k": "p", "i": 23, "style": "List Paragraph", "text": "Транспортные средства: https://app.zaezdo.pro/directory/vehicles" }, { "k": "p", "i": 24, "style": "List Paragraph", "text": "Водители: https://app.zaezdo.pro/directory/drivers" }, { "k": "p", "i": 25, "style": "Heading 3", "text": "Идентификатор записи {source_id}" }, { "k": "p", "i": 26, "style": "Normal", "text": "{source_id} – это идентификатор, который связывает сущность внешней системы с данными Заездо. Передавайте его в параметрах URL для поиска и сопоставления нужных данных." }, { "k": "p", "i": 27, "style": "Normal", "text": "source_id — непустая строка длиной от 1 до 80 символов. Регистр символов имеет значение. Не допускаются управляющие символы, пробелы по краям и разделители пути / и \\. Кириллица допустима; в URL её нужно кодировать в UTF-8." }, { "k": "p", "i": 28, "style": "Normal", "text": "Идентификатор передаётся в пути. Повторять его в теле JSON не следует." }, { "k": "p", "i": 29, "style": "Heading 3", "text": "Какие данные обновляются" }, { "k": "p", "i": 30, "style": "Normal", "text": "PUT передаёт полное состояние полей, перечисленных в описании метода. При повторе с тем же source_id данные этих полей заменяются значениями из запроса. Поэтому в каждом запросе передавайте все значения, которые нужно сохранить." }, { "k": "table", "i": 31, "rows": [ [ "Переданное значение", "Результат" ], [ "Обязательное поле", "Передаётся и при создании, и при обновлении. Пустое значение недопустимо." ], [ "Необязательное поле отсутствует, null или \"\"", "При создании остаётся пустым; при обновлении прежнее значение очищается." ], [ "Поле не предусмотрено методом", "Ошибка 422 UNKNOWN_FIELD. Запись не сохраняется." ] ] }, { "k": "p", "i": 32, "style": "Normal", "text": "Для обычных строк убираются пробелы по краям; пустая строка после этого считается незаполненным значением. Для source_id пробелы не исправляются автоматически. Необязательные поля принимают строку или null; у обязательных полей тип — string. Исключение — admission_mode метода sites: правила его передачи приведены в разделе 5.1." }, { "k": "p", "i": 33, "style": "Heading 3", "text": "Активность и повторные запросы" }, { "k": "p", "i": 34, "style": "Normal", "text": "Новая запись активна. При обновлении сохраняется её текущая активность: отключённая запись автоматически не включается. Поле is_active возвращается в ответе, но не принимается для изменения через PUT. Настройки, не входящие в метод, остаются без изменений." }, { "k": "p", "i": 35, "style": "Normal", "text": "Первая запись возвращает 201 и created: true. Обновление или повтор — 200 и created: false. Повтор одинакового запроса не создаёт новую запись." } ] }, { "number": "1.2", "title": "Общие ошибки PUT-методов", "blocks": [ { "k": "p", "i": 37, "style": "Normal", "text": "В таблице указаны точные значения code и message. Для 409 и 422 ответ также содержит errors[]: field — параметр, code — обобщенная причина, message — описание ошибки. Каждый ответ приложения с ошибкой содержит request_id." }, { "k": "table", "i": 38, "rows": [ [ "HTTP", "code", "message" ], [ "400", "INVALID_JSON", "Не удалось прочитать JSON тела запроса." ], [ "401", "UNAUTHORIZED", "Требуется действующий Bearer-токен интеграции." ], [ "403", "TENANT_INACTIVE", "Компания отключена в Заездо." ], [ "409", "RESOURCE_CONFLICT", "Невозможно сохранить запись из-за конфликта данных." ], [ "415", "UNSUPPORTED_MEDIA_TYPE", "Передайте тело запроса с Content-Type: application/json." ], [ "422", "VALIDATION_ERROR", "Ошибка проверки данных справочника." ], [ "429", "RATE_LIMITED", "Превышено допустимое количество запросов. Повторите запрос позже." ], [ "500", "INTERNAL_ERROR", "Внутренняя ошибка Заездо." ], [ "503", "SERVICE_UNAVAILABLE", "Сервис Заездо временно недоступен." ] ] }, { "k": "p", "i": 40, "style": "Normal", "text": "При 429 учитывайте Retry-After. При 500, 503 или потере ответа повторите тот же PUT после паузы. Если вместо JSON получен ответ сетевого шлюза, ориентируйтесь на HTTP-статус; request_id в таком ответе может отсутствовать." } ] }, { "number": "1.3", "title": "Общие ошибки параметров PUT", "blocks": [ { "k": "p", "i": 42, "style": "Normal", "text": "Для ошибок ниже верхнеуровневый ответ — 422 VALIDATION_ERROR. Специальные ограничения полей описаны в разделе соответствующего метода." }, { "k": "table", "i": 43, "rows": [ [ "errors[].field / code", "Точное значение errors[].message" ], [ "$\nBODY_MUST_BE_OBJECT", "Тело запроса должно быть объектом JSON." ], [ "source_id\nINVALID_SOURCE_ID", "Некорректный идентификатор записи во внешней системе." ], [ "Имя лишнего поля\nUNKNOWN_FIELD", "Параметр не поддерживается этим методом." ], [ "comment\nINVALID_COMMENT", "Комментарий должен быть строкой или null." ] ] }, { "k": "p", "i": 45, "style": "Normal", "text": "Для BODY_MUST_BE_OBJECT поле field содержит \"$\" — весь JSON. Для UNKNOWN_FIELD в field возвращается фактически переданное лишнее имя, например is_active." }, { "k": "p", "i": 46, "style": "Normal", "text": "REQUIRED возвращается, когда обязательного поля нет либо оно равно null или пустой строке. Если поле заполнено, но имеет неверный тип или длину, возвращается соответствующий код INVALID_… . Две ошибки об одном и том же нарушении не дублируются." }, { "k": "p", "i": 47, "style": "Heading 3", "text": "Когда возникает конфликт 409" }, { "k": "p", "i": 48, "style": "Normal", "text": "Если другая запись имеет те же реквизиты, по которым проверяются совпадения, метод не объединяет записи автоматически и не меняет их source_id. Критерии совпадения указаны для каждого справочника. Отключённые записи участвуют в проверке конфликтов." }, { "k": "p", "i": 49, "style": "Normal (Web)", "text": "Совпадения проверяются по следующим реквизитам:" }, { "k": "p", "i": 50, "style": "Normal (Web)", "text": "Площадки — код площадки." }, { "k": "p", "i": 51, "style": "Normal (Web)", "text": "Контрагенты — ИНН и КПП организации либо ИНН ИП." }, { "k": "p", "i": 52, "style": "Normal (Web)", "text": "Автомобили — государственный номер." }, { "k": "p", "i": 53, "style": "Normal (Web)", "text": "Водители — серия и номер удостоверения или паспорта." }, { "k": "p", "i": 54, "style": "Normal (Web)", "text": "Ответ API:" }, { "k": "p", "i": 55, "style": "Normal (Web)", "text": "HTTP: 409 Conflict" }, { "k": "p", "i": 56, "style": "Normal (Web)", "text": "code: RESOURCE_CONFLICT" }, { "k": "p", "i": 57, "style": "Normal (Web)", "text": "message: «Невозможно сохранить запись из-за конфликта данных.»" }, { "k": "p", "i": 58, "style": "Normal (Web)", "text": "errors[] — конкретные причины конфликта." }, { "k": "p", "i": 59, "style": "Normal (Web)", "text": "request_id — идентификатор запроса для диагностики." }, { "k": "p", "i": 60, "style": "Normal (Web)", "text": "Как устранить конфликт?" }, { "k": "p", "i": 61, "style": "Normal (Web)", "text": "Проверьте, не существует ли соответствующая запись в справочнике Заездо." }, { "k": "p", "i": 62, "style": "Normal (Web)", "text": "Если запись существует и соответствует объекту внешней системы, укажите в её карточке правильный «Идентификатор для синхронизации с 1С»." }, { "k": "p", "i": 63, "style": "Normal (Web)", "text": "Повторите исходный PUT-запрос с тем же source_id." }, { "k": "p", "i": 64, "style": "Normal (Web)", "text": "Заездо не создаёт дубликат и не выполняет автоматическое объединение записей. Не изменяйте source_id в 1С только ради обхода конфликта." }, { "k": "p", "i": 66, "style": "Heading 3", "text": "Пример общей ошибки параметра" }, { "k": "p", "i": 67, "style": "Caption Custom", "text": "HTTP 422 · source_id НЕ СООТВЕТСТВУЕТ ОГРАНИЧЕНИЯМ" }, { "k": "table", "i": 68, "rows": [ [ "{\n \"code\": \"VALIDATION_ERROR\",\n \"message\": \"Ошибка проверки данных справочника.\",\n \"errors\": [\n {\n \"field\": \"source_id\",\n \"code\": \"INVALID_SOURCE_ID\",\n \"message\": \"Некорректный идентификатор записи во внешней системе.\"\n }\n ],\n \"request_id\": \"req-put-format\"\n}" ] ] } ] } ] }, "x-docs-common-errors": { "http": [ [ "400", "INVALID_JSON", "Не удалось прочитать JSON тела запроса." ], [ "401", "UNAUTHORIZED", "Требуется действующий Bearer-токен интеграции." ], [ "403", "TENANT_INACTIVE", "Компания отключена в Заездо." ], [ "409", "RESOURCE_CONFLICT", "Невозможно сохранить запись из-за конфликта данных." ], [ "415", "UNSUPPORTED_MEDIA_TYPE", "Передайте тело запроса с Content-Type: application/json." ], [ "422", "VALIDATION_ERROR", "Ошибка проверки данных справочника." ], [ "429", "RATE_LIMITED", "Превышено допустимое количество запросов. Повторите запрос позже." ], [ "500", "INTERNAL_ERROR", "Внутренняя ошибка Заездо." ], [ "503", "SERVICE_UNAVAILABLE", "Сервис Заездо временно недоступен." ] ], "fields": [ { "http": 422, "field": "$", "code": "BODY_MUST_BE_OBJECT", "message": "Тело запроса должно быть объектом JSON.", "section": "1.3" }, { "http": 422, "field": "source_id", "code": "INVALID_SOURCE_ID", "message": "Некорректный идентификатор записи во внешней системе.", "section": "1.3" }, { "http": 422, "field": "Имя лишнего поля", "code": "UNKNOWN_FIELD", "message": "Параметр не поддерживается этим методом.", "section": "1.3" }, { "http": 422, "field": "comment", "code": "INVALID_COMMENT", "message": "Комментарий должен быть строкой или null.", "section": "1.3" } ] }, "x-docs-source": { "file": "Zaezdo_API_v1_admission_body(1).docx", "sha256": "fd5f175d3ad53c7179360e6a581876e770225a5b8dfd645486b2079a529d3e33", "approved": "2026-10-27" } }