Интеграция с 1С [Документация ACP MikBiLL]

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
====== Интеграция с 1С  ======
<WRAP center round important 40%>
Для начала рекомендую делать интеграцию на тестовом 1с сервере. Это важно.
</WRAP>
<WRAP center round tip 40%>
Все взаимодействие с  АСР MikBiLL построено на POST вызовах и json ответах
</WRAP>
**Интеграция с 1С делается в 3 этапа:**

===== Этап 1.  API Userside =====
==== 1.1.  Выгрузка абонентов ====
Документация по вызову и полное описание всех полей данных по ссылке
https://wiki.userside.eu/API_-_usm_billing_-_get_user_list

краткие выдержки из документации:
<sxh language width classes>
'flag_corporate' => флаг – юридическое лицо
'agreement' => array( - договора с клиентом
   [] => array( - вложенный массив
     'number' => номер
     'date' => дата
   )
 )
</sxh>

Учитывая объем около 100 000 учетных записей , время выгрузки примерно 15 минут.

==== 1.1.1 Выгрузка одного абонента ====
Для тестирования обработки или других нужд будет удобно получить данные только одного абонента, для этого  есть подвызов \\
**Запрос:** \\
<sxh language width classes>
 GET  /api/index/api?key=12345&request=get_user_list&customer_id=7
</sxh>

**Параметры GET:**
customer_id=7 - id абонента

**Ответ:**
<sxh language width classes>
{
  "7": {
    "id": 7,
    "customer_id": 7,
    "state_id": 1,
    "login": "router",
    "password": "12345",
    "full_name": "Тестовый Роутер Павлович",
    "flag_corporate": 0,
    "tariff": {
      "current": [
        {
          "id": 18
        }
      ]
    },
    "agreement": [
      {
        "number": "1121050",
        "date": "2012-08-12"
      }
    ],
    "comment": "10:1F:74:F8:DE:DD\nмаленький бук: \n00:22:15:AE:57:74",
    "balance": "12678.700000",
    "credit": "4059.23",
    "date_create": "2012-08-12",
    "date_connect": "2012-08-12",
    "traffic": {
      "month": {
        "up": 0,
        "down": 0
      }
    },
    "discount": 0,
    "address": [
      {
        "type": "connect",
        "house_id": 4,
        "apartment": {
          "full_name": "1",
          "number": "1"
        },
        "entrance": 0,
        "floor": 0
      }
    ],
    "phone": [
      {
        "number": "2",
        "flag_main": 1
      },
      {
        "number": "+79117446255",
        "flag_main": 0
      },
      {
        "number": "1",
        "flag_main": 0
      }
    ],
    "email": [
      {
        "address": "info@mikbill.ru",
        "flag_main": 1
      }
    ],
    "ip_mac": {
      "167776020": {
        "ip": "",
        "mac": "002215ae57a1",
        "ip_net": "255.255.255.255",
        "local_ip": 167776020
      }
    },
    "additional_data": {
      "1": {
        "id": 1,
        "value": "333"
      },
      "2": {
        "id": 2,
        "value": "выа333"
      },
      "4": {
        "id": 4,
        "value": "0000-00-00"
      }
    },
    "service": {
      "8": [
        {
          "cost": "100",
          "date_add": "2016-05-28",
          "comment": "Устройство id: 88"
        },
        {
          "cost": "30",
          "date_add": "2016-08-17",
          "comment": "Устройство id: 90"
        }
      ],
      "9": [
        {
          "cost": "5.000000",
          "date_add": "",
          "comment": "Реальный IP"
        }
      ]
    }
  }
}

</sxh>



===== Этап 2 Справочники и информация =====


<WRAP center round tip 40%>
Все взаимодействие с  АСР MikBiLL построено на POST вызовах и json ответах. 
Необходимо хранить куки и использовать в дальнейших запросах
</WRAP>
==== 2.1 Авторизация в АСР MikBiLL ====

**Запрос:**
<sxh language width classes>
POST  /json/index/auth
</sxh>
Данные POST: \\
login  - логин \\
password  - пароль \\

