Backend SDKs

Call the Solvimon API from your server in TypeScript, Python or Java with typed clients for every endpoint, instead of building HTTP requests by hand.

Why use a backend SDK

The backend SDKs wrap the same REST API that the API reference describes. Each SDK gives you typed request and response models, so your editor catches a missing field or a wrong enum value before the request is sent. Use them from your own servers only: they authenticate with your secret API key, which must never reach a browser. To render billing UI in the browser, use the Frontend Components instead.

Available SDKs

All three SDKs are generated from the Solvimon OpenAPI specification, so every endpoint in the API reference is available in each language.

Install

npm install @solvimon/solvimon-typescript-sdk

The current Python package version is a pre-release on PyPI, which is why the command needs --pre.

Configure the client

Each SDK needs two things: the base URL of the environment and an API key. Create a key in Desk as described in API key creation, and keep it in an environment variable rather than in your code.

The SDKs default to the sandbox. Set the base URL explicitly so that switching to live is a configuration change, not a code change.

import { Configuration, CustomersApi } from '@solvimon/solvimon-typescript-sdk';
const config = new Configuration({
  basePath: 'https://test.api.solvimon.com',
  apiKey: process.env.SOLVIMON_API_KEY,
});
const customers = new CustomersApi(config);

The SDKs send the key in the X-API-KEY header, the same header the API reference uses. In Python, the key in the api_key dictionary must be "API-Key".

Make your first call

This example creates an organization customer, the same request as POST /v1/customers.

import { ResponseError } from '@solvimon/solvimon-typescript-sdk';
try {
  const customer = await customers.postCustomers({
    version: '1',
    customerCreateRequest: {
      type: 'ORGANIZATION',
      reference: 'acme-corp',
      email: 'billing@acme.example',
      organization: { legal_name: 'Acme Corp B.V.' },
    },
  });
  console.log(customer.id);
} catch (err) {
  if (err instanceof ResponseError) {
    console.error(err.response.status, await err.response.json());
  } else {
    throw err;
  }
}

How the SDKs map to the API

Once you know the endpoint in the API reference, you can find the SDK call:

• API classes follow the resource. Customer endpoints are on CustomersApi, invoice endpoints on InvoicesApi, event ingestion on IngestApi, and so on.
• Method names follow the HTTP method and path. POST /v1/customers is postCustomers (post_customers in Python), and GET /v1/customers/{id} is getCustomersByResourceIdOrReference.
• version is a required argument on every call. Pass "1".
• Request and response fields keep the API’s snake_case names in TypeScript and Python, so field names match the API reference. Java uses camelCase setters and getters, such as legalName() for legal_name.
• Optional headers are arguments. To act on a specific platform, pass xPlatformId (TypeScript and Java) or x_platform_id (Python).

Errors

A response with a 4xx or 5xx status raises an error that carries the status code and the response body, as shown in the example above: ResponseError in TypeScript, ApiException in Python and Java. The body has the same structure as any API error; see Errors for the reasons Solvimon returns.

Edge cases

• The SDKs do not retry failed requests. To retry a POST safely, send an idempotency key.
• SDK versions are published separately from API releases, so a field that was just added to the API may not be in the SDK version you have installed yet. The API reference is the source of truth for every field; upgrade the SDK to pick up new ones.