public/eurostyle-server-api-requirements

Files

Ruzal 36f1dead41 Обновить eurostyle-server-api-requirements.md

2025-09-17 10:16:29 +03:00

28 KiB

Raw Blame History

📡 API-документация для внешнего поставщика данных

Приложение будет обращаться к вашему API, чтобы синхронизировать базу данных. Ниже описано, какие endpoint'ы мы ожидаем, какие данные получать, и какие форматы поддерживать.

📚 Таблица endpoint'ов

Метод	Endpoint	Описание
GET	`/api/v1/brands`	Список брендов
GET	`/api/v1/customers`	Список контрагентов (юр лиц компании)
GET	`/api/v1/addresses`	Список адресов (обьектов)
GET	`/api/v1/masters`	Список мастеров
GET	`/api/v1/warehouses`	Список складов
GET	`/api/v1/parts`	Номенклатура (расходников)
GET	`/api/v1/remainders`	Список Остатков по складам
GET	`/api/v1/defects`	Список неисправностей
GET	`/api/v1/jobs`	Список услуг
GET	`/api/v1/product_instances`	Список оборудования
GET	`/api/v1/unit_of_measures`	Список единиц измерения
GET	`/api/v1/users`	Список пользователей
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`	Изменение планового ТО.

🔎 Детали по каждому endpoint’у

✅ `GET /api/v1/brands`

[
  {
    "external_key": "brand-001",
    "name": "CoolBrand"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	Уникальный ID бренда
`name`	string	✅	Название бренда

✅ `GET /api/v1/customers`

[
  {
    "external_key": "cust-001",
    "name": "ООО Ромашка"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	Уникальный ID клиента
`name`	string	✅	Название клиента

✅ `GET /api/v1/addresses`

[
  {
    "external_key": "addr-001",
    "name": "ул. Техническая, 10",
    "brand_key": "brand-001",
    "customer_key": "cust-001",
    "master_key": "master-001",
    "serviced_from": "2025-01-01",
    "serviced_by": "2025-12-01",
    "comment": "Пункт обслуживания"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	ID адреса
`name`	string	✅	Название или адрес
`brand_key`	string	✅	Связь с брендом
`customer_key`	string	✅	Связь с клиентом
`master_key`	string	✅	Прикреплённый мастер
`serviced_from`	date	❌	Дата начала сервисного обслуживания
`serviced_by`	date	❌	Дата завершения сервисного обслуживания
`comment`	string	❌	Комментарий

✅ `GET /api/v1/masters`

[
  {
    "external_key": "master-001",
    "name": "Иванов Иван"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	ID мастера
`name`	string	✅	Имя мастера

✅ `GET /api/v1/warehouses`

[
  {
    "external_key": "wh-001",
    "name": "Главный склад",
    "master_key": "ms-001"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	ID склада
`name`	string	✅	Название склада
`master_key`	string	✅	Мастер, к которому привязан

✅ `GET /api/v1/parts`

[
  {
    "external_key": "part-001",
    "name": "Прокладка",
    "unit_of_measure_key": "uom-001"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	ID детали
`name`	string	✅	Название детали
`unit_of_measure_key`	string	✅	ID Единицы измерения

✅ `GET /api/v1/remainders`

[
  {
    "warehouse_key": "wh-001",
    "part_key": "part-001",
    "quantity": 12.5,
    "unit_of_measure_key": "uom-001"
  }
]

Поле	Тип	Обязательно	Описание
`warehouse_key`	string	✅	ID склада
`part_key`	string	✅	ID детали
`quantity`	number	✅	Кол-во в наличии
`unit_of_measure_key`	string	✅	ID единицы измерения

✅ `GET /api/v1/defects`

[
  {
    "external_key": "def-001",
    "name": "Протечка"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	ID дефекта
`name`	string	✅	Название дефекта

✅ `GET /api/v1/jobs`

[
  {
    "external_key": "job-001",
    "name": "Замена масла",
    "code": "JOB-999"
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	ID работы
`name`	string	✅	Название
`code`	string	✅	Внутренний код

✅ `GET /api/v1/product_instances`

[
  {
    "external_key": "pi-001",
    "address_key": "addr-001",
    "name": "Котёл Bosch",
    "serial_number": "SN12345",
    "inventory_number": "INV98765",
    "warranty": true
  }
]

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	ID устройства
`address_key`	string	✅	Привязка к адресу
`name`	string	✅	Название
`serial_number`	string	❌	Серийный номер
`inventory_number`	string	❌	Инвентарный номер
`warranty`	boolean	❌	Есть ли гарантия?

✅ `GET /api/v1/unit_of_measures`

[
  {
    "external_key": "uom-001",
    "name": "шт"
  }
]

✅ `GET /api/v1/users`

[
  {
    "login": "user-001",
    "password": "password1",
    "role": 1,
    "master_key": "master-001",
    "customer_key": "cust-001"
  }
]

Поле	Тип	Обязательно	Описание
`login`	string	✅	Логин пользователя
`password`	string	✅	Хэшированный пароль
`role`	number	✅	Роль
`master_key`	string	❌	ID мастера
`customer_key`	string	❌	ID контрагента

role - Перечисление (Enum)

Значение	Описание
`0`	Оператор
`1`	Клиент
`2`	Мастер

✅ `GET /api/v1/repair_orders`

Описание: Ответ содержит массив из хешей содержащих 1С ключ заявок на ремонт

  [
    {
      "external_key": "ro-001"
    },
    {
      "external_key": "ro-002"
    },
    {
      "external_key": "ro-003"
    }
  ]

✅ `GET /api/v1/repair_orders/ro-001`

Просмотр существующей заявки на ремонт. ro-001 - это ключ 1С заявки на ремонт.

Пример успешного ответа, когда заявка на ремонт найдена:

{
  "external_key": "ro-001",
  "customer_key": "cust-001",
  "address_key": "UPDATED-addr-001",
  "warehouse_key": "UPDATED-warehouse-001",
  "brand_key": "brand-001",
  "master_key": "master-001",
  "required_parts": [
    {
      "line": 1,
      "count": 100,
      "part_key": "material-1",
      "part_name": "Деталь"
    },
    {
      "line": 2,
      "count": 200,
      "part_key": "material-2",
      "part_name": "Деталь 2"
    }
  ],
  "spent_parts": [
    {
      "line": 1,
      "count": 100,
      "part_key": "material-1",
      "part_name": "Деталь"
    },
    {
      "line": 2,
      "count": 200,
      "part_key": "material-2",
      "part_name": "Деталь 2"
    }
  ],
  "jobs": [
    {
      "line": 1,
      "code": "code-1",
      "job_key": "job-1",
      "name": "услуга 1",
      "count": 1
    }
  ],
  "product_instances": [
    {
      "line": 1,
      "product_instance_key": "product_instance_key_1",
      "name": "оборудование-1",
      "serial_number": "123",
      "inventory_number": "1",
      "warranty": true
    }
  ],
  "files_path": "\\Shared\\file.txt",
  "contact_person_name": "Петров Петр",
  "number_in_client_database": "number_in_client_database_1",
  "submission_date": "2025-04-07T08:30:00Z",
  "accepted_at": "2025-04-07T09:00:00Z",
  "master_arrival_at": "2025-04-07T10:15:00Z",
  "fact_execution_date": "2025-04-07T12:45:00Z",
  "expected_date": "2025-04-07T13:00:00Z",
  "order_type": 0,
  "status": 1,
  "defect_key": "def-001",
  "call_reason": "Капает из фильтра",
  "conclusion": "Прокладка изношена"
}

Поле	Тип	Обязательно	Описание
`external_key`	string	✅	Уникальный ID заявки
`customer_key`	string	✅	Ссылка на контрагента
`address_key`	string	✅	Ссылка на адрес
`warehouse_key`	string	✅	Ссылка на склад
`brand_key`	string	✅	Ссылка на бренд
`master_key`	string	✅	Мастер
`contact_person_name`	string	❌	Имя контактного лица
`number_in_client_database`	string	❌	Номер в базе клиента
`submission_date`	datetime	❌	Дата поступления заявки
`accepted_at`	datetime	❌	Мастер принял
`master_arrival_at`	datetime	❌	Мастер прибыл
`fact_execution_date`	datetime	❌	Когда работа была фактически завершена
`expected_date`	datetime	❌	Плановая дата исполнения
`order_type`	numeric	✅	Тип заявки (enum)
`status`	numeric	✅	Статус заявки (enum)
`defect_key`	string	❌	Ссылка на неисправность
`call_reason`	text	❌	Причина вызова
`conclusion`	text	❌	Заключение

order_type - Перечисление (Enum)

Значение	Описание
`0`	Плановые работы
`1`	Техническое обслуживание
`2`	Вызов

status - Перечисление (Enum)

Значение	Описание
`1`	Новая
`2`	В работе
`4`	Плановая
`3`	Завершено
`9`	Отклонена

part_type - Перечисление (Enum)

Значение	Описание
`0`	Затраченый
`1`	Требуемый

✅ `GET /api/v1/repair_orders/999`

Просмотр несуществующей заявки на ремонт.

Пример ошибки, заявка не найдена:

{
  "errors": {
    "id": ["не существует"]
  }
}

✅ `POST /api/v1/repair_orders`

Создание новой заявки на ремонт.

Тело запроса:

{
  "customer_key": "cust-001",
  "address_key": "addr-001",
  "warehouse_key": "ware-001",
  "brand_key": "brand-001",
  "master_key": "master-001",
  "contact_person_name": "Петров Петр",
  "number_in_client_database": "number_in_client_database_1",
  "submission_date": "2025-04-07T08:30:00Z",
  "accepted_at": "2025-04-07T09:00:00Z",
  "master_arrival_at": "2025-04-07T10:15:00Z",
  "fact_execution_date": "2025-04-07T12:45:00Z",
  "expected_date": "2025-04-07T13:00:00Z",
  "order_type": 0,
  "status": 1,
  "defect_key": "def-001",
  "call_reason": "Капает из фильтра",
  "conclusion": "Прокладка изношена",
  "product_instances": [
    {
      "line": 1,
      "external_key": "pi-001"
    },
    {
      "line": 2,
      "external_key": "pi-002"
    }
  ],
  "required_parts": [
    {
      "line": 1,
      "external_key": "part-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "part-002",
      "count": 10
    }
  ],
  "spent_parts": [
    {
      "line": 1,
      "external_key": "part-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "part-002",
      "count": 10
    }
  ],
  "jobs": [
    {
      "line": 1,
      "external_key": "job-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "job-002",
       "count": 10
    }
  ]  
}

Пример успешного ответа когда заявка на ремонт успешно создана:

{
  "external_key": "ro-001",
  "customer_key": "cust-001",
  "address_key": "UPDATED-addr-001",
  "warehouse_key": "UPDATED-warehouse-001",
  "brand_key": "brand-001",
  "master_key": "master-001",
  "required_parts": [
    {
      "line": 1,
      "part_type": 1,
      "count": 100,
      "part_key": "material-1",
      "part_name": "Деталь"
    }
  ],
  "spent_parts": [
    {
      "line": 1,
      "part_type": 1,
      "count": 100,
      "part_key": "material-1",
      "part_name": "Деталь"
    }
  ],
  "jobs": [
    {
      "line": 1,
      "code": "code-1",
      "job_key": "job-1",
      "name": "услуга 1",
      "count": 1
    }
  ],
  "product_instances": [
    {
      "line": 1,
      "product_instance_key": "product_instance_key_1",
      "name": "оборудование-1",
      "serial_number": "123",
      "inventory_number": "1",
      "warranty": true
    }
  ],
  "files_path": "\\Shared\\",
  "contact_person_name": "Петров Петр",
  "number_in_client_database": "number_in_client_database_1",
  "submission_date": "2025-04-07T08:30:00Z",
  "accepted_at": "2025-04-07T09:00:00Z",
  "master_arrival_at": "2025-04-07T10:15:00Z",
  "fact_execution_date": "2025-04-07T12:45:00Z",
  "expected_date": "2025-04-07T13:00:00Z",
  "order_type": 0,
  "status": 1,
  "defect_key": "def-001",
  "call_reason": "Капает из фильтра",
  "conclusion": "Прокладка изношена"
}

Создание новой заявки на ремонт с ошибкой - пустое поле master_key.

Тело запроса:

{
  "customer_key": "cust-001",
  "address_key": "addr-001",
  "warehouse_key": "warehouse-001",
  "brand_key": "brand-001",
  "master_key": "",
  "contact_person_name": "Петров Петр",
  "number_in_client_database": "number_in_client_database_1",
  "submission_date": "2025-04-07T08:30:00Z",
  "accepted_at": "2025-04-07T09:00:00Z",
  "master_arrival_at": "2025-04-07T10:15:00Z",
  "fact_execution_date": "2025-04-07T12:45:00Z",
  "expected_date": "2025-04-07T13:00:00Z",
  "order_type": 0,
  "status": 1,
  "defect_key": "def-001",
  "call_reason": "Капает из фильтра",
  "conclusion": "Прокладка изношена",
  "product_instances": [
    {
      "line": 1,
      "external_key": "pi-001"
    },
    {
      "line": 2,
      "external_key": "pi-002"
    }
  ],
  "required_parts": [
    {
      "line": 1,
      "external_key": "part-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "part-002",
      "count": 10
    }
  ],
  "spent_parts": [
    {
      "line": 1,
      "external_key": "part-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "part-002",
      "count": 10
    }
  ],
  "jobs": [
    {
      "line": 1,
      "external_key": "job-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "job-002",
      "count": 10
    }
  ]
}

Ответ HTTP код 422:

{
  "errors": {
    "master_key": ["не может быть пустым"]
  }
}

✅ `PUT /api/v1/repair_orders/rc-001`

Изменение существующей заявки на ремонт. Где rc-001 это ключ 1С заявки на ремонт

Тело запроса:

{
  "customer_key": "cust-001",
  "address_key": "addr-001",
  "warehouse_key": "warehouse-001",
  "brand_key": "brand-001",
  "master_key": "master-001",
  "contact_person_name": "Петров Петр",
  "number_in_client_database": "number_in_client_database_1",
  "submission_date": "2025-04-07T08:30:00Z",
  "accepted_at": "2025-04-07T09:00:00Z",
  "master_arrival_at": "2025-04-07T10:15:00Z",
  "fact_execution_date": "2025-04-07T12:45:00Z",
  "expected_date": "2025-04-07T13:00:00Z",
  "order_type": 0,
  "status": 1,
  "defect_key": "def-001",
  "call_reason": "Капает из фильтра",
  "conclusion": "Прокладка изношена",
  "product_instances": [
    {
      "line": 1,
      "external_key": "pi-001"
    },
    {
      "line": 2,
      "external_key": "pi-002"
    }
  ],
  "required_parts": [
    {
      "line": 1,
      "external_key": "part-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "part-002",
      "count": 10
    }
  ],
  "spent_parts": [
    {
      "line": 1,
      "external_key": "part-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "part-002",
      "count": 10
    }
  ],
  "jobs": [
    {
      "line": 1,
      "external_key": "job-001",
      "count": 10
    },
    {
      "line": 2,
      "external_key": "job-002",
      "count": 10
    }
  ]
}

Пример успешного ответа когда заявка на ремонт успешно обновлена:

{
  "external_key": "ro-001",
  "customer_key": "cust-001",
  "address_key": "UPDATED-addr-001",
  "warehouse_key": "UPDATED-warehouse-001",
  "brand_key": "brand-001",
  "master_key": "master-001",
  "required_parts": [
    {
      "line": 1,
      "part_type": 1,
      "count": 100,
      "part_key": "material-1",
      "part_name": "Деталь"
    }
  ],
  "spent_parts": [
    {
      "line": 1,
      "part_type": 1,
      "count": 100,
      "part_key": "material-1",
      "part_name": "Деталь"
    }
  ],
  "jobs": [
    {
      "line": 1,
      "code": "code-1",
      "job_key": "job-1",
      "name": "услуга 1",
      "count": 1
    }
  ],
  "product_instances": [
    {
      "line": 1,
      "product_instance_key": "product_instance_key_1",
      "name": "оборудование-1",
      "serial_number": "123",
      "inventory_number": "1",
      "warranty": true
    }
  ],
  "files_path": "\\Shared\\",
  "contact_person_name": "Петров Петр",
  "number_in_client_database": "number_in_client_database_1",
  "submission_date": "2025-04-07T08:30:00Z",
  "accepted_at": "2025-04-07T09:00:00Z",
  "master_arrival_at": "2025-04-07T10:15:00Z",
  "fact_execution_date": "2025-04-07T12:45:00Z",
  "expected_date": "2025-04-07T13:00:00Z",
  "order_type": 0,
  "status": 1,
  "defect_key": "def-001",
  "call_reason": "Капает из фильтра",
  "conclusion": "Прокладка изношена"
}

✅ `GET /api/v1/service_orders`

Описание: Ответ содержит массив из хешей содержащих 1С ключей документов планового ТО

Доступные параметры

Параметр	Назначение
`start_date`	Фильтр по дате документа(начинается от)
`end_date`	Фильтр по дате документа(заканчивается до)

  [
    {
      "external_key": "so-001"
    },
    {
      "external_key": "so-002"
    },
    {
      "external_key": "so-003"
    }
  ]

✅ `GET /api/v1/service_orders/so-001`

Описание: Ответ содержит конкретный документ "Планового ТО"

  {
  "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": "Комментарий",
  "masters": [
    {
      "master_key": "master-key1"
    },
    {
      "master_key": "master-key2"
    }
  ]
}

Описание полей:

Поле	Тип	Обязательно	Описание
`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)

