dolibarr-api

Low-level REST client for the Dolibarr API, 100% generated by openapi-generator (-g ruby-idiomatic) from the instance's OpenAPI spec. A generic gem with no business logic: multi-instance, Faraday, Zeitwerk, per-resource namespaced sub-clients.

• Verified target: Dolibarr 23.0.3 (Swagger 2.0, 199 paths, 16 tags).
• Pinned and committed spec: versions/dolibarr-rest.v23.0.3.json.

⚠️ lib/ is entirely generated — never edit it by hand. Every change goes through the spec + mise run generate. The only hand-maintained files are listed in .openapi-generator-ignore (README, mise.toml, versions/, .github/, .gitignore, spec/smoke/).

Installation

# Gemfile
gem 'dolibarr-api', git: 'https://github.com/jbox-web/dolibarr-api.git'

bundle install

Configuration (environment variables)

Secrets are never hard-coded or committed — only supplied through the environment:

Variable	Purpose
DOLIBARR_BASE_URL	e.g. https://dolibarr.example.org
DOLAPIKEY	per-user API key

Usage

A multi-instance Client carries the base URL and API key; sub-clients are namespaced per resource:

require 'dolibarr-api'

client = Dolibarr::Api::Client.new(
  base_url: "#{ENV.fetch('DOLIBARR_BASE_URL')}/api/index.php",
  api_key:  ENV.fetch('DOLAPIKEY')
)

response = client.invoices.list(limit: 1)
response.status   # => 200
response.data     # => Array (or ApiError 404 if the list is empty, see below)

Authentication is sent as the api_key query parameter (as the spec declares); the instance accepts either that parameter or the DOLAPIKEY header interchangeably.

Restler quirks exposed raw

This transport adds no intelligence (that lives in dolibarr-client):

• An empty list returns HTTP 404 ({"error":{"code":404,…}}) instead of [] — the transport then raises Dolibarr::Api::ApiError (#status == 404).
• 403 when permissions are missing.
• Amounts as strings ("8900.00000000"), loose types, sqlfilters as free text.
• Pagination: limit, page, sortfield (e.g. t.rowid), sortorder.

Regeneration

mise run generate   # purge lib/ + generate from the pinned spec (-g ruby-idiomatic)
mise run build      # generate + format (format is a no-op unless rubocop is on PATH;
                    # the ruby-idiomatic generator already emits rubocop-clean code)
mise run dev:spec   # spec suite

Generator jar. ruby-idiomatic lives on an unmerged fork branch of openapi-generator and is not published on Maven. The jar (openapi-generator-cli.jar, gitignored) is built from the fork — see .github/workflows/regenerate.yml.

Tests

• Generated network-free unit specs (model round-trips, sub-client resolution).
• One read-only smoke test (GET /invoices?limit=1) driven by DOLIBARR_BASE_URL + DOLAPIKEY, skipped when they are absent.

License

MIT — see LICENSE.