<!--
Copyright (C) 2026 Moko Consulting <hello@mokoconsulting.tech>

This file is part of a Moko Consulting project.

SPDX-License-Identifier: GPL-3.0-or-later

# FILE INFORMATION
DEFGROUP: dolibarr-api-mcp.Documentation
INGROUP: dolibarr-api-mcp
REPO: https://git.mokoconsulting.tech/MokoConsulting/dolibarr-api-mcp
PATH: /docs/API.md
VERSION: 01.00.00
BRIEF: MCP tool reference documentation
-->

# API Reference

All tools accept an optional `connection` parameter to target a specific named connection. If omitted, the default connection is used.

All list tools accept optional pagination parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | number | Max results (default 100) |
| `page` | number | Page number (0-based) |
| `sortfield` | string | Field to sort by |
| `sortorder` | `"ASC"` / `"DESC"` | Sort direction |

## Third Parties

### `dolibarr_thirdparties_list`
List third parties (customers, suppliers, prospects).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | `"1"` / `"2"` / `"3"` / `"4"` | No | 1=customer, 2=prospect, 3=supplier, 4=customer+supplier |
| `search` | string | No | Search in name |
| `category` | number | No | Filter by category ID |

### `dolibarr_thirdparty_get`
Get a single third party by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Third party ID |

### `dolibarr_thirdparty_create`
Create a new third party.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Company or individual name |
| `client` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=neither, 1=customer, 2=prospect, 3=customer+prospect |
| `fournisseur` | `"0"` / `"1"` | No | 0=not supplier, 1=supplier |
| `email` | string | No | Email address |
| `phone` | string | No | Phone number |
| `address` | string | No | Street address |
| `zip` | string | No | Postal code |
| `town` | string | No | City |
| `country_id` | number | No | Country ID |

### `dolibarr_thirdparty_update`
Update an existing third party. Only provided fields are changed.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Third party ID |
| `name` | string | No | Company or individual name |
| `email` | string | No | Email address |
| `phone` | string | No | Phone number |
| `address` | string | No | Street address |
| `zip` | string | No | Postal code |
| `town` | string | No | City |
| `country_id` | number | No | Country ID |

### `dolibarr_thirdparty_delete`
Delete a third party.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Third party ID |

## Invoices

### `dolibarr_invoices_list`
List invoices.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"draft"` / `"unpaid"` / `"paid"` / `"cancelled"` | No | Filter by status |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |
| `search` | string | No | Search in ref or ref_client |

### `dolibarr_invoice_get`
Get a single invoice by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |

### `dolibarr_invoice_create`
Create a new invoice.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party (customer) ID |
| `type` | `"0"` / `"1"` / `"2"` / `"3"` | No | 0=standard, 1=replacement, 2=credit note, 3=deposit |
| `date` | string | No | Invoice date (YYYY-MM-DD or Unix timestamp) |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |

### `dolibarr_invoice_add_line`
Add a line item to an invoice.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
| `desc` | string | Yes | Line description |
| `subprice` | number | Yes | Unit price (HT) |
| `qty` | number | Yes | Quantity |
| `tva_tx` | number | No | VAT rate (e.g. 20.0) |
| `product_id` | number | No | Product/service ID |

### `dolibarr_invoice_validate`
Validate (finalize) a draft invoice. Changes status from draft to validated and assigns an invoice number.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |

### `dolibarr_invoice_set_paid`
Mark an invoice as paid.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Invoice ID |
| `close_code` | string | No | Close code (e.g. `"bankorder"`, `"cash"`) |
| `close_note` | string | No | Close note |

## Proposals (Quotes)

### `dolibarr_proposals_list`
List commercial proposals.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` / `"3"` / `"4"` | No | 0=draft, 1=validated, 2=signed, 3=not-signed, 4=billed |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |

### `dolibarr_proposal_get`
Get a single proposal by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |

### `dolibarr_proposal_create`
Create a new commercial proposal.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party (customer) ID |
| `date` | string | No | Proposal date (YYYY-MM-DD or Unix timestamp) |
| `duree_validite` | number | No | Validity duration in days |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |

### `dolibarr_proposal_add_line`
Add a line item to a proposal.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |
| `desc` | string | Yes | Line description |
| `subprice` | number | Yes | Unit price (HT) |
| `qty` | number | Yes | Quantity |
| `tva_tx` | number | No | VAT rate (e.g. 20.0) |
| `product_id` | number | No | Product/service ID |

### `dolibarr_proposal_validate`
Validate a draft proposal.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |

### `dolibarr_proposal_close`
Close a proposal (sign or refuse).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Proposal ID |
| `status` | `"2"` / `"3"` | Yes | 2=signed, 3=not signed (refused) |
| `note` | string | No | Close note |

## Orders

