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 | Описание | | Метод | Endpoint | Описание |
|-------|-----------------------------|--------------------------------| |-------|-----------------------------|--------------------------------|
| GET | `/api/v1/brands` | Список брендов | | GET | `/api/v1/brands` | Список брендов |
| GET | `/api/v1/regions` | Список регионов |
| GET | `/api/v1/customers` | Список контрагентов (юр лиц компании) | | GET | `/api/v1/customers` | Список контрагентов (юр лиц компании) |
| GET | `/api/v1/addresses` | Список адресов (обьектов) | | GET | `/api/v1/addresses` | Список адресов (обьектов) |
| GET | `/api/v1/masters` | Список мастеров | | GET | `/api/v1/masters` | Список мастеров |
@@ -23,11 +24,11 @@
| GET | `/api/v1/repair_orders` | Список заявок на ремонт | | GET | `/api/v1/repair_orders` | Список заявок на ремонт |
| GET | `/api/v1/repair_orders/1` | Просмотр заявки на ремонт | | GET | `/api/v1/repair_orders/1` | Просмотр заявки на ремонт |
| POST | `/api/v1/repair_orders` | Создание заявки на ремонт | | POST | `/api/v1/repair_orders` | Создание заявки на ремонт |
| PUT | `/api/v1/service_orders` | Изменение заявки на ремонт | | PUT | `/api/v1/repair_orders` | Изменение заявки на ремонт |
| GET | `/api/v1/service_orders` | Список планогов ТО. | | GET | `/api/v1/service_orders` | Список заявок на ТО |
| GET | `/api/v1/service_orders/1` | Просмотр планового ТО. | | GET | `/api/v1/service_orders/1` | Просмотр заявки на ТО |
| POST | `/api/v1/service_orders` | Создание планового ТО. | | POST | `/api/v1/service_orders` | Создание заявки на ТО |
| PUT | `/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` ### ✅ `GET /api/v1/customers`
```json ```json
@@ -78,6 +97,7 @@
"name": "ул. Техническая, 10", "name": "ул. Техническая, 10",
"brand_key": "brand-001", "brand_key": "brand-001",
"customer_key": "cust-001", "customer_key": "cust-001",
"region_key": "region-001",
"master_key": "master-001", "master_key": "master-001",
"serviced_from": "2025-01-01", "serviced_from": "2025-01-01",
"serviced_by": "2025-12-01", "serviced_by": "2025-12-01",
@@ -92,7 +112,8 @@
| `name` | string | ✅ | Название или адрес | | `name` | string | ✅ | Название или адрес |
| `brand_key` | string | ✅ | Связь с брендом | | `brand_key` | string | ✅ | Связь с брендом |
| `customer_key` | string | ✅ | Связь с клиентом | | `customer_key` | string | ✅ | Связь с клиентом |
| `master_key` | string | ✅| Прикреплённый мастер | | `region_key` | string | ❌ | Связь с регионом |
| `master_key` | string | ❌ | Прикреплённый мастер |
| `serviced_from` | date | ❌ | Дата начала сервисного обслуживания | | `serviced_from` | date | ❌ | Дата начала сервисного обслуживания |
| `serviced_by` | date | ❌ | Дата завершения сервисного обслуживания | | `serviced_by` | date | ❌ | Дата завершения сервисного обслуживания |
| `comment` | string | ❌ | Комментарий | | `comment` | string | ❌ | Комментарий |
@@ -415,12 +436,18 @@ order_type - Перечисление (Enum)
status - Перечисление (Enum) status - Перечисление (Enum)
| Значение | Описание | | Значение | Описание |
|----------|-----------| |----------|---------------------|
| `0` | Новая | | `0` | Отложенная |
| `1` | Плановая | | `1` | Новая |
| `2` | Завершено | | `2` | В работе |
| `3` | Отложено | | `3` | Завершено |
| `4` | Плановая |
| `5` | Нет акта |
| `6` | Уточнение |
| `7` | Ремонт в мастерской |
| `8` | Непринятая |
| `9` | Отклонена |
part_type - Перечисление (Enum) part_type - Перечисление (Enum)
@@ -516,7 +543,7 @@ part_type - Перечисление (Enum)
{ {
"line": 2, "line": 2,
"external_key": "job-002", "external_key": "job-002",
"count": 10 "count": 10
} }
] ]
} }
@@ -535,7 +562,6 @@ part_type - Перечисление (Enum)
"required_parts": [ "required_parts": [
{ {
"line": 1, "line": 1,
"part_type": 1,
"count": 100, "count": 100,
"part_key": "material-1", "part_key": "material-1",
"part_name": "Деталь" "part_name": "Деталь"
@@ -544,7 +570,6 @@ part_type - Перечисление (Enum)
"spent_parts": [ "spent_parts": [
{ {
"line": 1, "line": 1,
"part_type": 1,
"count": 100, "count": 100,
"part_key": "material-1", "part_key": "material-1",
"part_name": "Деталь" "part_name": "Деталь"
@@ -612,10 +637,6 @@ part_type - Перечисление (Enum)
{ {
"line": 1, "line": 1,
"external_key": "pi-001" "external_key": "pi-001"
},
{
"line": 2,
"external_key": "pi-002"
} }
], ],
"required_parts": [ "required_parts": [
@@ -623,11 +644,6 @@ part_type - Перечисление (Enum)
"line": 1, "line": 1,
"external_key": "part-001", "external_key": "part-001",
"count": 10 "count": 10
},
{
"line": 2,
"external_key": "part-002",
"count": 10
} }
], ],
"spent_parts": [ "spent_parts": [
@@ -635,11 +651,6 @@ part_type - Перечисление (Enum)
"line": 1, "line": 1,
"external_key": "part-001", "external_key": "part-001",
"count": 10 "count": 10
},
{
"line": 2,
"external_key": "part-002",
"count": 10
} }
], ],
"jobs": [ "jobs": [
@@ -647,11 +658,6 @@ part_type - Перечисление (Enum)
"line": 1, "line": 1,
"external_key": "job-001", "external_key": "job-001",
"count": 10 "count": 10
},
{
"line": 2,
"external_key": "job-002",
"count": 10
} }
] ]
} }
@@ -678,8 +684,8 @@ part_type - Перечисление (Enum)
```json ```json
{ {
"customer_key": "cust-001", "customer_key": "cust-001",
"address_key": "addr-001", "address_key": "UPDATED-addr-001",
"warehouse_key": "warehouse-001", "warehouse_key": "UPDATED-ware-001",
"brand_key": "brand-001", "brand_key": "brand-001",
"master_key": "master-001", "master_key": "master-001",
"contact_person_name": "Петров Петр", "contact_person_name": "Петров Петр",
@@ -756,7 +762,6 @@ part_type - Перечисление (Enum)
"required_parts": [ "required_parts": [
{ {
"line": 1, "line": 1,
"part_type": 1,
"count": 100, "count": 100,
"part_key": "material-1", "part_key": "material-1",
"part_name": "Деталь" "part_name": "Деталь"
@@ -765,7 +770,6 @@ part_type - Перечисление (Enum)
"spent_parts": [ "spent_parts": [
{ {
"line": 1, "line": 1,
"part_type": 1,
"count": 100, "count": 100,
"part_key": "material-1", "part_key": "material-1",
"part_name": "Деталь" "part_name": "Деталь"
@@ -810,142 +814,187 @@ part_type - Перечисление (Enum)
### ✅ `GET /api/v1/service_orders` ### ✅ `GET /api/v1/service_orders`
Описание: Ответ содержит массив из хешей содержащих 1С ключей документов планового ТО Описание: Ответ содержит массив из хешей, содержащих 1С ключ заявок на ТО.
Доступные параметры Доступные параметры:
| Параметр | Назначение | | Параметр | Назначение |
|------------|--------------------------| |--------------|--------------------------------------------------|
| `start_date` | Фильтр по дате документа(начинается от) | | `start_date` | Фильтр по дате документа (начиная от) |
| `end_date` | Фильтр по дате документа(заканчивается до) | | `end_date` | Фильтр по дате документа (заканчивая до) |
```json ```json
[ [
{ {
"external_key": "so-001" "external_key": "so-001"
}, },
{ {
"external_key": "so-002" "external_key": "so-002"
}, }
{ ]
"external_key": "so-003"
}
]
``` ```
--- ---
### ✅ `GET /api/v1/service_orders/so-001` ### ✅ `GET /api/v1/service_orders/so-001`
Описание: Ответ содержит конкретный документ "Планового ТО" Просмотр существующей заявки на ТО. **so-001** — это ключ 1С заявки на ТО.
**Пример успешного ответа:**
```json ```json
{ {
"external_key": "key-1", "external_key": "so-001",
"status": 0, "address_key": "addr-001",
"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": "Комментарий",
"masters": [ "masters": [
{ {
"master_key": "master-key1" "master_key": "master-001"
},
{
"master_key": "master-key2"
} }
] ],
"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 | ❌ | Путь к файлам на файловом сервере |
| Поле | Тип | Обязательно | Описание | status — Перечисление (Enum)
|-----------------------------|----------|-------------|----------------------------------------|
| `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 | ❌ | Заключение |
state - Перечисление (Enum) | Значение | Описание |
|----------|-----------|
| `1` | В работе |
| `2` | Завершено |
| Значение | Описание | **Пример ошибки, заявка не найдена:**
|----------|-------------------------|
| `0` | Новая | ```json
| `1` | В работе | {
| `2` | Завершено | "errors": {
| `3` | Плановая | "id": ["не существует"]
| `4` | Нет акта | }
| `5` | Уточнение | }
| `6` | Ремонт в мастерской. | ```
| `7` | Непринятая |
| `8` | Отклонена |
--- ---
### ✅ `POST /api/v1/service_orders` ### ✅ `POST /api/v1/service_orders`
Создание нового документа "Планового ТО". Создание новой заявки на ТО.
**Тело запроса:** **Тело запроса:**
```json ```json
{ {
"number_in_client_database": "Номер в базе клиента", "external_key": null,
"address_key": "address-key", "number": "SO-2025-001",
"date_of_service": "2025-06-01 10:00:00", "number_in_client_database": "client-123",
"conclusion": "Заключение", "responsible": "Иванов Иван",
"comment": "Комментарий", "comment": "Комментарий",
"date": "2025-04-07T08:30:00Z",
"date_of_service": "2025-04-10T00:00:00Z",
"status": 1,
"address_key": "addr-001",
"masters": [ "masters": [
{ {
"master_key": "master-key1" "master_key": "master-001"
},
{
"master_key": "master-key2"
} }
] ]
} }
``` ```
Ответ соответствует ответу при запросе конкретного документа "Планового ТО" | Поле | Тип | Обязательно | Описание |
|-----------------------------|----------|-------------|-----------------------------------------|
| `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` ### ✅ `PUT /api/v1/service_orders/so-001`
Обновление документа "Планового ТО". Изменение существующей заявки на ТО. **so-001** — это ключ 1С заявки на ТО.
**Тело запроса:** **Тело запроса** (аналогично POST, но `external_key` всегда заполнен):
```json ```json
{ {
"number_in_client_database": "Номер в базе клиента", "external_key": "so-001",
"address_key": "address-key", "number": "SO-2025-001",
"date_of_service": "2025-06-01 10:00:00", "number_in_client_database": "client-123",
"conclusion": "Заключение", "responsible": "Иванов Иван",
"comment": "Комментарий", "comment": "Обновлённый комментарий",
"date": "2025-04-07T08:30:00Z",
"date_of_service": "2025-04-12T00:00:00Z",
"status": 2,
"address_key": "addr-001",
"masters": [ "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"
}
```
--- ---