dolibarr-mcp/docs/api-reference.md

Dolibarr API Coverage

This server wraps the Dolibarr REST API v21.0.1 that is exposed by an instance at https://db.ginos.cloud/api/index.php. The MCP tools use the following REST resources, mirroring the scope that the sibling prestashop-mcp project implements for PrestaShop.

Authentication and Conventions

• Header – send the DOLAPIKEY header with the personal access token that is configured for your Dolibarr user.
• Content Type – every request uses application/json payloads and responses.
• Pagination – list endpoints accept the limit, sortfield, sortorder and sqlfilters query parameters.
• Identifiers – Dolibarr returns both id (numeric) and ref (business reference) for most entities. The MCP tools expose both values to the client.

Supported Resources

Resource	Endpoint(s)	Tool group
Status	GET /status	get_status, test_connection
Search	/products, /thirdparties	search_products_by_ref, search_customers, resolve_product_ref
Users	/users	CRUD helpers under the Users group
Third parties	/thirdparties	Customer CRUD operations
Products	/products	Product CRUD operations
Invoices	/invoices	Invoice CRUD operations
Orders	/orders	Order CRUD operations
Projects	/projects	Project CRUD operations & Search
Contacts	/contacts	Contact CRUD operations
Raw passthrough	Any relative path	dolibarr_raw_api tool for quick tests

Every endpoint supports create, read, update and delete operations unless noted otherwise. The Dolibarr instance that informed this reference currently contains live data for users, third parties and contacts; other modules respond with empty lists until records are created.

Response Examples

Status

{
  "success": {
    "code": 200,
    "dolibarr_version": "21.0.1",
    "access_locked": "0"
  }
}

Third Party

{
  "id": "1",
  "ref": "1",
  "name": "Test Customer MCP",
  "status": "1",
  "address": "123 Test Street",
  "zip": "12345",
  "town": "Test City",
  "email": "test@mcp-dolibarr.com",
  "phone": "+1-555-0123",
  "date_creation": 1752005684,
  "user_creation_id": "4",
  "array_options": {}
}

Structured Error Shapes

The MCP server and wrapper normalize Dolibarr errors into predictable JSON so callers can surface actionable messages and debugging breadcrumbs.

Validation errors (400)

{
  "error": "Bad Request",
  "status": 400,
  "message": "Validation failed",
  "missing_fields": ["ref", "socid"],
  "invalid_fields": [
    { "field": "price", "message": "must be a positive number" }
  ],
  "endpoint": "/api/index.php/products",
  "timestamp": "2026-01-02T12:34:56Z"
}

Unexpected errors (500)

{
  "error": "Internal Server Error",
  "status": 500,
  "message": "An unexpected error occurred while creating project",
  "correlation_id": "abc123-uuid",
  "endpoint": "/api/index.php/projects",
  "timestamp": "2026-01-02T12:35:06Z"
}

Successful create

{
  "status": 201,
  "id": 42,
  "ref": "FREELANCE_HOUR_TEST",
  "message": "Product created"
}

Include the correlation_id from a 500 response when opening support tickets so logs can be located quickly.

Create Endpoint Requirements & Examples

The wrapper validates payloads before sending them to Dolibarr. Required fields:

Endpoint	Required fields	Notes
POST /products	ref, label, type, price	type accepts product/0 or service/1.
POST /projects	ref, name, socid	title is accepted as an alias for name.
POST /invoices	socid	Provide lines for invoice content.
POST /time (timesheets)	ref, task_id, duration, fk_project	Provide ref or enable auto-generation.

Example: product create without ref (expected 400)

curl -X POST "https://dolibarr.example/api/index.php/products" \
  -H "DOLAPIKEY: <REDACTED>" \
  -H "Content-Type: application/json" \
  -d '{"label":"Freelance hourly rate test — Gino test","type":"service","price":110.00,"tva_tx":19.0}'

Example: corrected product payload

curl -X POST "https://dolibarr.example/api/index.php/products" \
  -H "DOLAPIKEY: <REDACTED>" \
  -H "Content-Type: application/json" \
  -d '{"ref":"FREELANCE_HOUR_TEST","label":"Freelance hourly rate test — Gino test","type":"service","price":110.00,"tva_tx":19.0}'

Example: project create (minimal payload)

curl -X POST "https://dolibarr.example/api/index.php/projects" \
  -H "DOLAPIKEY: <REDACTED>" \
  -H "Content-Type: application/json" \
  -d '{"ref":"PERCISION_TEST_PROJECT","name":"Percision test — Project test","socid":8}'

If server-side reference auto-generation is enabled, omitting ref results in a predictable AUTO_<timestamp> reference. Otherwise, the wrapper will raise a client-side validation error before sending the request.