public/eurostyle-server-api-requirements
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update api docs

Browse Source
This commit is contained in:
Галиев Руслан
2026-04-09 11:18:11 +03:00
parent d9a785743e
commit 4298c2791d
1 changed files with 166 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

283
eurostyle-server-api-requirements.md
View File

@@ -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"
}
```
---