Skip to content

README.md

Latest commit

 

History

History
117 lines (72 loc) · 5.32 KB

README.md

File metadata and controls

117 lines (72 loc) · 5.32 KB

API Reference

Complete API specifications for the Decabill billing manager. Specifications are published as OpenAPI 3.1.0 (HTTP REST) and AsyncAPI 3.0.0 (dashboard WebSocket gateway).

Billing Manager HTTP API

The billing manager exposes all billing, subscription, invoice, catalog, and admin operations over HTTP on port 3200 with global prefix /api.

OpenAPI Specification

Specification file: openapi.yaml

Canonical source in the monorepo: libs/domains/decabill/backend/feature-billing-manager/spec/openapi.yaml

The HTTP API includes:

  • Public offerings - Unauthenticated plan listings for marketing pages
  • Service catalog - Service types and service plans (admin)
  • Subscriptions and backorders - Order, cancel, resume, retry, and availability
  • Customer profile - Self-service billing metadata
  • Invoices and open positions - Issue, preview, download, void, pay, and billing-day accumulation
  • Admin billing - Manual invoices, customer profiles, statistics, audit logs, bill-now
  • Authentication and users - Login, register, and user management when AUTHENTICATION_METHOD=users
  • Stripe webhook - Signed payment event handling
  • Configuration - GET /config for operator-visible settings

Authentication

Unless documented as public, operations require authentication:

  • Bearer JWT when using built-in users
  • Bearer Keycloak access token when using Keycloak
  • Bearer or ApiKey static key when using AUTHENTICATION_METHOD=api-key

Send X-Tenant on every request for multi-tenant deployments. Invalid tenant ids return 400.

See Authentication.

Admin manual invoices and customer profiles

Admin CRUD for manual invoices and customer billing profiles is documented in the OpenAPI /admin/billing/* paths.

Product-oriented guide: Billing Administration

Billing Manager WebSocket Gateway

The billing manager runs a Socket.IO server on port 8082 (default), namespace billing, separate from the HTTP listener.

Static API key authentication is not sufficient for the dashboard stream. Connections require an end-user JWT or Keycloak identity, matching REST billing rules.

AsyncAPI Specification

Specification file: asyncapi.yaml

Canonical source in the monorepo: libs/domains/decabill/backend/feature-billing-manager/spec/asyncapi.yaml

The status gateway provides:

Direction Event Description
Client to server subscribeDashboardStatus Start polling provisioned server status for the authenticated user
Client to server unsubscribeDashboardStatus Stop polling for this socket
Server to client dashboardStatusUpdate Periodic status payload (same shape as REST server-info)
Server to client error Application errors scoped to the initiating socket

Pass X-Tenant in handshake metadata (auth.tenantId in browser clients, extraHeaders in Node clients).

See Real-time Status.

Using the Specifications

Swagger Editor

Swagger Editor helps you:

  • Browse endpoints and schemas interactively
  • Validate request and response models
  • Export client stubs or documentation

Load the spec via the docs.decabill.com URL above or the local /spec/billing-manager/openapi.yaml path served by the docs site build.

AsyncAPI Studio

AsyncAPI Studio helps you:

  • Visualize dashboard socket message flows
  • Inspect payload schemas for dashboardStatusUpdate
  • Validate the AsyncAPI document

Generated Client Package

The repository generates a TypeScript Axios client from the OpenAPI spec:

nx run decabill-backend-billing-manager:generate-client

Published npm package (GitHub Packages): @forepath/decabill-billing-manager-client

Configure @forepath scope in .npmrc to install from GitHub Packages. Clients are regenerated on release to stay aligned with the spec.

Related Documentation

For operational deployment variables, see Environment Configuration.