Описание API системы ClientoBox

Вы можете интегрировать свой сервис непосредственно с нашей системой, воспользовавшись предлагаемым описанием.

Подключение к API

Для работы с API в вашем аккаунте не надо предпринимать никаких действий: все, что вам нужно — уже настроено, вам необходимо только получить ключ доступа со страницы настроек в разделе «Интеграция».

Запросы к API системы ClientoBox (далее «API») необходимо отправлять методом POST на адрес вида https://app.clientobox.ru/api/<element>/<method>. Обратите внимание, что, хотя вы можете отправлять эти же запросы по протоколу http://, мы не рекомендуем так делать в целях безопасности ваших данных.

На этот адрес методом POST должны отправляться все параметры, которые требует метод, плюс внутри запроса должен отправляться POST-параметр с именем api_key и значением, соответствующим значению вашего API-ключа.

Ответ будет возвращен в формате JSON или в строковом формате (если возвращается не массив, а только одно значение).

Обратите внимание, что API позволяет выполнять только те запросы, которые ограничены вашим доступом. Так, если вы по выставленным администратором правам доступа не можете смотреть задачи других пользователей в менеджере задач, вам будет недоступна фильтрация задач по пользователям.

В случае, если возникает ошибка, возвращается JSON-объект с именем error и значением - описание возникшей ошибки на русском языке.

Подробное описание элементов API

Звездочкой (*) выделены обязательные входные параметры.

Элемент action [задачи]

add - Метод создает задачу с указанными параметрами

Входные параметры:
action_date *
дата, когда необходимо выполнить задачу (в формате ГГГГ-ММ-ДД)
name *
название (заголовок) задачи
owner *
идентификатор пользователя, назначаемого ответственным по данной задаче
action_time *
время, в которое нужно выполнить задачу (в формате ЧЧ:ММ)
deal_id
идентификатор сделки, привязанной к задаче
contact_id
идентификатор контакта, привязанного к задаче
org_id
идентификатор организации, привязанной к задаче
description
подробное описание задачи в текстовом виде
performed
отметить задачу как выполненную (1 - задача выполнена, 0 - задача не выполнена). По умолчанию вновь созданная задача не является выполненной.
action_type
тип задачи (числовое значение, см. метод types)

count - Метод возвращает количество открытых (невыполненных) личных задач

Входные параметры:
нет

delete - Метод удаляет указанную задачу

Входные параметры:
id *
идентификатор указанной задачи

edit - Метод изменяет задачу с указанным идентификатором

Входные параметры:
action_id *
идентификатор редактируемой задачи action_date * дата, когда необходимо выполнить задачу (в формате ГГГГ-ММ-ДД)
name *
название (заголовок) задачи
action_type *
тип задачи (числовое значение, см. метод types)
action_time
время, в которое нужно выполнить задачу (в формате ЧЧ:ММ)
deal_id
идентификатор сделки, привязанной к задаче
contact_id
идентификатор контакта, привязанного к задаче org_id идентификатор организации, привязанной к задаче
description
подробное описание задачи в текстовом виде owner идентификатор пользователя, назначаемого ответственным по данной задаче performed отметить задачу как выполненную (1 - задача выполнена, 0 - задача не выполнена). По умолчанию вновь созданная задача не является выполненной.

info - Метод возвращает подробное описание задачи с указанным идентификатором

Входные параметры:
id *
идентификатор задачи

list - Метод возвращает список задач, удовлетворяющих набору входных параметров

Входные параметры:
user
ID пользователя, для которого возвращаются списки дел
date
интервал дат, для которых возвращается список дел (допустимые значения: today, tomorrow, next_week, this_week)
type
тип задач (допустимые значения: all, performed, not_performed)
deal
ID сделки, к которой относятся задачи
organization
ID организации, с которой связана задача
contact
ID контакта, с которым связана задача

my - Метод возвращает список открытых (невыполненных) личных задач

Входные параметры:
нет

perform - Метод изменяет статус “выполнено” для указанной задачи

Входные параметры:
id *
идентификатор задачи
value *
значение параметра “Задача выполнена”: 0 - задача не выполнена, 1 - задача выполнена.

