Поставки

8 статьи Максим От Максим

Методы для поставок, их статусов и оплаты

Поставки

Поставки: закупки материалов и продуктов у поставщиков. Поставка пополняет остатки на складе и обновляет цены материалов. Через API поставки можно создавать, редактировать и удалять, менять статус и статус оплаты, получать список поставок и данные поставки. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/purchases/add | Создает поставку | | v1/purchases/edit | Изменяет поставку | | v1/purchases/delete | Удаляет поставку | | v1/purchases/update_status | Меняет статус поставки | | v1/purchases/update_payment | Меняет статус оплаты | | v1/purchases/get_list | Возвращает поставки компании | | v1/purchases/get_entry | Возвращает данные поставки со строками |

Создание поставки

Создает поставку. Статус поставки берется из настройки Статус новой поставки по умолчанию в настройках системы, а от статуса зависит, поступят ли материалы и продукты на склад сразу (см. Смену статуса поставки). v1/purchases/add.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | supplier_id | int | supplier_id или supplier_name | ID существующего поставщика | | supplier_name | string | supplier_id или supplier_name | Имя поставщика. Если такого нет, он создается из полей с префиксом supplier_ | | materials | array | materials или products | Строки материалов | | products | array | materials или products | Строки продуктов | | num | string | Нет | Номер поставки. Если не передан, присваивается следующий номер | | date_placed | string | Нет | Дата заказа поставки. По умолчанию сегодня | | date_received | string | Нет | Дата получения | | materials_storage_id | int | Нет | Склад материалов. По умолчанию склад из настроек | | products_storage_id | int | Нет | Склад продуктов. По умолчанию склад из настроек | | delivery_price | float | Нет | Стоимость доставки. По умолчанию 0 | | discount | float | Нет | Скидка. По умолчанию 0 | | notes | string | Нет | Заметки | Строки поставки Состав поставки передается двумя массивами: materials для материалов и products для продуктов. Нужна хотя бы одна строка в одном из массивов. | Поле | Тип | Обязательное | Описание | |---|---|---|---| | id | int | id или sku | ID материала или продукта | | sku | string | id или sku | Артикул. Продукт ищется и по альтернативным SKU | | amount | float | Да | Количество | | total | float | Да | Сумма строки (не цена за единицу) | | notes | string | Нет | Комментарий к строке | В отличие от заказов, неизвестная позиция не пропускается: запрос отклоняется с ошибкой, и поставка не создается. Поставщик Поставщик указывается одним из двух способов: - supplier_id: ID существующего поставщика, например из v1/suppliers/add; - supplier_name: имя поставщика. Если поставщика с таким именем нет, Controlata создаст его вместе с поставкой из полей ниже. | Поле | Тип | Описание | |---|---|---| | supplier_name | string | Наименование юрлица или имя ИП и физлица | | supplier_type | int | Тип: 1 юрлицо, 2 ИП, 3 физлицо. По умолчанию 1 | | supplier_email | string | Электронная почта | | supplier_phone | string | Телефон | | supplier_address | string | Юридический адрес | | supplier_inn | string | ИНН | | supplier_kpp | string | КПП | | supplier_ogrn | string | ОГРН | | supplier_agreement | string | Договор | | supplier_manager_name | string | Руководитель | | supplier_manager_post | string | Должность руководителя | | supplier_notes | string | Заметки о поставщике | Если переданы оба поля, используется supplier_id, а supplier_* игнорируются. Если поставщик с таким именем уже есть, поставка привязывается к нему, поля supplier_* не обновляются. Пример запроса { "supplier_id": 45, "date_placed": "2026-10-06", "materials_storage_id": 3998, "materials": [ { "sku": "M010", "amount": 0.2, "total": 26000, "notes": "Проверить толщину" }, { "id": 2052, "amount": 10, "total": 4000 } ], "delivery_price": 1500, "notes": "Счет № 118" } Пример ответа { "success": true, "purchase_id": 29645, "num": "15", "status": 1 } num содержит номер поставки, status содержит код статуса, в котором она создана. Ошибки | Ошибка | Причина | |---|---| | No supplier_name or supplier_id in input | Не передан поставщик | | Supplier not found or access denied | Поставщик supplier_id не найден или удален | | Supplier name must not be empty | Пустое supplier_name | | Supplier name must be a string | supplier_name не строка | | Invalid supplier_type value. Must be one of: 1, 2, 3 | Неверный тип нового поставщика | | Storage ID not found | Склад не найден или удален | | Materials is not an array | materials не массив (так же для products) | | No products or materials in input | Не передано ни одной строки | | Line 0 of materials must be an object | Строка не является объектом (вместо 0 будет номер строки) | | SKU or id not set for material 0 | В строке нет ни id, ни sku | | Material with SKU "M010" not found | Позиция не найдена или удалена | | Amount must be greater than 0 for material with SKU "M010" | Количество не передано, не число или не больше 0 после округления | | Total must be 0 or greater for material with SKU "M010" | Сумма строки не передана, не число или меньше 0 | | Invalid notes value for material with SKU "M010". Must be a string | notes в строке не строка | | Notes for material with SKU "M010" are too long: maximum 10000 characters | Комментарий строки длиннее 10 000 символов | | Date is not a valid date in format YYYY-MM-DD | Неверная дата заказа или получения | | Invalid delivery_price value. Must be a number, 0 or greater | Стоимость доставки не число или меньше 0 | | Invalid discount value. Must be a number, 0 or greater | Скидка не число или меньше 0 | В текстах ошибок строк вместо material будет product для строк продуктов, а вместо SKU "M010" будет id 2052, если строка передана по id.

