# Overview

Which official SDK to use for your stack, how to install it, and the same list as JSON.

Official SDKs wrap the BeeL. REST API with typed clients, automatic retries,
idempotency, and webhook verification — so you can ship integrations faster.

## Pick the SDK for your stack

| Stack | Detected by | Package | Install | Status | Docs |
|---|---|---|---|---|---|
| TypeScript, JavaScript (Node.js 18+) | `package.json` | [`@beel_es/sdk`](https://www.npmjs.com/package/@beel_es/sdk) | `npm install @beel_es/sdk` | Recommended, 2.2.0+ | [Node.js / TypeScript SDK](/sdks/node) |
| Python (Python 3.10+) | `pyproject.toml`, `requirements.txt`, `setup.py`, `Pipfile` | [`beel-sdk`](https://pypi.org/project/beel-sdk/) | `pip install beel-sdk` | Legacy: Version 1.0.0 calls the routes without the company in the path, which retire on the date in the deprecation policy. Until a new release, call the REST API. | — |
| Java (Java 11+) | `pom.xml`, `build.gradle`, `build.gradle.kts` | [`es.beel:beel-sdk`](https://central.sonatype.com/artifact/es.beel/beel-sdk) | `implementation 'es.beel:beel-sdk:1.0.2'` | Legacy: Version 1.0.2 calls the routes without the company in the path, which retire on the date in the deprecation policy. Until a new release, call the REST API. | — |

No recommended SDK for your stack: call the REST API as the API reference describes, or generate a typed client from the OpenAPI specification.

The guides with SDK code, such as [From order to invoice](/guides/order-to-invoice), are written for the recommended SDK. Every endpoint is also in the API reference, and you can generate a typed client from the [OpenAPI specification](/api/openapi).

## The catalogue as JSON [#sdks-json]

The same list is published at [`/api/sdks.json`](/api/sdks.json), for agents and tools that need to decide which SDK a project should use. `version` is the version of its shape: new fields are added without changing it, and a change that breaks a reader bumps it.

| Field | Meaning |
|---|---|
| `version` | Shape version, `1` |
| `source` | The URL of this file |
| `directive` | The instruction for a project with no SDK: install it first, do not hand-write HTTP calls |
| `config_note` | How to configure the client: the project's own variable names, any base URL |
| `fallback.text`, `fallback.openapi_url` | What to do when no recommended SDK matches the stack |
| `sdks[].id` | `node`, `python`, `java` |
| `sdks[].status` | `recommended`, or `legacy` (published, not for new integrations; `status_note` says why) |
| `sdks[].languages`, `sdks[].runtime` | What it is for |
| `sdks[].detect` | Files at the project root that identify the stack, such as `package.json` |
| `sdks[].package` | `registry` (`npm`, `pypi`, `maven`), `name` and `url` |
| `sdks[].install` | `tool`, `command`, and `alternatives` (`tool`, `command`) |
| `sdks[].min_version` | The lowest version the docs are written for |
| `sdks[].docs_url`, `sdks[].docs_md_url` | Its page, and the same page in Markdown; `null` when it has none |
| `sdks[].guides[]` | `url` and `md_url` of each guide with code for it |

## Related

<Related>

- [Node.js SDK](/sdks/node) — every resource and method
- [From order to invoice](/guides/order-to-invoice) — the SDK code for every common case

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi