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

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

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

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

LBX позволяет вести учёт услуг, рассчитывать списания за эти услуги и выставлять документы клиентам. Ключевые объекты системы, которые задействованы при этом:

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

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

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

image

LBX проверяет, какие услуги и в каком количестве назначены в подписке, и рассчитывает списания денежных средств с учётом всех условий.

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

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

Аутентификация для работы с API LBX

Получите токен, используя 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: создание клиента, договора и подписки

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

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

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

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

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

curl '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 клиента
  • is_offer — признак договора оферты
  • agreement_number — номер договора (не требуется для договоров оферты)
  • 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
  }
}
Создать подписку

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

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

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

  • agreement_id — id только что созданного договора. К нему будет привязана создаваемая подписка.
  • 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: изменение подписки

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

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

  • subscr_id — id подписки, для которой хотите запланировать изменение. Используется id первой версии подписки.
  • change_start_date — дата, с которой вступит в силу новая версия подписки. Тарификация и списания будут происходить уже по изменённым условиям.

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

  • добавлена одна новая услуга из тарифа,
  • изменена цена у действующей услуги.

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

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

Клиенты (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} — удалить подписку вместе со всеми списаниями

Подробнее — в Swagger API LBX.

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