Поставщики

Поставщики

Поставщики: компании и люди, у которых вы закупаете материалы и продукты. Через API их можно создавать, редактировать и удалять, получать список и данные поставщика. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/suppliers/add | Создает поставщика | | v1/suppliers/edit | Изменяет поставщика | | v1/suppliers/delete | Удаляет поставщика | | v1/suppliers/get_list | Возвращает поставщиков компании | | v1/suppliers/get_entry | Возвращает данные поставщика | Поля поставщика | Поле | Тип | Описание | |---|---|---| | id | int | ID поставщика | | type | int | Тип поставщика (см. ниже) | | name | string | Наименование юрлица или имя ИП и физлица | | email | string | Электронная почта | | phone | string | Телефон | | address | string | Юридический адрес | | inn | string | ИНН | | kpp | string | КПП | | ogrn | string | ОГРН | | agreement | string | Договор | | manager_name | string | Руководитель | | manager_post | string | Должность руководителя | | notes | string | Заметки | Файлы поставщика через API не передаются и не возвращаются. Тип поставщика | Значение | Тип | |---|---| | 1 | Юридическое лицо | | 2 | Индивидуальный предприниматель | | 3 | Физическое лицо | Если тип не передан при создании, поставщик создается юридическим лицом (1). Тип можно передать числом или строкой: 2 или "2". API сохраняет все переданные поля независимо от типа. Но в карточке поставщика Controlata показывает только поля, подходящие типу: - ИНН, КПП и юридический адрес: у юрлица и ИП; - ОГРН, руководитель и должность: только у юрлица. Реквизиты ИНН, КПП и ОГРН сохраняются в том виде, в котором переданы: их формат и контрольные цифры не проверяются. Длина поля: ИНН до 12 символов, КПП 9, ОГРН до 15. Уникальность имени и реквизитов тоже не проверяется. Если в Controlata появились дубли, выделите их в списке поставщиков и нажмите Объединить. Поставщики материалов и продуктов Поставщиков можно указать в карточках материалов и продуктов: поле suppliers в методах v1/materials/add, v1/materials/edit, v1/products/add и v1/products/edit принимает ID поставщиков. При удалении поставщик убирается из всех карточек. Поставщик из поставки Создавать поставщика заранее не обязательно. В v1/purchases/add вместо supplier_id можно передать supplier_name и другие поля поставщика с префиксом supplier_ (supplier_type, supplier_email, supplier_phone, supplier_inn и так далее). Тогда Controlata создаст нового поставщика вместе с поставкой. Каждая поставка с supplier_name создает нового поставщика, даже если поставщик с таким именем уже есть. Для постоянных поставщиков сохраните ID на своей стороне и передавайте supplier_id.

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

Создает поставщика. v1/suppliers/add.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | name | string | Да | Наименование юрлица или имя ИП и физлица | | type | int | Нет | Тип: 1 юрлицо, 2 ИП, 3 физлицо. По умолчанию 1 | | email | string | Нет | Электронная почта | | phone | string | Нет | Телефон | | address | string | Нет | Юридический адрес | | inn | string | Нет | ИНН | | kpp | string | Нет | КПП | | ogrn | string | Нет | ОГРН | | agreement | string | Нет | Договор | | manager_name | string | Нет | Руководитель | | manager_post | string | Нет | Должность руководителя | | notes | string | Нет | Заметки | Формат реквизитов и уникальность имени не проверяются: повторный запрос с тем же именем создаст еще одного поставщика. Подробнее о типах и реквизитах в статье Поставщики. Поставщика можно создать и вместе с поставкой, см. v1/purchases/add. Пример запроса { "name": "ООО Лесторг", "email": "sales@lestorg.ru", "phone": "+7 812 300-20-10", "address": "г. Санкт-Петербург, ул. Портовая, д. 8", "inn": "7801234567", "kpp": "780101001", "ogrn": "1037800123456", "agreement": "№ 7 от 15.02.2026", "manager_name": "Сидоров Олег Иванович", "manager_post": "Директор" } Пример ответа { "success": true, "supplier_id": 45 } Ошибки | Ошибка | Причина | |---|---| | No name in input | Не передан name или передан null | | Name must not be empty | Пустое имя | | Name must be a string | В name передан массив или объект | | Invalid type value. Must be one of: 1, 2, 3 | Неверный тип |

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