### `dolibarr_orders_list`
List customer orders.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` / `"3"` / `"-1"` | No | 0=draft, 1=validated, 2=processing, 3=delivered, -1=cancelled |
| `thirdparty_ids` | string | No | Comma-separated third party IDs |

### `dolibarr_order_get`
Get a single order by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Order ID |

### `dolibarr_order_create`
Create a new customer order.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `socid` | number | Yes | Third party (customer) ID |
| `date` | string | No | Order date (YYYY-MM-DD or Unix timestamp) |
| `note_public` | string | No | Public note |
| `note_private` | string | No | Private note |

### `dolibarr_order_validate`
Validate a draft order.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Order ID |

## Products / Services

### `dolibarr_products_list`
List products and/or services.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | `"0"` / `"1"` | No | 0=product, 1=service |
| `search` | string | No | Search in label or ref |
| `category` | number | No | Filter by category ID |
| `to_sell` | `"0"` / `"1"` | No | 1=for sale only |
| `to_buy` | `"0"` / `"1"` | No | 1=for purchase only |

### `dolibarr_product_get`
Get a single product/service by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Product ID |

### `dolibarr_product_create`
Create a new product or service.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ref` | string | Yes | Product reference code |
| `label` | string | Yes | Product label/name |
| `type` | `"0"` / `"1"` | No | 0=product, 1=service (default 0) |
| `price` | number | No | Selling price (HT) |
| `price_ttc` | number | No | Selling price (TTC) |
| `tva_tx` | number | No | Default VAT rate |
| `description` | string | No | Description |
| `status` | `"0"` / `"1"` | No | 1=on sale, 0=not on sale |
| `status_buy` | `"0"` / `"1"` | No | 1=on purchase, 0=not on purchase |

### `dolibarr_product_update`
Update a product or service. Only provided fields are changed.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Product ID |
| `ref` | string | No | Product reference code |
| `label` | string | No | Product label/name |
| `price` | number | No | Selling price (HT) |
| `description` | string | No | Description |
| `status` | `"0"` / `"1"` | No | On sale flag |
| `status_buy` | `"0"` / `"1"` | No | On purchase flag |

### `dolibarr_product_stock`
Get stock levels for a product across all warehouses.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Product ID |

## Contacts / Addresses

### `dolibarr_contacts_list`
List contacts/addresses.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search in name |
| `thirdparty_id` | number | No | Filter by third party ID |

### `dolibarr_contact_get`
Get a single contact by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Contact ID |

## Projects

### `dolibarr_projects_list`
List projects.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` / `"1"` / `"2"` | No | 0=draft, 1=open, 2=closed |
| `search` | string | No | Search in title or ref |

### `dolibarr_project_get`
Get a single project by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Project ID |

### `dolibarr_project_create`
Create a new project.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `ref` | string | Yes | Project reference |
| `title` | string | Yes | Project title |
| `socid` | number | No | Third party ID |
| `description` | string | No | Project description |
| `date_start` | string | No | Start date (YYYY-MM-DD or Unix timestamp) |
| `date_end` | string | No | End date (YYYY-MM-DD or Unix timestamp) |

## Tasks

### `dolibarr_tasks_list`
List project tasks.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `project_id` | number | No | Filter by project ID |

### `dolibarr_task_get`
Get a single task by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | Task ID |

## Users

### `dolibarr_users_list`
List Dolibarr users.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Search in login name |

### `dolibarr_user_get`
Get a single user by ID.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | Yes | User ID |

## Categories

### `dolibarr_categories_list`
List categories.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | `"product"` / `"supplier"` / `"customer"` / `"member"` / `"contact"` / `"project"` | No | Category type |
| `search` | string | No | Search in label |

## Bank Accounts

### `dolibarr_bankaccounts_list`
List bank accounts. No additional parameters (supports pagination).

## Supplier Invoices

### `dolibarr_supplier_invoices_list`
List supplier invoices.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"draft"` / `"unpaid"` / `"paid"` / `"cancelled"` | No | Filter by status |
| `thirdparty_ids` | string | No | Comma-separated supplier IDs |

## Supplier Orders

### `dolibarr_supplier_orders_list`
List supplier orders (purchase orders).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `status` | `"0"` - `"5"`, `"9"` | No | 0=draft, 1=validated, 2=approved, 3=ordered, 4=partially received, 5=received, 9=cancelled |
| `thirdparty_ids` | string | No | Comma-separated supplier IDs |

## Warehouses

### `dolibarr_warehouses_list`
List warehouses. No additional parameters (supports pagination).

## Setup / System

### `dolibarr_setup_company`
Get company/entity information. No parameters.

### `dolibarr_status`
Get Dolibarr instance status and version. No parameters.

## Generic

### `dolibarr_api_request`
Make a raw API request to any Dolibarr REST endpoint.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `method` | `"GET"` / `"POST"` / `"PUT"` / `"DELETE"` | Yes | HTTP method |
| `endpoint` | string | Yes | API path (e.g. `"/thirdparties"`) |
| `body` | object | No | Request body for POST/PUT |
| `params` | object | No | Query parameters |

### `dolibarr_list_connections`
List all configured connections. No parameters.

## Revision History

| Date | Version | Author | Notes |
| --- | --- | --- | --- |
| 2026-05-07 | 0.0.1 | jmiller | Initial API reference |