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

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

### Third Party

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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

```json
{
  "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)

```bash
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

```bash
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)

```bash
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.