Изменяет поставщика. Меняются только переданные поля, остальные остаются прежними. Подробнее о частичном редактировании в статье Общие правила. v1/suppliers/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | supplier_id | int | Да | ID поставщика | | name | string | Нет | Наименование юрлица или имя ИП и физлица | | type | int | Нет | Тип: 1 юрлицо, 2 ИП, 3 физлицо | | email | string | Нет | Электронная почта | | phone | string | Нет | Телефон | | address | string | Нет | Юридический адрес | | inn | string | Нет | ИНН | | kpp | string | Нет | КПП | | ogrn | string | Нет | ОГРН | | agreement | string | Нет | Договор | | manager_name | string | Нет | Руководитель | | manager_post | string | Нет | Должность руководителя | | notes | string | Нет | Заметки | Чтобы очистить поле, передайте пустую строку. Значение null в текстовом поле тоже очищает его, а в type оставляет тип прежним. Имя проверяется, только если передано. Поэтому поставщика с пустым именем можно отредактировать, не передавая name. Удаленного поставщика изменить нельзя. Пример запроса { "supplier_id": 45, "email": "opt@lestorg.ru", "notes": "Доставка по вторникам" } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No supplier_id in input | Не передан supplier_id | | Supplier not found or access denied | Поставщик не найден или удален | | Name must not be empty | Передано пустое имя | | Name must be a string | В name передан null, массив или объект | | Invalid type value. Must be one of: 1, 2, 3 | Неверный тип |

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

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

Список поставщиков

Возвращает поставщиков компании, отсортированных по имени. Удаленные поставщики в список не входят. v1/suppliers/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Без limit возвращается весь список. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив suppliers со всеми полями поставщика (см. Поставщики). Поле total содержит общее число поставщиков. Пример запроса { "limit": 100, "offset": 0 } Пример ответа { "success": true, "suppliers": [ { "id": "46", "type": "2", "name": "ИП Кузнецов Андрей Викторович", "email": "kuznecov.furnitura@example.com", "phone": "+7 903 210-11-22", "address": "г. Тула, ул. Мира, д. 14", "inn": "710512345678", "kpp": "", "ogrn": "", "agreement": "", "manager_name": "", "manager_post": "", "notes": "" }, { "id": "45", "type": "1", "name": "ООО Лесторг", "email": "opt@lestorg.ru", "phone": "+7 812 300-20-10", "address": "г. Санкт-Петербург, ул. Портовая, д. 8", "inn": "7801234567", "kpp": "780101001", "ogrn": "1037800123456", "agreement": "№ 7 от 15.02.2026", "manager_name": "Сидоров Олег Иванович", "manager_post": "Директор", "notes": "Доставка по вторникам" } ], "total": 2 } Ошибки | Ошибка | Причина | |---|---| | 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/suppliers/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | supplier_id | int | Да | ID поставщика | Удаленный поставщик не возвращается. Ответ Объект supplier со всеми полями поставщика (см. Поставщики). Поля из ответа можно передать в v1/suppliers/edit без изменений, добавив supplier_id. Пример запроса { "supplier_id": 45 } Пример ответа { "success": true, "supplier": { "id": "45", "type": "1", "name": "ООО Лесторг", "email": "opt@lestorg.ru", "phone": "+7 812 300-20-10", "address": "г. Санкт-Петербург, ул. Портовая, д. 8", "inn": "7801234567", "kpp": "780101001", "ogrn": "1037800123456", "agreement": "№ 7 от 15.02.2026", "manager_name": "Сидоров Олег Иванович", "manager_post": "Директор", "notes": "Доставка по вторникам" } } Ошибки | Ошибка | Причина | |---|---| | No supplier_id in input | Не передан supplier_id | | Supplier not found or access denied | Поставщик не найден или удален |