API LBX: быстрый старт

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

В этом руководстве рассмотрим аутентификацию для использования API и минимальный сценарий подключения подписки для нового клиента, а также изменение подписки.

Общие принципы

Для работы с подписками LBX необходимо представлять, как между собой связаны основные сущности системы:

  • Клиент — физическое лицо или организация, которая пользуется услугами. Основные данные о клиенте: имя/название, контактные данные и реквизиты (ИНН, номер расчётного счёта и др).
  • Договор принадлежит клиенту. В LBX договор содержит информацию о балансе и движении денежных средств клиента (платежи и списания за услуги). Подписки хранятся на договорах клиентов.
  • Тариф содержит:
    • основные условия для расчёта списаний (с какой частотой списывать средства, в начале или в конце периода и др.)
    • все возможные услуги, которые клиент может приобрести в рамках этого тарифа.
  • Подписка — это конкретный набор услуг, которыми пользуется ваш клиент.

То есть для создания подписки необходимо указать:

  • клиента,
  • договор,
  • тариф,
  • какие услуги назначены в конкретной подписке, а также количество каждой услуги.

На схеме условно показана связь между основными объектами системы.

image

LBX рассчитывает списания по каждой подписке и списывает средства с договора. Подробнее о том, как выполняются списания.

Начало работы с API LBX

Обратите внимание: в описанных примерах запросов:

  • используется демостенд LBX. Вы можете использовать его, чтобы изучить взаимодействием с LBX в тестовом режиме, а также проверить результаты запросов.
  • используются объекты, уже созданные на демостенде. В реальной интеграции ID тарифов, периодов тарификации и услуг можно получить с помощью методов API:
    • GET /tariffs — получение списка тарифов,
    • GET /tariffs/{tar_id}/periods — получение списка доступных на тарифе периодов,
    • GET /tariffs/{tar_id}/services — получение списка услуг тарифа.
  • используется curl в Linux/macOS shell. Для Windows синтаксис может отличаться.

Аутентификация

Получите токен, используя basicAuth:

curl -X GET 'https://demo.lbxbilling.ru/api/rest/v1/auth' \
  -H "Authorization: Basic BASE64_STRING "

Ответ при успешном выполнении запроса:

{
    "code": 200,
    "response":
    {
        "expires_in": 600,
        "token": "YOUR_API_TOKEN"
    }
}

Для аутентификации запроса передайте заголовок с полученным токеном в формате Authorization: Bearer YOUR_API_TOKEN.

Пример 1: минимальный сценарий подключения подписки новому клиенту

При успешном создании объекта API обычно возвращает код 201 Created или 200 OK, а также ID созданного объекта.

Создать клиента

Создайте нового клиента через endpoint POST /users.

Данные о клиенте в этом примере:

  • type — тип клиента: юридическое или физическое лицо (в примере: type = 1 — юридическое лицо),
  • organization — название организации (в примере: “Test organization”),
  • email — в примере: “support@lbxbilling.ru”.

Пример запроса на создание клиента:

curl -X POST 'https://demo.lbxbilling.ru/api/rest/v1/users'
	-H 'Content-Type: application/json' \
	-H 'Authorization: Bearer YOUR_API_TOKEN' \
	-d '{
			"type": 1,
			"organization": "Test organization",
			"email": "support@lbxbilling.ru"
		}'

Ответ при успешном выполнении запроса:

{
  "code": 201,
  "response": {
    "user_id": 6
  }
}
Создать договор

Создайте договор через endpoint POST /agreements.

В теле запроса передайте:

  • user_id — ID клиента (в примере: user_id = 6 — идентификатор клиента, созданного на предыдущем шаге),
  • is_offer — признак договора оферты (в примере: is_offer = false — не является договором оферты),
  • agreement_number — номер договора (в примере: “doc_agrm”). Номер не требуется для договоров оферты,
  • create_date — дату заключения договора.

Пример запроса на создание договора:

curl -X POST 'https://demo.lbxbilling.ru/api/rest/v1/agreements' \
	-H 'Content-Type: application/json' \
	-H 'Authorization: Bearer YOUR_API_TOKEN ' \
	-d '{
			"user_id": 6,
			"is_offer": false,
			"agreement_number": "doc_agrm",
			"create_date": "2026-03-01"
		}'

Ответ при успешном выполнении запроса:

{
  "code": 200,
  "response": {
    "agreement_id": 6
  }
}
Создать подписку

В примере используется тариф, уже настроенный на демостенде, а также услуги, входящие в этот тариф.