Значение	Описание
`0`	Новая
`1`	В работе
`2`	Завершено
`3`	Плановая
`4`	Нет акта
`9`	Отложенная
`6`	Ремонт в мастерской.
`7`	Непринятая
`8`	Отклонена

✅ `POST /api/v1/service_orders`

Создание нового документа "Планового ТО".

Тело запроса:

{
  "number_in_client_database": "Номер в базе клиента",
  "address_key": "address-key",
  "date_of_service": "2025-06-01 10:00:00",
  "conclusion": "Заключение",
  "comment": "Комментарий",
  "masters": [
    {
      "master_key": "master-key1"
    },
    {
      "master_key": "master-key2"
    }
  ]
}

Ответ соответствует ответу при запросе конкретного документа "Планового ТО"

✅ `PUT /api/v1/service_orders/so-001`

Обновление документа "Планового ТО".

Тело запроса:

{
  "number_in_client_database": "Номер в базе клиента",
  "address_key": "address-key",
  "date_of_service": "2025-06-01 10:00:00",
  "conclusion": "Заключение",
  "comment": "Комментарий",
  "masters": [
    {
      "master_key": "master-key1"
    },
    {
      "master_key": "master-key2"
    }
  ]
}

Ответ соответствует ответу при запросе конкретного документа "Планового ТО"