types - Метод возвращает список допустимых типов для задач

Входные параметры:
нет

Элемент channel [воронки]

Обратите внимание, что у воронок используется несколько идентификационных параметров: id (идентификатор) и number (номер). В разных методах могут использоваться разные параметры - смотрите подробное описание входных параметров соответствующих методов.

add - Метод добавляет новую воронку с указанным именем

Входные параметры:
name *
название новой воронки

delete - Метод удаляет указанную воронку

Входные параметры:
id *
идентификатор воронки

edit - Метод редактирует указанную воронку

Входные параметры:
id *
идентификатор воронки
name *
название новой воронки

info - Метод возвращает информацию по указанной воронке

Входные параметры:
id *
идентификатор воронки

list - Метод возвращает список воронок

Входные параметры:
selected
номер воронки, который требуется отметить выбранным (у него добавляется параметр selected)
stages
требуется ли добавить список этапов к воронкам (0 - нет, 1 - да)

Элемент comments [текстовые комментарии]

add - Метод добавляет комментарий к элементу

Входные параметры:
type *
к какому типу элементов относится комментарий (см. метод type)
number *
идентификатор элемента (сделки, организации, контакта или товара), к которому относится комментарий
comment *
текст комментария

delete - Метод удаляет комментарий к элементу

Входные параметры:
type *
к какому типу элементов относится комментарий (см. метод type)
id *
идентификатор комментария

list - Метод возвращает список комментариев к элементу

Входные параметры:
type *
к какому типу элементов относится комментарий (см. метод type)
number *
идентификатор элемента (сделки, организации, контакта или товара), для которого хотим получить список комментариев

type - Метод возвращает список допустимых типов комментариев

Входные параметры:
нет

Элемент contact [контакты]

add - Метод добавляет контакт

Обратите внимание, что при добавлении контакта в организацию может использоваться или параметр org, или параметр org_id, но не оба вместе. Если заполнены оба поля - параметр org_id имеет приоритет.

Входные параметры:
name *
имя контакта owner * идентификатор пользователя, ответственного по данному контакту email адрес электронной почты контакта phone телефон контакта org_id идентификатор организации, к которой относится контакт org название организации, к которой относится контакт
skype
номер skype
social
адрес контакта в соц. сети

delete - Метод отметить контакт удаленным

Входные параметры:
id *
идентификатор контакта

edit - Метод редактирует контакт

Обратите внимание, что при добавлении контакта в организацию может использоваться или параметр org, или параметр org_id, но не оба вместе. Если заполнены оба поля - параметр org_id имеет приоритет.

Входные параметры:
id *
идентификатор редактируемого контакта
name *
имя контакта
owner *
идентификатор пользователя, ответственного по данному контакту
email
адрес электронной почты контакта
phone
телефон контакта
org_id
идентификатор организации, к которой относится контакт
org
название организации, к которой относится контакт
skype
номер skype
social
адрес контакта в соц. сети

info - Метод возвращает информацию по указанному контакту

Входные параметры:
id *
идентификатор контакта

list - Метод возвращает список контактов, удовлетворяющих набору входных параметров

Входные параметры:
org
идентификатор организации, к которой принадлежит контакт
deleted
допустимо только значение ‘false’ - в этом случае будут возвращены только организации, которые не были удалены (по умолчанию возвращаются все организации)
owner
ответственный за данный контакт
limit
ограничить выдачу указанным количеством записей
offset
вернутьсписок контактов, начиная с указанного

restore - Метод отметить контакт неудаленным

Входные параметры:
id *
идентификатор контакта

Элемент currency [валюты]

list - Метод возвращает список доступных валют

Входные параметры:
нет

Элемент deal [сделки]

add - Метод добавляет сделку

Обратите внимание, что при связывании сделки с организацией может использоваться или параметр org, или параметр org_id, но не оба вместе. Если заполнены оба поля - параметр org_id имеет приоритет. Аналогично для связывания сделки с контактом. Если указанный контакт или организация не найдены, создается новый контакт/организация с указанным именем.