Создайте подписку через endpoint POST /subscriptions.

В теле запроса передайте:

  • agreement_id — ID договора, к которому будет привязана подписка (в примере: agreement_id = 6 — идентификатор договора, созданного на предыдущем шаге),
  • tariff_id — ID тарифа (в примере: tariff_id = 1)
  • period_id — ID периода тарификации (в примере: period_id = 1. Длина данного периода составляет 1 месяц).

Услуги, которые будут назначены в подписке, передаются в массиве services. В нём необходимо указать:

  • tariff_service_id — ID услуги из тарифа (в примере: tariff_service_id = 1)
  • multiplicator — количество услуги в подписке (в примере: multiplicator = 1.0)

Пример запроса на создание подписки с одной услугой:

curl -X POST 'https://demo.lbxbilling.ru/api/rest/v1/subscriptions' \
	-H 'Content-Type: application/json' \
	-H 'Authorization: Bearer YOUR_API_TOKEN' \
	-d '{
			"agreement_id": 6,
			"description": "Название подписки №1",
			"subscription_start_date": "2026-03-01 00:00:00",
			"period_id": 1,
			"tariff_id":1,
			"services": [
				{
					"tariff_service_id": 1,
					"multiplicator": 1.0
				}
			]
		}'

Ответ при успешном выполнении запроса:

{
  "code": 200,
  "response": {
    "subscription_id": 1
  }
}

Подписка создана. LBX будет рассчитывать стоимость услуг с заданной периодичностью (согласно настройкам тарифа) и списывать средства с баланса на договоре.

Пример 2: изменение подписки

Со временем условия подписки могут меняться. Например, может потребоваться изменить тариф, подключить или отключить услуги, изменить количество предоставляемых услуг. Подобное изменение условий подписки происходит через создание новой версии подписки.

В LBX изменение условий подписки обычно выполняется через создание новой версии подписки (PATCH), чтобы сохранить историю тарификации. Подробнее о том, как устроены версии подписок.

Создайте новую версии подписки через endpoint PATCH /subscriptions/{subscr_id}.

  • subscr_id — ID подписки, для которой хотите запланировать изменение (в примере: subscr_id = 1 — идентификатор подписки, созданной в предыдущем шаге).
  • change_start_date — дата, с которой вступит в силу новая версия подписки. Тарификация и списания будут происходить уже по изменённым условиям.

В примере запроса на создание новой версии подписки:

  • количество назначенной услуги изменено (multiplicator = 2),
  • изменена цена действующей услуги (new_price = 150).
  • добавлена новая услуга в количестве 1 (tariff_service_id = 2, multiplicator = 1).

Пример запроса на создание новой версии подписки:

curl -X PATCH 'https://demo.lbxbilling.ru/api/rest/v1/subscriptions/1' \
	-H 'Content-Type: application/json' \
	-H 'Authorization: Bearer YOUR_API_TOKEN' \
	-d '{
			"description": "Новое название подписки",
			"change_start_date": "2026-04-01 00:00:00",
			"period_id": 1,
			"tariff_id": 1,
			"services": [
				{
					"tariff_service_id": 1,
					"multiplicator": 2,
					"modifier": {
						"new_price": 150
					}
				},
				{
					"multiplicator": 1.000000,
					"tariff_service_id": 2
				}
			]
		}'

Список основных методов API LBX

Полный список методов — в Swagger API LBX.

Клиенты (users)

  • GET /users — получить список клиентов
  • POST /users — создать клиента
  • GET /users/{id} — получить клиента
  • PATCH /users/{id} — обновить информацию о клиенте
  • DELETE /users/{id} — удалить клиента

Договоры (agreements)

  • GET /agreements — получить cписок договоров
  • POST /agreements — создать договор
  • GET /agreements/{agrm_id} — получить договор
  • PATCH /agreements/{agrm_id} — обновить информацию о договоре
  • DELETE /agreements/{agrm_id} — расторгнуть договор

Подписки (subscriptions)

  • GET /subscriptions — получить список подписок
  • POST /subscriptions — создать подписку
  • GET /subscriptions/{subscr_id} – получить подписку
  • PATCH /subscriptions/{subscr_id} — запланировать изменение или закрытие подписки
  • PUT /subscriptions/{subscr_id} — отредактировать подписку
  • DELETE /subscriptions/{subscr_id} — удалить подписку вместе со всеми списаниями

У вас есть вопросы по этой статье? Пожалуйста, напишите нам на .