Merchant API и JS-клиент

Пакет npm

Опубликованный клиент: @wilix/billbill-client-js .

Исходный код в монорепозитории BillBill: каталог billbill-client-js/ (генерация из OpenAPI: yarn generate).

Установка и инициализация


yarn add @wilix/billbill-client-js


import { ApiClient, MerchantApi } from '@wilix/billbill-client-js'
 
const client = new ApiClient({
  apiKey: process.env.BILLBILL_MERCHANT_KEY!,
  baseUrl: 'https://api.billbill.ru',
  userAgent: 'MySaaS/1.0 OpenAPI'
})
 
const merchant = new MerchantApi(client)

Категории методов `MerchantApi` (ориентир)

Ниже — группы вызовов; точные имена и тела запросов смотрите в TypeScript-типах и Swagger.

Область	Примеры методов клиента
Профиль и ключи	`newApikey`, настройки профиля
Продукты и планы	`productNew`, `productEdit`, `planNew`, `planEdit`, `planActivate`, `planAddonsBinding`
Пользователи мерчанта	операции с пользователями/клиентами (`user` / `member` — по версии клиента)
Подписки	`subscriptionCreatePreview`, `subscriptionCreateSubmit`, `subscriptionRenew`, `subscriptionUpdate*`
Счета и платежи	`invoiceNew`, `invoiceDetail`, `paymentNew`, `paymentRefund*`
Метрики	`metricNew`, `metricEdit`, `metricNewEvent`, `metricEventList`, `userMetric`, `limitGrantNew`, `limitGrantList`, `limitGrantRevoke`
Шлюзы	`gatewaySetup`, `gatewaySetupWebhook`, `gatewayEdit`
Шаблоны	`document_templateNew`, `document_templateEdit`
Скрипты	`scriptNew`, `scriptEdit`, `scriptDebug`
Вебхуки	`webhookNewEndpoint`, `getWebhookEndpointList`, `getWebhookEventList`

Полный список — в файле billbill-client-js/src/merchant.ts.

Частые ошибки интеграции

Симптом	Причина	Решение
`sub not found`	В `subscriptionId` передан `subscription.id` (number)	Используйте `subscription.subscriptionId` (string)
`BaseGateway invalid`	Нет `gatewayId` в `create_submit`	Передайте id активного шлюза, даже для free-плана
`product not found`	Перепутаны `productId` и `planId`	Для дефолтного продукта: `productId: 0`
`Server Error` при апгрейде	Нет `returnUrl` при `totalAmount > 0`	Сначала `update_preview`, затем `returnUrl` в submit

Подробный справочник: Справочник полей подписки. Сквозной пример: Быстрый старт.

Вспомогательные функции SDK


import {
  assertReturnUrlForPaidOperation,
  isValidProductId,
  getSubscriptionApiId,
} from '@wilix/billbill-client-js'
 
// productId: 0 — валиден
isValidProductId(0) // true
 
// из ответа detail — правильный id для API
const subscriptionId = getSubscriptionApiId(subscription)

Ответы API

Типичный конверт GoFrame: поле code (0 = успех), data, сообщение об ошибке. Клиент бросает BillBillError при неуспехе — см. errors.ts.

OpenAPI / Swagger

Актуальная схема — на работающем инстансе API: http://127.0.0.1:8088/swagger-ui.html (dev) или URL, выданный облаком.