{warning}Эта версия API больше не поддерживается. Пожалуйста, используйте [CarbonBilling:API REST v2.0]{warning}
h2. Отличия API REST v1 и v2
* Новый адрес для запросов: http://<ip>:8082/rest_api/v2/
* Вместо передачи параметров в GET, перешли на POST
* Убрали из вывода результаты промежуточных вызовов (method1, method2,..), оставили только result
* Соответственно, немного поменялся схема вывода (см. соответствующий раздел)
* Модель указывается в url напрямую, например: http://<ip>:8082/rest_api/v2/Abonents/
* Атрибут запроса fields теперь не нужно маркировать номером метода. Он будет применяться к последнему объекту (возвращенному последним методом)
* Документацию (пока что только перечень доступных полей для запроса) можно посмотреть, пройдя браузером по ссылке http://<ip>:8082/rest_api/v2/
* Теперь можно в fields запрашивать вывод объектов по ссылкам (fk, m2m), обратным ссылкам и выводить property объектов, а также выводить конкретные поля этих объектов. Глубина запроса не ограничена, разделитель - двойное подчеркивание. \*Внимание\! Django не объединяет запрос по обратной ссылке в один, поэтому он может выполняться заметно дольше для большого кол-ва объектов (например, если запросить все учетные записи у всех абонентов - будет 1 запрос для абонентов и по запросу на каждого абонента для получения его учетных записей)
h2. Описание API REST v1
Api работает через порт 8082.
!апи2.JPG|border=1!
В api можно получить подробные сведения о каждой модели веб-интерфейса администратора Carbon Billing 5.
* поля модели;
* методы модели;
* методы объекта.
!апи3.JPG|border=1!
Создадим тариф с помощью api. Обязательно указываем аргумент, даже если он пустой.
!апи4.JPG|border=1!
Возвращается XML документ с подробными описаниями для нового объекта.
!апи5.JPG|border=1!
Можно задать сразу имя тарифа:
!апи6.JPG|border=1!
В файле можно увидеть, что тариф создался с именем:
!апи7.JPG|border=1!
Также мы можем получить файл не в XML виде, а в json, для этого пишем в командной строке:
!апи8.JPG|border=1!
После создания или изменения объекта, его нужно сохранить:
!апи9.JPG|border=1!
Логика биллинга отработает и вернет значения, которые после сохранения выставились в тарифе.
Теперь этот тариф можно увидеть в веб-интерфейсе администратора Carbon Billing 5.
!апи10.JPG|border=1!
Чтобы авторизоваться для работы в api, необходимо зайти в веб-интерфейс администратора Carbon Billing 5, раздел *Настройки/Настройки (в файле)/Настройка Сети*.
!апи11.JPG|border=1!
Также нужно указать hash_key, который обычно известен при авторизации.
!апи12.JPG|border=1!
Тогда все запросы будут считаться авторизованными.
!апи13.JPG|border=1!
{color:#000000}{*}Задача: Требуется создавать абонентов с реквизитами.*{color}
1.Необходимо узнать имена моделей для составления к ним запросов, для этого заходим в администраторскую панель и нажимаем на соответствующие пункты, чтобы в строке url браузера увидеть название модели.
!Выделение_059.jpeg|border=1!
Некоторые модели можно узнать только через настройку прав доступа.
!Выделение_062.jpeg|border=1!
2.Также необходимо узнать ид реквизитов который хотим добавлять абоненту.
!Выделение_063.jpeg|border=1!
Например мы хотим добавить прописку: 15
3.Создадим группу или используем существующую для новых абонентов и узнаем ее номер для запросов:
!Выделение_064.jpeg|border=1!
Например 90
4.Итак узнав имена моделей (Abonents и AttributeValues), для создания запросов необходимо узнать имена полей который мы хотим заполнять, для этого делаем запросы
{code}
http://195.64.222.86:8082/rest_api/?model=Abonents
{code}
и
{code}
http://195.64.222.86:8082/rest_api/?model=AttributeValues
{code}
соответственно.
5.Имея всю необходимую информацию по абонентам и их реквизитам сначала создаем запрос на создание абонента:
{code}
http://195.64.222.86:8082/rest_api/?model=Abonents&method1=new&arg1={"name":"Тест","parent_id":90}&method2=save&arg2={}&format=json
{code}
, в ответ мы получим json массив откуда узнаем pk созданного абонента и по нему формируем запрос на создание реквизитов указывая его каждый раз как abonent_id:
{code}
http://195.64.222.86:8082/rest_api/?model=AttributeValues&method1=new&arg1={"abonent_id":pk,"attribute_id":15,"attribute_value":"Россия"}&method2=save&arg2={}&format=json
{code}
6.Мы успешно создали абонента с именем Тест в группе VIP с реквизитом Прописка:Россия
h2. Синтаксис. Диапазон параметров
Если требуется передать диапазон параметров, например при запросе данных, то синтаксис будет такой:
{code}
'id__in":[1,2,3]
{code}
Вообще доступен весь синтаксис [django|https://docs.djangoproject.com/en/1.5/topics/db/queries/]
h2. Авторизация через API
С примером класса авторизации через php можете ознакомиться здесь: [https://github.com/carbonsoft/billing_api_tools]
h2. Примеры
*Пример 1. Внести абоненту с номером договора SL0000001 на счет 500 рублей.*
{code}
http://<ip_сервера>:8082/rest_api/?model=Abonents&method1=objects.get&arg1={"contract_number":"SL0000001"}&method2=add_payment&arg2={"SUM_IN":500}
{code}
*Пример 2. Получить все данные абонента с номером договора BILL0000029.*
{code}
http://<ip_сервера>:8082/rest_api/?model=Abonents&method1=objects.get&arg1={"contract_number":"BILL0000029"}&format=json
{code}
Ищем строку
{code}
"account": 10002143
{code}
И берем цифровое значение
Далее вставляем его в запрос:
{code}
http://<ip_сервера>:8082/rest_api/?model=AdminAccounts&method1=objects.get&arg1={"id":"10002143"}&format=json
{code}
После этого операция *debit-credit+ostatok* даст баланс абонента
*Пример 3. Получить данные по отчету номер 15 из конструктора отчетов.*
{code}
http://<ip_сервера>:8082/rest_api/?model=AdminCustomReports&method1=objects.get&arg1={"pk":"15"}&method2=get_data&arg2={}
{code}
*Пример 4. Получить данные по отчету номер 15 из конструктора отчетов. если в отчет нужно передать параметры.*
Например при запуске отчета выводится 2 поля для заполнения, которые называются "C_даты" и "По_дату"
{code}
http://<ip_сервера>:8082/rest_api/?
model=AdminCustomReports&method1=objects.get&arg1={"pk":"<номер_отчета_в_конструкторе_отчетов>"}&method2=get_data&arg2={"C_даты":"05.12.2014","По_дату":"10.12.2014"}
{code}{*}Пример 5. Получить список учетных записей заблокированных абонентов*
{code}
{code}
{code}
http://<ip_сервера>:8082/rest_api/?
model=Users&method1=objects.extra&arg1={ "where": ["users.abonent_id in (select abonent_id from abonents_block)"] }
{code}
{code}
{code}
h2. Отличия API REST v1 и v2
* Новый адрес для запросов: http://<ip>:8082/rest_api/v2/
* Вместо передачи параметров в GET, перешли на POST
* Убрали из вывода результаты промежуточных вызовов (method1, method2,..), оставили только result
* Соответственно, немного поменялся схема вывода (см. соответствующий раздел)
* Модель указывается в url напрямую, например: http://<ip>:8082/rest_api/v2/Abonents/
* Атрибут запроса fields теперь не нужно маркировать номером метода. Он будет применяться к последнему объекту (возвращенному последним методом)
* Документацию (пока что только перечень доступных полей для запроса) можно посмотреть, пройдя браузером по ссылке http://<ip>:8082/rest_api/v2/
* Теперь можно в fields запрашивать вывод объектов по ссылкам (fk, m2m), обратным ссылкам и выводить property объектов, а также выводить конкретные поля этих объектов. Глубина запроса не ограничена, разделитель - двойное подчеркивание. \*Внимание\! Django не объединяет запрос по обратной ссылке в один, поэтому он может выполняться заметно дольше для большого кол-ва объектов (например, если запросить все учетные записи у всех абонентов - будет 1 запрос для абонентов и по запросу на каждого абонента для получения его учетных записей)
h2. Описание API REST v1
Api работает через порт 8082.
!апи2.JPG|border=1!
В api можно получить подробные сведения о каждой модели веб-интерфейса администратора Carbon Billing 5.
* поля модели;
* методы модели;
* методы объекта.
!апи3.JPG|border=1!
Создадим тариф с помощью api. Обязательно указываем аргумент, даже если он пустой.
!апи4.JPG|border=1!
Возвращается XML документ с подробными описаниями для нового объекта.
!апи5.JPG|border=1!
Можно задать сразу имя тарифа:
!апи6.JPG|border=1!
В файле можно увидеть, что тариф создался с именем:
!апи7.JPG|border=1!
Также мы можем получить файл не в XML виде, а в json, для этого пишем в командной строке:
!апи8.JPG|border=1!
После создания или изменения объекта, его нужно сохранить:
!апи9.JPG|border=1!
Логика биллинга отработает и вернет значения, которые после сохранения выставились в тарифе.
Теперь этот тариф можно увидеть в веб-интерфейсе администратора Carbon Billing 5.
!апи10.JPG|border=1!
Чтобы авторизоваться для работы в api, необходимо зайти в веб-интерфейс администратора Carbon Billing 5, раздел *Настройки/Настройки (в файле)/Настройка Сети*.
!апи11.JPG|border=1!
Также нужно указать hash_key, который обычно известен при авторизации.
!апи12.JPG|border=1!
Тогда все запросы будут считаться авторизованными.
!апи13.JPG|border=1!
{color:#000000}{*}Задача: Требуется создавать абонентов с реквизитами.*{color}
1.Необходимо узнать имена моделей для составления к ним запросов, для этого заходим в администраторскую панель и нажимаем на соответствующие пункты, чтобы в строке url браузера увидеть название модели.
!Выделение_059.jpeg|border=1!
Некоторые модели можно узнать только через настройку прав доступа.
!Выделение_062.jpeg|border=1!
2.Также необходимо узнать ид реквизитов который хотим добавлять абоненту.
!Выделение_063.jpeg|border=1!
Например мы хотим добавить прописку: 15
3.Создадим группу или используем существующую для новых абонентов и узнаем ее номер для запросов:
!Выделение_064.jpeg|border=1!
Например 90
4.Итак узнав имена моделей (Abonents и AttributeValues), для создания запросов необходимо узнать имена полей который мы хотим заполнять, для этого делаем запросы
{code}
http://195.64.222.86:8082/rest_api/?model=Abonents
{code}
и
{code}
http://195.64.222.86:8082/rest_api/?model=AttributeValues
{code}
соответственно.
5.Имея всю необходимую информацию по абонентам и их реквизитам сначала создаем запрос на создание абонента:
{code}
http://195.64.222.86:8082/rest_api/?model=Abonents&method1=new&arg1={"name":"Тест","parent_id":90}&method2=save&arg2={}&format=json
{code}
, в ответ мы получим json массив откуда узнаем pk созданного абонента и по нему формируем запрос на создание реквизитов указывая его каждый раз как abonent_id:
{code}
http://195.64.222.86:8082/rest_api/?model=AttributeValues&method1=new&arg1={"abonent_id":pk,"attribute_id":15,"attribute_value":"Россия"}&method2=save&arg2={}&format=json
{code}
6.Мы успешно создали абонента с именем Тест в группе VIP с реквизитом Прописка:Россия
h2. Синтаксис. Диапазон параметров
Если требуется передать диапазон параметров, например при запросе данных, то синтаксис будет такой:
{code}
'id__in":[1,2,3]
{code}
Вообще доступен весь синтаксис [django|https://docs.djangoproject.com/en/1.5/topics/db/queries/]
h2. Авторизация через API
С примером класса авторизации через php можете ознакомиться здесь: [https://github.com/carbonsoft/billing_api_tools]
h2. Примеры
*Пример 1. Внести абоненту с номером договора SL0000001 на счет 500 рублей.*
{code}
http://<ip_сервера>:8082/rest_api/?model=Abonents&method1=objects.get&arg1={"contract_number":"SL0000001"}&method2=add_payment&arg2={"SUM_IN":500}
{code}
*Пример 2. Получить все данные абонента с номером договора BILL0000029.*
{code}
http://<ip_сервера>:8082/rest_api/?model=Abonents&method1=objects.get&arg1={"contract_number":"BILL0000029"}&format=json
{code}
Ищем строку
{code}
"account": 10002143
{code}
И берем цифровое значение
Далее вставляем его в запрос:
{code}
http://<ip_сервера>:8082/rest_api/?model=AdminAccounts&method1=objects.get&arg1={"id":"10002143"}&format=json
{code}
После этого операция *debit-credit+ostatok* даст баланс абонента
*Пример 3. Получить данные по отчету номер 15 из конструктора отчетов.*
{code}
http://<ip_сервера>:8082/rest_api/?model=AdminCustomReports&method1=objects.get&arg1={"pk":"15"}&method2=get_data&arg2={}
{code}
*Пример 4. Получить данные по отчету номер 15 из конструктора отчетов. если в отчет нужно передать параметры.*
Например при запуске отчета выводится 2 поля для заполнения, которые называются "C_даты" и "По_дату"
{code}
http://<ip_сервера>:8082/rest_api/?
model=AdminCustomReports&method1=objects.get&arg1={"pk":"<номер_отчета_в_конструкторе_отчетов>"}&method2=get_data&arg2={"C_даты":"05.12.2014","По_дату":"10.12.2014"}
{code}{*}Пример 5. Получить список учетных записей заблокированных абонентов*
{code}
{code}
{code}
http://<ip_сервера>:8082/rest_api/?
model=Users&method1=objects.extra&arg1={ "where": ["users.abonent_id in (select abonent_id from abonents_block)"] }
{code}
{code}
{code}