dolibarr-mcp/api/README.md

# Dolibarr API Documentation - Complete Analysis
## Instance Information: db.ginos.cloud

**Dolibarr Version:** 21.0.1  
**API Base URL:** https://db.ginos.cloud/api/index.php  
**Authentication:** DOLAPIKEY header  
**Response Format:** JSON

## ✅ Confirmed Working Endpoints

### 1. **Status Endpoint**
- **URL:** `/status`
- **Method:** GET
- **Purpose:** API health check and version info
- **Response:** 
```json
{
  "success": {
    "code": 200,
    "dolibarr_version": "21.0.1",
    "access_locked": "0"
  }
}
```

### 2. **Users Endpoint**
- **URL:** `/users`
- **Method:** GET, POST, PUT, DELETE
- **Purpose:** User management
- **Parameters:** limit, sortfield, sortorder
- **Response:** Array of user objects with complete profile data
- **Fields Include:** id, login, lastname, firstname, email, admin, status, etc.
- **Status:** ✅ Fully functional with 4 users found

### 3. **Third Parties Endpoint** (Customers/Suppliers)
- **URL:** `/thirdparties`
- **Method:** GET, POST, PUT, DELETE
- **Purpose:** Customer/supplier management
- **Parameters:** limit, sortfield, sortorder, sqlfilters
- **Response:** Array of third party objects
- **Fields Include:** id, name, address, phone, email, status, type (client/supplier)
- **Status:** ✅ Fully functional with 1 test customer found

### 4. **Products Endpoint**
- **URL:** `/products`
- **Method:** GET, POST, PUT, DELETE
- **Purpose:** Product catalog management
- **Parameters:** limit, sortfield, sortorder
- **Response:** Array of product objects
- **Status:** ✅ Accessible but currently empty

### 5. **Invoices Endpoint**
- **URL:** `/invoices`
- **Method:** GET, POST, PUT, DELETE
- **Purpose:** Invoice management
- **Parameters:** limit, status filtering
- **Response:** Array of invoice objects
- **Status:** ✅ Accessible but currently empty

### 6. **Orders Endpoint**
- **URL:** `/orders`
- **Method:** GET, POST, PUT, DELETE
- **Purpose:** Order management
- **Parameters:** limit, status filtering
- **Response:** Array of order objects
- **Status:** ✅ Accessible but currently empty

### 7. **Contacts Endpoint**
- **URL:** `/contacts`
- **Method:** GET, POST, PUT, DELETE
- **Purpose:** Contact management
- **Parameters:** limit, thirdparty filtering
- **Response:** Array of contact objects
- **Status:** ✅ Accessible but currently empty

## ❌ Non-Working/Problematic Endpoints

### 1. **Setup Endpoint**
- **URL:** `/setup`
- **Status:** ❌ 404 Not Found
- **Note:** May require different path or parameters

### 2. **Documents Endpoint**
- **URL:** `/documents`
- **Status:** ❌ 400 Bad Request
- **Note:** Requires specific parameters (modulepart, filename, etc.)

## 🔍 API Patterns Identified

### Standard Query Parameters
All list endpoints support these parameters:
- `limit`: Number of records to return (default: 100)
- `sortfield`: Field to sort by
- `sortorder`: ASC or DESC
- `sqlfilters`: Advanced filtering using SQL-like syntax

### Authentication
- **Header:** `DOLAPIKEY: your_api_key`
- **Format:** Token-based authentication
- **Permission:** Tied to user permissions in Dolibarr

### Response Structure
- **Success:** Array of objects or single object
- **Error:** JSON with error details
- **HTTP Status Codes:** 200, 201, 400, 401, 403, 404, 500

### Data Structure Pattern
All business objects share common fields:
- `id`: Unique identifier
- `ref`: Reference number
- `status`/`statut`: Status code
- `date_creation`: Creation timestamp
- `user_creation_id`: Creator user ID
- `note_public`/`note_private`: Notes
- `array_options`: Custom fields

## 🏗️ Recommended MCP Server Structure

### Core Modules
1. **Customer Management** (`/thirdparties`)
   - get_customers()
   - get_customer_by_id()
   - create_customer()
   - update_customer()
   - delete_customer()

2. **Product Management** (`/products`)
   - get_products()
   - get_product_by_id()
   - create_product()
   - update_product()
   - delete_product()

3. **Invoice Management** (`/invoices`)
   - get_invoices()
   - get_invoice_by_id()
   - create_invoice()
   - update_invoice()
   - delete_invoice()

4. **Order Management** (`/orders`)
   - get_orders()
   - get_order_by_id()
   - create_order()
   - update_order()
   - delete_order()

5. **Contact Management** (`/contacts`)
   - get_contacts()
   - get_contact_by_id()
   - create_contact()
   - update_contact()
   - delete_contact()

6. **User Management** (`/users`)
   - get_users()
   - get_user_by_id()
   - create_user()
   - update_user()
   - delete_user()

### Additional Endpoints to Explore
Based on Dolibarr source code, these endpoints likely exist:
- `/projects` - Project management
- `/suppliers` - Supplier-specific operations
- `/warehouses` - Inventory management
- `/categories` - Category management
- `/members` - Membership management
- `/expensereports` - Expense reporting
- `/tickets` - Support tickets
- `/events` - Calendar events
- `/proposals` - Commercial proposals
- `/contracts` - Contract management
- `/agenda` - Agenda/calendar
- `/actioncomm` - Communication actions
- `/shipments` - Shipping management
- `/receptions` - Reception management
- `/mrp` - Manufacturing Resource Planning
- `/boms` - Bill of Materials
- `/stockmovements` - Stock movements
- `/bankaccounts` - Bank account management
- `/payments` - Payment management
- `/leaverequest` - Leave requests
- `/salaries` - Salary management

## 🔬 Testing Methodology Used

1. **Connection Test:** Verified API accessibility with `/status` endpoint
2. **Core Business Objects:** Tested major CRUD endpoints
3. **Parameter Testing:** Verified filtering and pagination
4. **Error Handling:** Documented error responses
5. **Data Structure Analysis:** Analyzed response formats

## 📝 Next Steps for MCP Development

1. **Create Base MCP Server Structure**
   - Follow prestashop-mcp reference pattern
   - Implement dolibarr_client.py with all discovered endpoints
   - Create MCP server with proper tool definitions

2. **Implement Core Functions**
   - Start with working endpoints (users, thirdparties, products, invoices, orders)
   - Add comprehensive error handling
   - Include proper parameter validation

3. **Test and Expand**
   - Test all CRUD operations
   - Discover additional endpoints through testing
   - Add advanced features (filtering, pagination, etc.)

4. **Documentation and Deployment**
   - Create comprehensive README
   - Add Docker containerization
   - Implement proper logging and monitoring

## 🎯 Immediate Development Priority

**High Priority Endpoints (Confirmed Working):**
1. Users management
2. Customer/Third party management  
3. Product management
4. Invoice management
5. Order management

**Medium Priority (Need Parameter Research):**
1. Document management
2. Contact management
3. Project management

**Low Priority (Discovery Required):**
1. Setup/configuration endpoints
2. Advanced modules (MRP, BOM, etc.)
3. Integration-specific endpoints