Входные параметры:
name *
название сделки
owner *
идентификатор пользователя, ответственного за данную сделку
stage *
идентификатор этапа, на котором размещена сделка
org_id
идентификатор организации, связанной со сделкой
org
название организации, связанной со сделкой
contact_id
идентификатор контакта, связанного со сделкой
contact
имя контакта, связанного со сделкой
status
статус сделки (см. метод status)
price_currency
идентификатор валюты сделки (см. элемент currency)

comment_add - Метод добавляет текстовый комментарий к сделке

Входные параметры:
id *
идентификатор сделки
comment *
текст комментария

comments - Метод возвращает список событий, связанных со сделкой

Входные параметры:
id *
идентификатор сделки

delete - Метод отметить сделку удаленной

Входные параметры:
id *
идентификатор сделки

edit - Метод редактирует сделку

Обратите внимание, что при связывании сделки с организацией может использоваться или параметр org, или параметр org_id, но не оба вместе. Если заполнены оба поля - параметр org_id имеет приоритет. Аналогично для связывания сделки с контактом. Если указанный контакт или организация не найдены, создается новый контакт/организация с указанным именем.

Входные параметры:
id *
идентификатор сделки
name *
название сделки
owner *
идентификатор пользователя, ответственного за данную сделку
stage *
идентификатор этапа, на котором размещена сделка
org_id
идентификатор организации, связанной со сделкой
org
название организации, связанной со сделкой
contact_id
идентификатор контакта, связанного со сделкой
contact
имя контакта, связанного со сделкой
status
статус сделки (см. метод status)
price_currency
идентификатор валюты сделки (см. элемент currency)

fail - Метод отмечает сделку как проигранную

Входные параметры:
id *
идентификатор сделки

info - Метод возвращает информацию по указанной сделке

Входные параметры:
id *
идентификатор сделки

list - Метод возвращает список сделок, удовлетворяющих набору входных параметров

Входные параметры:
pipeline
идентификатор воронки, в которой находятся сделки
status
возвращать только сделки с указанным статусом (см. метод status)
deleted
допустимо только значение ‘false’ - в этом случае будут возвращены только организации, которые не были удалены (по умолчанию возвращаются все организации)
tasks
возвращать только сделки с задачами в указанном статусе. Допустимые значения: with - сделки с задачами, without - сделки без задач, lost - сделки с просроченными задачами
channel
сделки, находящиеся на определенном этапе
owner
идентификатор пользователя, ответственного за сделку
org
идентификатор организации, с которой связана сделка
contact
идентификатор контакта, с которым связана сделка
limit
ограничить выдачу указанным количеством записей
offset
вернутьсписок контактов, начиная с указанного

restore - Метод отметить сделку неудаленной

Входные параметры:
id *
идентификатор сделки

set_stage - Метод перемещает сделку на указанный этап

Входные параметры:
deal *
идентификатор сделки
stage *
идентификатор этапа

status - Метод возвращает список допустимых статусов для сделки

Входные параметры:
нет

won - Метод отмечает сделку как выигранную

Входные параметры:
id *
идентификатор сделки

Элемент org [организации]

add - Метод добавляет организацию

Входные параметры:
name *
название организации
owner *
идентификатор пользователя, ответственного по данной организации
city
город, в котором расположена организация
legal_address
юридический адрес
fact_address
фактический адрес
inn
ИНН организации
kpp
КПП организации
phone
номер телефона организации
email
контактный email организации
site
сайт организации

delete - Метод отметить организацию удаленной

Входные параметры:
id *
идентификатор организации

edit - Метод редактирование организации

Входные параметры:
id *
идентификатор редактируемой организации
name *
название организации
owner *
идентификатор пользователя, ответственного по данной организации
city
город, в котором расположена организация
legal_address
юридический адрес
fact_address
фактический адрес
inn
ИНН организации
kpp
КПП организации
phone
номер телефона организации
email
контактный email организации
site
сайт организации

info - Метод возвращает информацию по указанной организации

Входные параметры:
id *
идентификатор организации

list - Метод возвращает список организаций, удовлетворяющих набору входных параметров

