Dolibarr

Dolibarr

Self-hosted ERP/CRM: products, orders, proposals, customer and supplier invoices, third parties, contacts, users, categories, stock movements, projects, warehouses, bank accounts, and shipments.

Multicompany (multi-society)

One Dolibarr URL can host multiple legal entities. Dolibarr routes API calls by the DOLAPIENTITY header — not a query parameter.

1. Discover first when the user mentions multiple societies or entity-specific data — run entity discovery (read-only probe of numeric ids). Results cache on the connection.
2. Per call — pass entity (numeric id) on reads and writes.
3. Default — set default_entity on the connection to avoid repeating the id.
4. When exactly one entity is accessible, discovery auto-selects it. When several are accessible, pass entity or set default_entity.

Operational order

1. Entities (multicompany only) — discover accessible societies when scope is unclear.
2. Products / categories — catalog shape and category_id for filtered product lists.
3. Third parties and contacts — customers (third-party mode=1), suppliers (mode=4), then contacts filtered by socid.
4. Commercial documents — proposals and orders (headers, then lines via include=lines on reads or line upserts on writes).
5. Invoices — list headers first; line and payment detail via include on reads.
6. Stock — warehouses, stock movements, shipments when inventory questions arise.
7. Company setup — admin-only on many instances.

Writes

• Upsert pattern: omit id to create draft rows; pass id to update headers.
• Document lines are separate upserts on the parent document id.
• Document validation (approve/close) on orders, proposals, and invoices triggers workflow and accounting side effects — only when the user explicitly asks.
• Deletes are irreversible on most instances; confirm destructive intent first.

Gotchas

• REST entry point is /api/index.php on the user's host (not index.html, not bare /api).
• Without entity, Dolibarr uses its default context — not necessarily the society the user means.
• Some multicompany installs return HTTP 500 with a valid JSON body; reads still return data.
• Company setup often requires an admin API key.
• Category lists require type (e.g. product).
• Third-party list mode: 1=customers, 4=suppliers.
• Invoice, order, and proposal detail: use include=lines (and include=payments on customer invoices) when id is set.
• Projects, bank accounts, and some stock endpoints require modules or permissions the API user may lack.