**Ответ:**
<sxh language width classes>
{
  "success": true,
  "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.ImZhZTY5ZDg5ZjdmNmE1ZGE2ZTE5M2NkOWE5M2IwOGIwIg.Psz2MUbDVf7Vlz7PDnIhjdz2uF_wxunJJcW5rdAWYQQcSVfFJacvgJoAhmFy_BnifspkEDoDO0xKwDkERYXGRQ",
  "data": {
    "enable": true,
    "ue": "руб",
    "result": 1,
      ………
  }
}
</sxh>

**Описание:**

Необходимо хранить куки и использовать в дальнейших запросах. \\

jwt - токен рекомендуется сохранить для дальнейшего взаимодействия \\
<sxh language width classes>
"data": {
    "enable": true,  - означает что вас авторизовало
</sxh>
 "success": true,   - означает что запрос выполнен успешно - если в любом запросе будет false - это критическая ошибка и парсить ответ дальше безсмысленно \\




==== 2.2. Справочник финансовых категорий ====
=== 2.2.1 Типы начислений ( снятия абонплат с абонента) ===
**Разбивка по группам:**
^Название группы ^Список bughtypeid ^
|все |1,2,7,9,20,21,22,23,25,26,27,28,29,30,32,33,34,35,36,42,46,48,51,64,65,72,74,79,99,104,105,120|
|только интернет |1,2,7,20,21,22,42|
|ТВ и другие доп услуги | 79|
|Оборудование абонента| 64,65,|
|Подключение | 27,30,46|
|Другие сервисы |9,26,29,32,33,34,35,48,48,120|

**Описание справочника bughtypeid:**
^bughtypeid  ^Описание^
|1| Абонентская плата за текущий месяц|
|2 |Абонентская плата за текущий день|
|7| Снятие со счета|
|9| Оплата аренды внешнего IP адреса|
|20| Блокировка интернета в связи с окончанием средств|
|21|Остаточная абонплата за месяц|
|22| Остаточная Абонентская плата за текущий месяц|
|23| Изменение пакета с нового месяца|
|25| Ремонт|
|26| Изменение тарифного пакета|
|27| Подключение|
|29| % за пользование кредитом|
|30| Создание второй учетной записи |
|32| Услуга Real IP|
|33| Активация Акционного тарифа|
|34| Услуга "Турбо"|
|35| Активация услуги Кредит|
|36| Активация услуги Кредит с %|
|42| Отключение по задолженности|
|46| Активация учетки абонента|
|48| Оплата Разморозки|
|51| Абонентская плата заморозки|
|64| Плата за покупку устройства| 
|65| Плата за аренду устройства |
|72| Перевод средств абоненту|
|74| Комиссия за перевод средств абоненту|
|79| Дополнительные услуги - списание с абонента|
|99| Корректировка|
|104| Пеня|
|105| Отмена Безналичного платежа|
|120| Подписка Rentsoft |
==== 2.3 Справочника субпровайдеров ====
**Запрос:**
<sxh language width classes>
POST json/options/usersgroupslist
</sxh>
**Ответ:**
<sxh language width classes>
{
  "success": true,
  "totalCount": 1,
  "data": [
    {
      "usersgroupid": "1",
      "usersgroupname": "Иванов",
      "description": "",
      "archived": "0",
      "share": "10.00",
      "ext_do_liqpay_terminal": "1",
      "ext_easysoft_purpose_vat": "0",
      "ext_liqpay_v3": "1",
      "ext_merchant_id": "12345",
      "ext_merc_sign": "123",
      "ext_merc_sign_other": "123",
      "ext_payberry_legal_code": "1",
      "ext_payberry_login": "1",
      "ext_payberry_numdogovor": "1",
      "ext_payberry_on": "1",
      "ext_payberry_uid": "1",
      "ext_phone_pay": "123",
      "ext_show_company_name": "1",
      "ext_show_company_name_text": "Моя компания"
    }
  ]
}
</sxh>
<WRAP center round help 40%>
Описание: \\
 "usersgroupid": "1" - Идентификатор субпровайдера, этапе [[http://docs.mikbill.pro/doku.php?id=config:1%D1%81#%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5_%D1%84%D0%B8%D0%BD%D0%B0%D0%BD%D1%81%D0%BE%D0%B2%D1%8B%D1%85_%D0%BE%D0%BF%D0%B5%D1%80%D0%B0%D1%86%D0%B8%D0%B8_%D0%B7%D0%B0_%D0%BF%D0%B5%D1%80%D0%B8%D0%BE%D0%B4_%D0%B2%D1%80%D0%B5%D0%BC%D0%B5%D0%BD%D0%B8|3.1]] \\
 "usersgroupname": "Иванов" - Название субпровайдера внутри системы \\

</WRAP>

===== Этап 3 - регулярная выгрузка информации =====


**Запрос:**
<sxh language width classes>
POST  /json/bugh/paymentsreport
</sxh>
**Данные POST:** \\
reportname: paymentsbycategoriesreport \\
from_date: 2014-08-01  - дата начала год-месяц-день \\
to_date: 2014-08-31  - дата окончания год-месяц-день \\
settlementid: -1  -  все населенные пункты \\
sectorid: -1   - все сегменты \\
usersgroupid: 0 - все субпровайдеры \\


**categories_list:** 
<sxh language width classes>
1,2,5,6,7,9,10,15,16,17,18,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,142
</sxh>
<WRAP center round info 40%>
тут из пп [[http://docs.mikbill.pro/doku.php?id=config:1%D1%81#%D1%81%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA_%D1%84%D0%B8%D0%BD%D0%B0%D0%BD%D1%81%D0%BE%D0%B2%D1%8B%D1%85_%D0%BA%D0%B0%D1%82%D0%B5%D0%B3%D0%BE%D1%80%D0%B8%D0%B9|2.2]] данного документа указываются категории, в примере указаны практически все категории , хотя вы можете выбирать какие вам нужно выгружать.
</WRAP>


**например:**
categories_list: 79  - выдаст список всех списаний Абонплаты за доп услуги 


**Ответ:**
<sxh language width classes>
{
  "success": true,
  "data": [
    {
      "date": "2020-02-17 20:19:55",
      "before_billing": "12728.7",
      "summa": "50",
      "comment": "HD Кино",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406328",
      "user": "router",
      "fio": "Тестовый Роутер Павлович",
      "phone": "+79117446255",
      "speed_rate": "5000",
      "speed_burst": "5000",
      "mob_tel": "2",
      "sms_tel": "1",
      "gid": "18",
      "sectorid": "37",
      "login": "System",
      "useruid": "7",
      "address": "Переяславка, Октябрьская 92/1"
    },
    {
      "date": "2020-02-18 18:59:55",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406330",
      "user": "0000018134",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "28",
      "login": "System",
      "useruid": "18134",
      "address": "Переяславка, пер. Ульянова 60"
    },
    {
      "date": "2020-02-18 19:07:51",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406332",
      "user": "0000018135",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "32",
      "login": "System",
      "useruid": "18135",
      "address": "Переяславка, пер. Ульянова 60"
    },
    {
      "date": "2020-02-18 19:10:30",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406334",
      "user": "0000018136",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "28",
      "login": "System",
      "useruid": "18136",
      "address": "Могилевка, Тестовая улица 3 55"
    },
    {
      "date": "2020-02-18 19:37:43",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406336",
      "user": "0000018137",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "28",
      "login": "System",
      "useruid": "18137",
      "address": "Могилевка, тестовая улица 4 555"
    }
  ],
  "error": 0
}
</sxh>
==== 3.1 Получение финансовых операции за период времени ====
**Запрос:**
<sxh language width classes>
POST  /json/bugh/paymentsreport
</sxh>
**Данные POST:**
<sxh language width classes>
reportname: paymentsbycategoriesreport
from_date: 2014-08-01  - дата начала год-месяц-день
to_date: 2014-08-31  - дата окончания год-месяц-день
settlementid: -1  -  все населенные пункты
sectorid: -1   - все сегменты 
usersgroupid: 0 - все субпровайдеры
</sxh>
**categories_list:** 
<sxh language width classes>
1,2,5,6,7,9,10,15,16,17,18,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,142
</sxh>

<WRAP center round tip 40%>
тут из пп [[http://docs.mikbill.pro/doku.php?id=config:1%D1%81#%D1%81%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA_%D1%84%D0%B8%D0%BD%D0%B0%D0%BD%D1%81%D0%BE%D0%B2%D1%8B%D1%85_%D0%BA%D0%B0%D1%82%D0%B5%D0%B3%D0%BE%D1%80%D0%B8%D0%B9|2.2]] данного документа указываются категории, в примере указаны практически все категории , хотя вы можете выбирать какие вам нужно выгружать.
например
categories_list: 79  - выдаст список всех списаний Абонплаты за доп услуги 
</WRAP>


**Ответ:**
<sxh language width classes>
{
  "success": true,
  "data": [
    {
      "date": "2020-02-17 20:19:55",
      "before_billing": "12728.7",
      "summa": "50",
      "comment": "HD Кино",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406328",
      "user": "router",
      "fio": "Тестовый Роутер Павлович",
      "phone": "+79117446255",
      "speed_rate": "5000",
      "speed_burst": "5000",
      "mob_tel": "2",
      "sms_tel": "1",
      "gid": "18",
      "sectorid": "37",
      "login": "System",
      "useruid": "7",
      "address": "Переяславка, Октябрьская 92/1"
    },
    {
      "date": "2020-02-18 18:59:55",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406330",
      "user": "0000018134",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "28",
      "login": "System",
      "useruid": "18134",
      "address": "Переяславка, пер. Ульянова 60"
    },
    {
      "date": "2020-02-18 19:07:51",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406332",
      "user": "0000018135",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "32",
      "login": "System",
      "useruid": "18135",
      "address": "Переяславка, пер. Ульянова 60"
    },
    {
      "date": "2020-02-18 19:10:30",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406334",
      "user": "0000018136",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "28",
      "login": "System",
      "useruid": "18136",
      "address": "Могилевка, Тестовая улица 3 55"
    },
    {
      "date": "2020-02-18 19:37:43",
      "before_billing": "-758.62",
      "summa": "0",
      "comment": "test22",
      "typename": "Дополнительные услуги - списание с абонента",
      "stuffid": "",
      "bughtypeid": "79",
      "plategid": "406336",
      "user": "0000018137",
      "fio": "",
      "phone": "",
      "speed_rate": "0",
      "speed_burst": "0",
      "mob_tel": "",
      "sms_tel": "",
      "gid": "3",
      "sectorid": "28",
      "login": "System",
      "useruid": "18137",
      "address": "Могилевка, тестовая улица 4 555"
    }
  ],
  "error": 0
}
</sxh>
==== 3.2. Получение истории платежей по абоненту ====

**Запрос:**
<sxh language width classes>
POST  json/users/statpaymfl
</sxh>
**Данные POST:** \\
from_date: 2014-08-01  - дата начала год-месяц-день \\
to_date: 2014-08-31  - дата окончания год-месяц-день \\
uid: 7 - UID идентификатор абонента \\

**Ответ:**
<sxh language width classes>
{
  "success": true,
  "totalCount": 4,
  "data": [
    {
      "IdRowPayView": "4",
      "date": "2020-01-10 23:58:04",
      "bughtypeid": "Абонентская плата за текущий день",
      "who": "System",
      "before_billing": "-459.17",
      "summa": "8.06",
      "comment": ""
    },
    {
      "IdRowPayView": "3",
      "date": "2020-01-10 23:58:05",
      "bughtypeid": "Дополнительные услуги - списание с абонента",
      "who": "System",
      "before_billing": "-467.24",
      "summa": "3.84",
      "comment": "VIP HD"
    },
    {
      "IdRowPayView": "2",
      "date": "2020-01-11 23:58:03",
      "bughtypeid": "Абонентская плата за текущий день",
      "who": "System",
      "before_billing": "-471.08",
      "summa": "8.06",
      "comment": ""
    },
    {
      "IdRowPayView": "1",
      "date": "2020-01-11 23:58:04",
      "bughtypeid": "Дополнительные услуги - списание с абонента",
      "who": "System",
      "before_billing": "-479.14",
      "summa": "3.84",
      "comment": "VIP HD"
    }
  ]
}
</sxh>
<WRAP center round tip 40%>
bughtypeid - справочник описан в этапе [[http://docs.mikbill.pro/doku.php?id=config:1%D1%81#%D1%81%D0%BF%D1%80%D0%B0%D0%B2%D0%BE%D1%87%D0%BD%D0%B8%D0%BA_%D1%84%D0%B8%D0%BD%D0%B0%D0%BD%D1%81%D0%BE%D0%B2%D1%8B%D1%85_%D0%BA%D0%B0%D1%82%D0%B5%D0%B3%D0%BE%D1%80%D0%B8%D0%B9|2.2]]
</WRAP>