Редактирование поставки

Изменяет поставку. Меняются только переданные поля, остальные остаются прежними. v1/purchases/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | purchase_id | int | Да | ID поставки | | supplier_id | int | Нет | ID поставщика | | supplier_name | string | Нет | Имя поставщика и поля supplier_* | | materials | array | Нет | Строки материалов. Заменяют текущие строки целиком | | products | array | Нет | Строки продуктов. Заменяют текущие строки целиком | | num | string | Нет | Номер поставки | | date_placed | string | Нет | Дата заказа поставки | | date_received | string | Нет | Дата получения. Пустая строка очищает ее | | materials_storage_id | int | Нет | Склад материалов | | products_storage_id | int | Нет | Склад продуктов | | delivery_price | float | Нет | Стоимость доставки | | discount | float | Нет | Скидка | | notes | string | Нет | Заметки | Статус и статус оплаты этим методом не меняются, для них есть v1/purchases/update_status и v1/purchases/update_payment. Строки поставки Строки передаются массивами materials и products. Если передан хотя бы один из массивов, состав заменяется целиком, а непереданный считается пустым. Если не передан ни один, строки не меняются. | Поле | Тип | Обязательное | Описание | |---|---|---|---| | id | int | id или sku | ID материала или продукта | | sku | string | id или sku | Артикул. Продукт ищется и по альтернативным SKU | | amount | float | Да | Количество | | total | float | Да | Сумма строки (не цена за единицу) | | notes | string | Нет | Комментарий к строке | Строки из ответа v1/purchases/get_entry можно отправить обратно без изменений. Пример запроса Изменить стоимость доставки, не передавая строки: { "purchase_id": 29645, "delivery_price": 3000 } Суммы строк останутся 26000 и 4000, а себестоимость станет 28600 и 4400. Цены материалов обновятся по новой себестоимости. Заменить состав поставки: { "purchase_id": 29645, "materials": [ { "sku": "M010", "amount": 0.25, "total": 32500 } ] } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No purchase_id in input | Не передан purchase_id | | Purchase not found or access denied | Поставка не найдена или удалена | | No num in input | Передан пустой num | | The purchase total is 0, so line totals cannot be restored. Pass materials and products explicitly | Итог поставки равен 0, а строки не переданы | | Storage ID is not set | Передан пустой склад | | Storage ID not found | Склад не найден или удален | | Date is not a valid date in format YYYY-MM-DD | Неверная дата. Пустая date_placed тоже отклоняется | | Invalid delivery_price value. Must be a number, 0 or greater | Стоимость доставки не число или меньше 0 | | Invalid discount value. Must be a number, 0 or greater | Скидка не число или меньше 0 | | Materials is not an array | materials не массив (так же для products) | | No products or materials in input | Переданы пустые materials и products | | Material with SKU "M010" not found | Позиция не найдена или удалена | | Supplier not found or access denied | Поставщик supplier_id не найден или удален | | Supplier name must not be empty | Пустое supplier_name | | Invalid supplier_type value. Must be one of: 1, 2, 3 | Неверный тип нового поставщика | Остальные ошибки в строках те же, что в v1/purchases/add.