🔄 Поддержка изменений

Во всех API справочников , а также в API получения списка заявок на ремонт в строке адреса возможна передача параметра ?updated_since=, в ответ на этот запрос будет соджержать данные изменившиеся только после этой даты:

GET /api/v1/brands?updated_since=2025-04-01T00:00:00Z

HTTP Коды ошибок

Код ошибки	Сообщение
`400`	Некорректные данные в запросе (например, отсутствуют обязательные поля)
`404`	Невозможно найти один из связанных объектов (например, контрагент или адрес)
`500`	Внутренняя ошибка сервера

Общие сведения

Часть API	Описание
Формат данных	JSON
Кодировка	UTF-8
Формат даты/времени	ISO 8601 (`2025-04-09T15:20:00Z`)
Аутентификация	Bearer Token (передается в заголовке `Authorization`)
Обработка ошибок	При ошибках возвращается HTTP-статус и JSON-объект с деталями ошибки

28 KiB Raw Blame History Unescape Escape

📡 API-документация для внешнего поставщика данных

📚 Таблица endpoint'ов

🔎 Детали по каждому endpoint’у

✅ GET /api/v1/brands

✅ GET /api/v1/customers

✅ GET /api/v1/addresses

✅ GET /api/v1/masters

✅ GET /api/v1/warehouses

