Покупатели

Покупатели

Покупатели: компании и люди, которым вы продаете продукцию. Через API их можно создавать, редактировать и удалять, получать список и данные покупателя. Пути методов указаны относительно базового адреса API, а общие для всех методов правила (авторизация, формат запросов, частичное редактирование, постраничная выдача) описаны в статьях Обзор API и Общие правила. Методы | Метод | Что делает | |---|---| | v1/customers/add | Создает покупателя | | v1/customers/edit | Изменяет покупателя | | v1/customers/delete | Удаляет покупателя | | v1/customers/get_list | Возвращает покупателей компании | | v1/customers/get_entry | Возвращает данные покупателя | Поля покупателя | Поле | Тип | Описание | |---|---|---| | id | int | ID покупателя | | type | int | Тип покупателя (см. ниже) | | name | string | Наименование юрлица или имя ИП и физлица | | email | string | Электронная почта | | phone | string | Телефон | | address_legal | string | Юридический адрес | | address_real | string | Адрес доставки | | inn | string | ИНН | | kpp | string | КПП | | ogrn | string | ОГРН | | agreement | string | Договор | | manager_name | string | Руководитель | | manager_post | string | Должность руководителя | | notes | string | Заметки | Файлы покупателя через API не передаются и не возвращаются. Тип покупателя | Значение | Тип | |---|---| | 1 | Юридическое лицо | | 2 | Индивидуальный предприниматель | | 3 | Физическое лицо | Если тип не передан при создании, покупатель создается физическим лицом (3). Тип можно передать числом или строкой: 1 или "1". API сохраняет все переданные поля независимо от типа. Но в карточке покупателя Controlata показывает только поля, подходящие типу: - ИНН, КПП и юридический адрес: у юрлица и ИП; - ОГРН, руководитель и должность: только у юрлица. Реквизиты ИНН, КПП и ОГРН сохраняются в том виде, в котором переданы: их формат и контрольные цифры не проверяются. Длина поля: ИНН до 12 символов, КПП 9, ОГРН до 15. Уникальность имени и реквизитов тоже не проверяется. Если в Controlata появились дубли, выделите их в списке покупателей и нажмите Объединить. Покупатель из заказа Создавать покупателя заранее не обязательно. В v1/orders/add вместо customer_id можно передать customer_name и другие поля покупателя с префиксом customer_ (customer_type, customer_email, customer_phone, customer_inn и так далее). Тогда Controlata создаст нового покупателя вместе с заказом. Каждый заказ с customer_name создает нового покупателя, даже если покупатель с таким именем уже есть. Для постоянных покупателей сохраните ID на своей стороне и передавайте customer_id.

Создание покупателя