Удаление поставки

Удаляет поставку. v1/purchases/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | purchase_id | int | Да | ID поставки | Удаление нельзя отменить. Цены материалов и себестоимость продуктов, обновленные поставкой, к прежним значениям не возвращаются. Пример запроса { "purchase_id": 29645 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No purchase_id in input | Не передан purchase_id | | Purchase not found or access denied | Поставка не найдена или уже удалена |

Смена статуса поставки

Меняет статус поставки. От статуса зависит, поступили ли материалы и продукты поставки на склад. v1/purchases/update_status.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | purchase_id | int | Да | ID поставки | | status | int | Да | Новый статус: 0 — План, 1 — Заказана, 3 — Получена | | date_received | string | Нет | Дата получения. Учитывается при переходе в статус «Получена» | Статус 2 «Частично получена» через API не ставится: он появляется, когда часть поставки получают отгрузками в интерфейсе Controlata. date_received учитывается при переходе в «Получена»: она записывается в поставку, и поступление датируется ею. В других статусах date_received игнорируется. Пример запроса { "purchase_id": 29645, "status": 3, "date_received": "2026-10-09" } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No purchase_id in input | Не передано обязательное поле (вместо purchase_id будет имя поля) | | Invalid status value. Must be one of: 0, 1, 3 | Неверный статус, в том числе 2 | | Purchase not found or access denied | Поставка не найдена или удалена | | Date is not a valid date in format YYYY-MM-DD | Неверная date_received |

Смена статуса оплаты поставки

Меняет статус оплаты поставки. Статус оплаты только отмечает, оплачена ли поставка поставщику: на остатки, суммы и статус поставки он не влияет. v1/purchases/update_payment.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | purchase_id | int | Да | ID поставки | | status | int | Да | Статус оплаты: 0 — Не оплачена, 1 — Частично оплачена, 2 — Оплачена | Статус оплаты виден в списке поставок, если в разделе Настройки → Основные включено Показывать статус оплаты поставок. Через API он меняется и возвращается независимо от этой настройки. Пример запроса { "purchase_id": 29645, "status": 2 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No purchase_id in input | Не передано обязательное поле (вместо purchase_id будет имя поля) | | Invalid payment status value. Must be one of: 0, 1, 2 | Неверный статус оплаты | | Purchase not found or access denied | Поставка не найдена или удалена |

Получение списка поставок

Возвращает поставки компании, от новых к старым по дате заказа поставки. Строки поставок в список не входят, их возвращает v1/purchases/get_entry. v1/purchases/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | date_from | string | Нет | Поставки с этой даты заказа включительно | | date_to | string | Нет | Поставки по эту дату заказа включительно | | supplier_id | int | Нет | Только поставки этого поставщика | | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Фильтры по датам работают по date_placed. Без параметров возвращаются все поставки компании. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив purchases с полями поставки: | Поле | Тип | Описание | |---|---|---| | id | int | ID поставки | | num | string | Номер поставки | | status | int | Статус, код из Смены статуса поставки | | payment | int | Статус оплаты, код из Смены статуса оплаты поставки | | date_placed | string | Дата заказа поставки | | date_received | string | Дата получения. Пустая строка, если не задана | | supplier_id | int | ID поставщика | | supplier_name | string | Наименование поставщика | | materials_storage_id | int | Склад материалов | | materials_storage_name | string | Название склада материалов | | products_storage_id | int | Склад продуктов | | products_storage_name | string | Название склада продуктов | | subtotal | float | Сумма строк | | delivery_price | float | Стоимость доставки | | discount | float | Скидка | | total | float | Итого: subtotal плюс delivery_price минус discount | | amount | float | Общее количество, если у всех строк одна единица измерения, иначе null | | lines | int | Число строк | | notes | string | Заметки | Поле total в корне ответа содержит общее число поставок, подходящих под фильтры. Пример запроса { "date_from": "2026-10-01", "supplier_id": 45, "limit": 100, "offset": 0 } Пример ответа { "success": true, "purchases": [ { "id": 29645, "num": "15", "status": 1, "payment": 0, "date_placed": "2026-10-06", "date_received": "", "supplier_id": 45, "supplier_name": "ООО Лесторг", "materials_storage_id": 3998, "materials_storage_name": "Основной склад", "products_storage_id": 3998, "products_storage_name": "Основной склад", "subtotal": 30000, "delivery_price": 1500, "discount": 0, "total": 31500, "amount": null, "lines": 2, "notes": "Счет № 118" } ], "total": 1 } Ошибки | Ошибка | Причина | |---|---| | Date is not a valid date in format YYYY-MM-DD | Неверная date_from или date_to | | Invalid limit value. Must be between 1 and 1000 | Неверный limit | | Invalid offset value. Must be 0 or greater | Неверный offset | | Offset requires limit | Передан offset без limit |

Получение данных поставки

Возвращает данные поставки и ее строки. v1/purchases/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | purchase_id | int | Да | ID поставки | Ответ Объект purchase с полями поставки: | Поле | Тип | Описание | |---|---|---| | id | int | ID поставки | | num | string | Номер поставки | | status | int | Статус, код из Смены статуса поставки | | payment | int | Статус оплаты, код из Смены статуса оплаты поставки | | date_placed | string | Дата заказа поставки | | date_received | string | Дата получения. Пустая строка, если не задана | | supplier_id | int | ID поставщика | | supplier_name | string | Наименование поставщика | | materials_storage_id | int | Склад материалов | | materials_storage_name | string | Название склада материалов | | products_storage_id | int | Склад продуктов | | products_storage_name | string | Название склада продуктов | | subtotal | float | Сумма строк | | delivery_price | float | Стоимость доставки | | discount | float | Скидка | | total | float | Итого: subtotal плюс delivery_price минус discount | | amount | float | Общее количество, если у всех строк одна единица измерения, иначе null | | lines | int | Число строк | | notes | string | Заметки | А также два массива строк поставки: materials и products. Поля строки: | Поле | Тип | Описание | |---|---|---| | id | int | ID материала или продукта | | sku | string | Артикул | | name | string | Название | | amount | float | Количество | | unit | string | Единица измерения | | total | float | Сумма строки | | price | float | Цена за единицу: total, деленный на amount | | cost | float | Себестоимость строки | | position | int | Номер строки в карточке поставки, от 0 | | notes | string | Комментарий к строке. Пустая строка, если его нет | Нумерация position сквозная для обоих массивов: по ней можно восстановить порядок строк, как в карточке поставки. Строки из ответа можно отправить в v1/purchases/edit без изменений: лишние поля игнорируются. Пример запроса { "purchase_id": 29645 } Пример ответа { "success": true, "purchase": { "id": 29645, "num": "15", "status": 1, "payment": 0, "date_placed": "2026-10-06", "date_received": "", "supplier_id": 45, "supplier_name": "ООО Лесторг", "materials_storage_id": 3998, "materials_storage_name": "Основной склад", "products_storage_id": 3998, "products_storage_name": "Основной склад", "subtotal": 30000, "delivery_price": 1500, "discount": 0, "total": 31500, "amount": null, "lines": 2, "notes": "Счет № 118", "materials": [ { "id": 2051, "sku": "M010", "name": "Доска дубовая", "amount": 0.2, "cost": 27300, "unit": "куб. м", "position": 0, "total": 26000, "price": 130000, "notes": "Проверить толщину" }, { "id": 2052, "sku": "M011", "name": "Клей столярный", "amount": 10, "cost": 4200, "unit": "кг", "position": 1, "total": 4000, "price": 400, "notes": "" } ], "products": [] } } Ошибки | Ошибка | Причина | |---|---| | No purchase_id in input | Не передан purchase_id | | Purchase not found or access denied | Поставка не найдена или удалена |