API | Работа с документами
Документ - это базовая модель по работе с различными бизнес-процессами.
Базовая структура документа#
Документы содержат общую базовую структуру и имеют набор стандартных полей:
| Поле | Тип | Описание |
|---|---|---|
document_id | UUID | Идентификатор документа в системе MarkingHub |
status | string | См. справочник "Статусы документов". |
external_id | string | Идентификатор документа во внешней системе (СУЗ, ГИСМТ и т.п.) |
external_status | string | Статус документа во внешней системе (СУЗ, ГИСМТ и т.п.) |
direction | string | См. справочник "Направления документов". |
created | datetime | Дата создание документа в системе MarkingHub |
product_group | string | См. справочник "Товарные группы". |
stock | string | Идентификатор склада в системе MarkingHub |
doctype | string | Тип документа в системе MarkingHub |
data | object | Объект которые содержит основной атрибутивный состав документа. Зависит от типа документа. |
extra | object | Объект которые содержит произваольные данные которые можно использовать при интеграции. |
children | array | Массив позиций документа. |
children_generator | array | Параметры для автозаполнения позиций. |
Методы API по процессам#
Для каждого типа документа есть свои урлы с общим набором методов.
| Метод | URL | Описание |
|---|---|---|
GET | /bp/processes/{process_name}/ | Список документов |
POST | /bp/processes/{process_name}/ | Создание нового документа |
POST | /bp/processes/{process_name}/execute/ | Отправка документов на обработку |
POST | /bp/processes/{process_name}/fetch_update/ | Обновление статуса документов из внешней системы (СУЗ, ГИСМТ, НК и тд) |
POST | /bp/processes/{process_name}/load_file/ | Импорт нового документа из CSV или XLSX |
GET | /bp/processes/{process_name}/{document_id}/ | Получение одного документа по ID |
PATCH | /bp/processes/{process_name}/{document_id}/ | Изменение документа |
DELETE | /bp/processes/{process_name}/{document_id}/ | Удаление документа |
POST | /bp/processes/{process_name}/{document_id}/renew/ | Сброс документа до состояния "Черновик" |
GET | /bp/processes/{process_name}/{document_id}/children/ | Список позиций документа |
POST | /bp/processes/{process_name}/{document_id}/children/create/ | Создание новой позиции документа |
GET | /bp/processes/{process_name}/{document_id}/children/{child_id}/ | Получение одной позиции по ID |
DELETE | /bp/processes/{process_name}/{document_id}/children/{child_id}/ | Удаление одной позиции по ID |
Методы API без привязки к процессам#
Если нужно делать выборки или манипуляции по документам без привязки к определенному процессу, есть следующие запросы:
| Метод | URL | Описание |
|---|---|---|
GET | /bp/document/document/ | Список все документов. Подробнее в Swagger |
POST | /bp/document/search/ | Поиск документов с помощью MHQL. Подробнее в Swagger |
GET | /bp/document/document/{document_id}/ | Получение одного документа по ID. Подробнее в Swagger |
DELETE | /bp/document/document/{document_id}/ | Удаление одного документа по ID. Подробнее в Swagger |
Обработка документов#
Документы подразумевают что они должны быть обработаны. В зависимости от типа документа, обработка происходит на различных уровнях:
- Обработка внутри системы (Запросы на печать, перемещение между складами)
- Обработка через СУЗ (Заказы на эмиссию)
- Обработка через ГИС МТ (Ввод в оборот, Отгрузка, Приемка, Агрегация и т.д.)
Отправить документ на обработку можно только в статусе Черновик.
После отправки документа на обработку, документ переходит в статус В обработке, и находится в этом статусе до перехода в статусы Обработан или Ошибка