Создает покупателя. v1/customers/add.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | name | string | Да | Наименование юрлица или имя ИП и физлица | | type | int | Нет | Тип: 1 юрлицо, 2 ИП, 3 физлицо. По умолчанию 3 | | email | string | Нет | Электронная почта | | phone | string | Нет | Телефон | | address_legal | string | Нет | Юридический адрес | | address_real | string | Нет | Адрес доставки | | inn | string | Нет | ИНН | | kpp | string | Нет | КПП | | ogrn | string | Нет | ОГРН | | agreement | string | Нет | Договор | | manager_name | string | Нет | Руководитель | | manager_post | string | Нет | Должность руководителя | | notes | string | Нет | Заметки | Формат реквизитов и уникальность имени не проверяются: повторный запрос с тем же именем создаст еще одного покупателя. Подробнее о типах и реквизитах в статье Покупатели. Покупателя можно создать и вместе с заказом, см. v1/orders/add. Пример запроса { "name": "ООО Мебельный двор", "type": 1, "email": "zakaz@mebdvor.ru", "phone": "+7 495 123-45-67", "address_legal": "г. Москва, ул. Лесная, д. 5", "address_real": "г. Москва, ул. Складская, д. 12", "inn": "7701234567", "kpp": "770101001", "ogrn": "1027700123456", "agreement": "№ 15 от 10.01.2026", "manager_name": "Иванов Петр Сергеевич", "manager_post": "Генеральный директор" } Пример ответа { "success": true, "customer_id": 512 } Ошибки | Ошибка | Причина | |---|---| | 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/customers/edit.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | customer_id | int | Да | ID покупателя | | name | string | Нет | Наименование юрлица или имя ИП и физлица | | type | int | Нет | Тип: 1 юрлицо, 2 ИП, 3 физлицо | | email | string | Нет | Электронная почта | | phone | string | Нет | Телефон | | address_legal | string | Нет | Юридический адрес | | address_real | string | Нет | Адрес доставки | | inn | string | Нет | ИНН | | kpp | string | Нет | КПП | | ogrn | string | Нет | ОГРН | | agreement | string | Нет | Договор | | manager_name | string | Нет | Руководитель | | manager_post | string | Нет | Должность руководителя | | notes | string | Нет | Заметки | Чтобы очистить поле, передайте пустую строку. Значение null в текстовом поле тоже очищает его, а в type оставляет тип прежним. Имя проверяется, только если передано. Поэтому покупателя с пустым именем можно отредактировать, не передавая name. Удаленного покупателя изменить нельзя. Пример запроса { "customer_id": 512, "phone": "+7 495 765-43-21", "address_real": "г. Москва, ул. Заводская, д. 3" } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No customer_id in input | Не передан customer_id | | Customer 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/customers/delete.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | customer_id | int | Да | ID покупателя | Как работает - Покупатель пропадает из списка покупателей, его файлы удаляются. - Заказы покупателя остаются в истории вместе с покупателем. - Новый заказ на удаленного покупателя создать нельзя: v1/orders/add вернет ошибку «Customer not found». Пример запроса { "customer_id": 512 } Пример ответа { "success": true } Ошибки | Ошибка | Причина | |---|---| | No customer_id in input | Не передан customer_id | | Customer not found or access denied | Покупатель не найден или уже удален |

Список покупателей

Возвращает покупателей компании, отсортированных по имени. Удаленные покупатели в список не входят. v1/customers/get_list.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | limit | int | Нет | Размер страницы, от 1 до 1000 | | offset | int | Нет | Сколько записей пропустить | Без limit возвращается весь список. Подробнее о постраничной выдаче в статье Общие правила. Ответ Массив customers со всеми полями покупателя (см. Покупатели). Поле total содержит общее число покупателей. Пример запроса { "limit": 100, "offset": 0 } Пример ответа { "success": true, "customers": [ { "id": "513", "type": "3", "name": "Анна Смирнова", "email": "anna@example.com", "phone": "+7 916 555-12-34", "address_legal": "", "address_real": "г. Казань, ул. Баумана, д. 20, кв. 7", "inn": "", "kpp": "", "ogrn": "", "agreement": "", "manager_name": "", "manager_post": "", "notes": "" }, { "id": "512", "type": "1", "name": "ООО Мебельный двор", "email": "zakaz@mebdvor.ru", "phone": "+7 495 123-45-67", "address_legal": "г. Москва, ул. Лесная, д. 5", "address_real": "г. Москва, ул. Складская, д. 12", "inn": "7701234567", "kpp": "770101001", "ogrn": "1027700123456", "agreement": "№ 15 от 10.01.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/customers/get_entry.php Параметры | Поле | Тип | Обязательное | Описание | |---|---|---|---| | customer_id | int | Да | ID покупателя | Удаленный покупатель не возвращается. Ответ Объект customer со всеми полями покупателя (см. Покупатели). Поля из ответа можно передать в v1/customers/edit без изменений, добавив customer_id. Пример запроса { "customer_id": 512 } Пример ответа { "success": true, "customer": { "id": "512", "type": "1", "name": "ООО Мебельный двор", "email": "zakaz@mebdvor.ru", "phone": "+7 495 123-45-67", "address_legal": "г. Москва, ул. Лесная, д. 5", "address_real": "г. Москва, ул. Складская, д. 12", "inn": "7701234567", "kpp": "770101001", "ogrn": "1027700123456", "agreement": "№ 15 от 10.01.2026", "manager_name": "Иванов Петр Сергеевич", "manager_post": "Генеральный директор", "notes": "" } } Ошибки | Ошибка | Причина | |---|---| | No customer_id in input | Не передан customer_id | | Customer not found or access denied | Покупатель не найден или удален |