✅ GET /api/v1/parts

✅ GET /api/v1/remainders

✅ GET /api/v1/defects

✅ GET /api/v1/jobs

✅ GET /api/v1/product_instances

✅ GET /api/v1/unit_of_measures

✅ GET /api/v1/users

✅ GET /api/v1/repair_orders

✅ GET /api/v1/repair_orders/ro-001

✅ GET /api/v1/repair_orders/999

✅ POST /api/v1/repair_orders

✅ PUT /api/v1/repair_orders/rc-001

✅ GET /api/v1/service_orders

✅ GET /api/v1/service_orders/so-001

✅ POST /api/v1/service_orders

✅ PUT /api/v1/service_orders/so-001

🔄 Поддержка изменений

HTTP Коды ошибок

Общие сведения

28 KiB

Raw Blame History

✅ `GET /api/v1/brands`

✅ `GET /api/v1/customers`

✅ `GET /api/v1/addresses`

✅ `GET /api/v1/masters`

✅ `GET /api/v1/warehouses`

✅ `GET /api/v1/parts`

✅ `GET /api/v1/remainders`

✅ `GET /api/v1/defects`

✅ `GET /api/v1/jobs`

✅ `GET /api/v1/product_instances`

✅ `GET /api/v1/unit_of_measures`

✅ `GET /api/v1/users`

✅ `GET /api/v1/repair_orders`

✅ `GET /api/v1/repair_orders/ro-001`

✅ `GET /api/v1/repair_orders/999`

✅ `POST /api/v1/repair_orders`

✅ `PUT /api/v1/repair_orders/rc-001`

✅ `GET /api/v1/service_orders`

✅ `GET /api/v1/service_orders/so-001`

✅ `POST /api/v1/service_orders`

✅ `PUT /api/v1/service_orders/so-001`