From 4298c2791df0370479f2f87aa8a925145a592a4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=A0=D1=83=D1=81=D0=BB=D0=B0=D0=BD=20=D0=93=D0=B0=D0=BB?= =?UTF-8?q?=D0=B8=D0=B5=D0=B2?= Date: Thu, 9 Apr 2026 11:18:11 +0300 Subject: [PATCH] Update api docs --- eurostyle-server-api-requirements.md | 283 ++++++++++++++++----------- 1 file changed, 166 insertions(+), 117 deletions(-) diff --git a/eurostyle-server-api-requirements.md b/eurostyle-server-api-requirements.md index f85641a..d242fbe 100644 --- a/eurostyle-server-api-requirements.md +++ b/eurostyle-server-api-requirements.md @@ -9,6 +9,7 @@ | Метод | Endpoint | Описание | |-------|-----------------------------|--------------------------------| | GET | `/api/v1/brands` | Список брендов | +| GET | `/api/v1/regions` | Список регионов | | GET | `/api/v1/customers` | Список контрагентов (юр лиц компании) | | GET | `/api/v1/addresses` | Список адресов (обьектов) | | GET | `/api/v1/masters` | Список мастеров | @@ -23,11 +24,11 @@ | GET | `/api/v1/repair_orders` | Список заявок на ремонт | | GET | `/api/v1/repair_orders/1` | Просмотр заявки на ремонт | | POST | `/api/v1/repair_orders` | Создание заявки на ремонт | -| PUT | `/api/v1/service_orders` | Изменение заявки на ремонт | -| GET | `/api/v1/service_orders` | Список планогов ТО. | -| GET | `/api/v1/service_orders/1` | Просмотр планового ТО. | -| POST | `/api/v1/service_orders` | Создание планового ТО. | -| PUT | `/api/v1/service_orders` | Изменение планового ТО. | +| PUT | `/api/v1/repair_orders` | Изменение заявки на ремонт | +| GET | `/api/v1/service_orders` | Список заявок на ТО | +| GET | `/api/v1/service_orders/1` | Просмотр заявки на ТО | +| POST | `/api/v1/service_orders` | Создание заявки на ТО | +| PUT | `/api/v1/service_orders/1` | Изменение заявки на ТО | --- @@ -51,6 +52,24 @@ --- +### ✅ `GET /api/v1/regions` + +```json +[ + { + "external_key": "region-001", + "name": "Московская область" + } +] +``` + +| Поле | Тип | Обязательно | Описание | +|------|-----|-------------|----------| +| `external_key` | string | ✅ | Уникальный ID региона | +| `name` | string | ✅ | Название региона | + +--- + ### ✅ `GET /api/v1/customers` ```json @@ -78,6 +97,7 @@ "name": "ул. Техническая, 10", "brand_key": "brand-001", "customer_key": "cust-001", + "region_key": "region-001", "master_key": "master-001", "serviced_from": "2025-01-01", "serviced_by": "2025-12-01", @@ -92,7 +112,8 @@ | `name` | string | ✅ | Название или адрес | | `brand_key` | string | ✅ | Связь с брендом | | `customer_key` | string | ✅ | Связь с клиентом | -| `master_key` | string | ✅| Прикреплённый мастер | +| `region_key` | string | ❌ | Связь с регионом | +| `master_key` | string | ❌ | Прикреплённый мастер | | `serviced_from` | date | ❌ | Дата начала сервисного обслуживания | | `serviced_by` | date | ❌ | Дата завершения сервисного обслуживания | | `comment` | string | ❌ | Комментарий | @@ -415,12 +436,18 @@ order_type - Перечисление (Enum) status - Перечисление (Enum) -| Значение | Описание | -|----------|-----------| -| `0` | Новая | -| `1` | Плановая | -| `2` | Завершено | -| `3` | Отложено | +| Значение | Описание | +|----------|---------------------| +| `0` | Отложенная | +| `1` | Новая | +| `2` | В работе | +| `3` | Завершено | +| `4` | Плановая | +| `5` | Нет акта | +| `6` | Уточнение | +| `7` | Ремонт в мастерской | +| `8` | Непринятая | +| `9` | Отклонена | part_type - Перечисление (Enum) @@ -516,7 +543,7 @@ part_type - Перечисление (Enum) { "line": 2, "external_key": "job-002", - "count": 10 + "count": 10 } ] } @@ -535,7 +562,6 @@ part_type - Перечисление (Enum) "required_parts": [ { "line": 1, - "part_type": 1, "count": 100, "part_key": "material-1", "part_name": "Деталь" @@ -544,7 +570,6 @@ part_type - Перечисление (Enum) "spent_parts": [ { "line": 1, - "part_type": 1, "count": 100, "part_key": "material-1", "part_name": "Деталь" @@ -612,10 +637,6 @@ part_type - Перечисление (Enum) { "line": 1, "external_key": "pi-001" - }, - { - "line": 2, - "external_key": "pi-002" } ], "required_parts": [ @@ -623,11 +644,6 @@ part_type - Перечисление (Enum) "line": 1, "external_key": "part-001", "count": 10 - }, - { - "line": 2, - "external_key": "part-002", - "count": 10 } ], "spent_parts": [ @@ -635,11 +651,6 @@ part_type - Перечисление (Enum) "line": 1, "external_key": "part-001", "count": 10 - }, - { - "line": 2, - "external_key": "part-002", - "count": 10 } ], "jobs": [ @@ -647,11 +658,6 @@ part_type - Перечисление (Enum) "line": 1, "external_key": "job-001", "count": 10 - }, - { - "line": 2, - "external_key": "job-002", - "count": 10 } ] } @@ -678,8 +684,8 @@ part_type - Перечисление (Enum) ```json { "customer_key": "cust-001", - "address_key": "addr-001", - "warehouse_key": "warehouse-001", + "address_key": "UPDATED-addr-001", + "warehouse_key": "UPDATED-ware-001", "brand_key": "brand-001", "master_key": "master-001", "contact_person_name": "Петров Петр", @@ -756,7 +762,6 @@ part_type - Перечисление (Enum) "required_parts": [ { "line": 1, - "part_type": 1, "count": 100, "part_key": "material-1", "part_name": "Деталь" @@ -765,7 +770,6 @@ part_type - Перечисление (Enum) "spent_parts": [ { "line": 1, - "part_type": 1, "count": 100, "part_key": "material-1", "part_name": "Деталь" @@ -810,142 +814,187 @@ part_type - Перечисление (Enum) ### ✅ `GET /api/v1/service_orders` -Описание: Ответ содержит массив из хешей содержащих 1С ключей документов планового ТО +Описание: Ответ содержит массив из хешей, содержащих 1С ключ заявок на ТО. -Доступные параметры +Доступные параметры: -| Параметр | Назначение | -|------------|--------------------------| -| `start_date` | Фильтр по дате документа(начинается от) | -| `end_date` | Фильтр по дате документа(заканчивается до) | +| Параметр | Назначение | +|--------------|--------------------------------------------------| +| `start_date` | Фильтр по дате документа (начиная от) | +| `end_date` | Фильтр по дате документа (заканчивая до) | ```json - [ - { - "external_key": "so-001" - }, - { - "external_key": "so-002" - }, - { - "external_key": "so-003" - } - ] +[ + { + "external_key": "so-001" + }, + { + "external_key": "so-002" + } +] ``` --- ### ✅ `GET /api/v1/service_orders/so-001` -Описание: Ответ содержит конкретный документ "Планового ТО" +Просмотр существующей заявки на ТО. **so-001** — это ключ 1С заявки на ТО. + +**Пример успешного ответа:** ```json - { - "external_key": "key-1", - "status": 0, - "number_in_client_database": "Номер в базе клиента", - "number": "1234", - "date": "2025-06-01 10:00:00", - "address_key": "address-key", - "date_of_service": "2025-06-01 10:00:00", - "responsible": "Отвественный/(строка)", - "conclusion": "Заключение", - "comment": "Комментарий", +{ + "external_key": "so-001", + "address_key": "addr-001", "masters": [ { - "master_key": "master-key1" - }, - { - "master_key": "master-key2" + "master_key": "master-001" } - ] + ], + "number": "SO-2025-001", + "number_in_client_database": "client-123", + "date": "2025-04-07T08:30:00Z", + "date_of_service": "2025-04-10T00:00:00Z", + "responsible": "Иванов Иван", + "conclusion": "Выполнено", + "comment": "Комментарий", + "status": 1, + "files_path": "\\Shared\\service\\file.txt" } ``` -Описание полей: +| Поле | Тип | Обязательно | Описание | +|-----------------------------|----------|-------------|------------------------------------------| +| `external_key` | string | ✅ | Уникальный ID заявки | +| `address_key` | string | ✅ | Ссылка на адрес | +| `masters` | array | ✅ | Список мастеров (массив `{master_key}`) | +| `number` | string | ❌ | Номер заявки | +| `number_in_client_database` | string | ❌ | Номер в базе клиента | +| `date` | datetime | ❌ | Дата создания заявки | +| `date_of_service` | datetime | ❌ | Дата планового обслуживания | +| `responsible` | string | ❌ | Ответственный | +| `conclusion` | string | ❌ | Заключение | +| `comment` | string | ❌ | Комментарий | +| `status` | numeric | ✅ | Статус заявки (enum) | +| `files_path` | string | ❌ | Путь к файлам на файловом сервере | -| Поле | Тип | Обязательно | Описание | -|-----------------------------|----------|-------------|----------------------------------------| -| `external_key` | string | ✅ | Уникальный ID заявки | -| `address_key` | string | ✅ | Ссылка на адрес | -| `number` | string | ✅ | Номер документа | -| `date` | datetime | ✅ | Дата документа. | -| `number_in_client_database` | string | ❌ | Номер в базе клиента | -| `date_of_service` | datetime | ✅ | Дата проведения ТО | -| `responsible` | string | ❌ | Ответственный | -| `status` | numeric | ✅ | Статус. (enum) | -| `comment` | text | ❌ | Комментарий. | -| `conclusion` | text | ❌ | Заключение | +status — Перечисление (Enum) -state - Перечисление (Enum) +| Значение | Описание | +|----------|-----------| +| `1` | В работе | +| `2` | Завершено | -| Значение | Описание | -|----------|-------------------------| -| `0` | Новая | -| `1` | В работе | -| `2` | Завершено | -| `3` | Плановая | -| `4` | Нет акта | -| `5` | Уточнение | -| `6` | Ремонт в мастерской. | -| `7` | Непринятая | -| `8` | Отклонена | +**Пример ошибки, заявка не найдена:** + +```json +{ + "errors": { + "id": ["не существует"] + } +} +``` --- ### ✅ `POST /api/v1/service_orders` -Создание нового документа "Планового ТО". +Создание новой заявки на ТО. **Тело запроса:** ```json { - "number_in_client_database": "Номер в базе клиента", - "address_key": "address-key", - "date_of_service": "2025-06-01 10:00:00", - "conclusion": "Заключение", + "external_key": null, + "number": "SO-2025-001", + "number_in_client_database": "client-123", + "responsible": "Иванов Иван", "comment": "Комментарий", + "date": "2025-04-07T08:30:00Z", + "date_of_service": "2025-04-10T00:00:00Z", + "status": 1, + "address_key": "addr-001", "masters": [ { - "master_key": "master-key1" - }, - { - "master_key": "master-key2" + "master_key": "master-001" } ] } ``` -Ответ соответствует ответу при запросе конкретного документа "Планового ТО" +| Поле | Тип | Обязательно | Описание | +|-----------------------------|----------|-------------|-----------------------------------------| +| `external_key` | string | ❌ | Ключ 1С (null при создании) | +| `number` | string | ❌ | Номер заявки | +| `number_in_client_database` | string | ❌ | Номер в базе клиента | +| `responsible` | string | ❌ | Ответственный | +| `comment` | string | ❌ | Комментарий | +| `date` | datetime | ✅ | Дата создания (при отсутствии: `"0001-01-01T00:00:00Z"`) | +| `date_of_service` | datetime | ✅ | Дата обслуживания (при отсутствии: `"0001-01-01T00:00:00Z"`) | +| `status` | numeric | ✅ | Статус заявки (enum) | +| `address_key` | string | ✅ | Ссылка на адрес | +| `masters` | array | ✅ | Список мастеров (массив `{master_key}`) | + +> **Примечание:** если значение даты не задано, передаётся строка `"0001-01-01T00:00:00Z"` вместо `null`. + +**Пример успешного ответа:** + +```json +{ + "external_key": "so-001", + "number": "SO-2025-001", + "date": "2025-04-07T08:30:00Z", + "files_path": "\\Shared\\service\\file.txt" +} +``` + +| Поле | Тип | Описание | +|----------------|----------|-----------------------------------| +| `external_key` | string | Присвоенный 1С ключ заявки | +| `number` | string | Номер заявки в 1С | +| `date` | datetime | Дата заявки в 1С | +| `files_path` | string | Путь к папке файлов на файловом сервере | --- ### ✅ `PUT /api/v1/service_orders/so-001` -Обновление документа "Планового ТО". +Изменение существующей заявки на ТО. **so-001** — это ключ 1С заявки на ТО. -**Тело запроса:** +**Тело запроса** (аналогично POST, но `external_key` всегда заполнен): ```json { - "number_in_client_database": "Номер в базе клиента", - "address_key": "address-key", - "date_of_service": "2025-06-01 10:00:00", - "conclusion": "Заключение", - "comment": "Комментарий", + "external_key": "so-001", + "number": "SO-2025-001", + "number_in_client_database": "client-123", + "responsible": "Иванов Иван", + "comment": "Обновлённый комментарий", + "date": "2025-04-07T08:30:00Z", + "date_of_service": "2025-04-12T00:00:00Z", + "status": 2, + "address_key": "addr-001", "masters": [ { - "master_key": "master-key1" + "master_key": "master-001" }, { - "master_key": "master-key2" + "master_key": "master-002" } ] } ``` -Ответ соответствует ответу при запросе конкретного документа "Планового ТО" +**Пример успешного ответа:** + +```json +{ + "external_key": "so-001", + "number": "SO-2025-001", + "date": "2025-04-07T08:30:00Z", + "files_path": "\\Shared\\service\\file.txt" +} +``` ---