Входные параметры:
deleted
допустимые значение ‘true’ или 1 - в этом случае будут возвращены только организации, которые были удалены
owner
идентификатор ответственного за данную организацию
limit
ограничить выдачу указанным количеством записей
offset
вернутьсписок контактов, начиная с указанного

restore - Метод отметить организацию неудаленной

Входные параметры:
id *
идентификатор организации

Элемент product [товары/услуги]

add - Метод добавляет товар/услугу

Входные параметры:
name *
название товара/услуги
nds
НДС для данного товара/услуги
code
код (шифр, артикул) товара/услуги

delete - Метод удаление товара/услуги

Входные параметры:
id *
идентификатор товара/услуги

edit - Метод редактирует товар/услугу

Входные параметры:
id *
идентификатор товара/услуги
name *
название товара/услуги
nds
НДС для данного товара/услуги
code
код (шифр, артикул) товара/услуги

info - Метод возвращает информацию по указанному товару/услуге

Входные параметры:
id *
идентификатор товара/услуги

list - Метод возвращает список всех товаров/услуг

Входные параметры: нет

restore - Метод восстановление товара/услуги

Входные параметры:
id *
идентификатор товара/услуги

Элемент stage [этапы]

add - Метод добавляет этап в воронку

Входные параметры:
channel *
идентификатор воронки, в которой нужно создать этап
name *
название этапа
probability *
вероятность выигрыша на данном этапе (в процентах)

delete - Метод удаляет указанный этап (удалить можно только этап, на котором нет сделок)

Входные параметры:
id *
идентификатор этапа

edit - Метод редактирует название указанного этапа

Входные параметры:
id *
идентификатор этапа
name *
новое название этапа

list - Метод возвращает список этапов в соответствии с указанными входными параметрами

Входные параметры:
channel
идентификатор воронки, к которой относятся этапы

Элемент statistic [список событий]

contact - Метод возвращает список событий для контакта

Входные параметры:
id *
идентификатор контакта
limit
количество последних возвращаемых элементов

deal - Метод возвращает список событий для сделки

Входные параметры:
id *
идентификатор сделки
limit
количество последних возвращаемых элементов

org - Метод возвращает список событий для организации

Входные параметры:
id *
идентификатор организации
limit
количество последних возвращаемых элементов

product - Метод возвращает список событий для товара

Входные параметры:
id *
идентификатор товара
limit
количество последних возвращаемых элементов

Элемент user [пользователи]

Выполнение всех методов элемента user, за исключением list и info, доступно только администраторам аккаунта

add - Метод добавляет в аккаунт нового пользователя

Входные параметры:
name *
имя пользователя
email *
адрес электронной почты пользователя
phone
номер телефона пользователя
private_statistics
приватность страницы статистики (допустимое значение - ‘all’: показывать всю статистику аккаунта, любое другое значение - скрывать общую статистику аккаунта (отображать только личную))
private_tasks
отображение задач других пользователей в панели задач (допустимые значения: ‘none’, ‘all_tasks’)

edit - Метод редактирует пользователя аккаунта

Входные параметры:
id *
идентификатор пользователя
name *
имя пользователя
email *
адрес электронной почты пользователя
phone
номер телефона пользователя
private_statistics
приватность страницы статистики (допустимое значение - ‘all’: показывать всю статистику аккаунта, любое другое значение - скрывать общую статистику аккаунта (отображать только личную))
private_tasks
отображение задач других пользователей в панели задач (допустимые значения: ‘none’, ‘all_tasks’)
is_admin
является ли пользователь администратором (пустое значение или 0 - нет, 1 - да)

info - Метод возвращает информацию по указанному пользователю

Входные параметры:
id *
идентификатор пользователя

list - Метод возвращает список пользователей аккаунта

Входные параметры:
нет

merge - Метод переносит задачи/сделки/организации/контакты от пользователя 1 к пользователю 2 и удаляет пользователя 1 из аккаунта

Входные параметры:
user *
идентификатор пользователя, к которому переносятся сделки, задачи, организации, контакты (этот пользователь сохранится в аккаунте)
loser *
идентификатор пользователя, от которого переносятся сделки, задачи, организации, контакты (этот пользователь будет удален)