docker-erpnext/API_GUIDE.md

ERPNext API Access Guide

Overview

ERPNext provides comprehensive REST APIs for all its modules. The APIs follow RESTful conventions and return JSON responses.

Important: There is no browsable API index page at /api/. You must access specific endpoints directly.

API Endpoints

Base URL

http://localhost:8080

Common API Endpoints

1. Authentication

# Login
POST http://localhost:8080/api/method/login
{
  "usr": "Administrator",
  "pwd": "LocalDev123!"
}

2. Resource APIs

All DocTypes (database tables) in ERPNext are accessible via REST:

# Get list of items
GET http://localhost:8080/api/resource/Item

# Get specific item
GET http://localhost:8080/api/resource/Item/{item_name}

# Create new item
POST http://localhost:8080/api/resource/Item

# Update item
PUT http://localhost:8080/api/resource/Item/{item_name}

# Delete item
DELETE http://localhost:8080/api/resource/Item/{item_name}

3. Method APIs

Custom server methods can be called:

POST http://localhost:8080/api/method/{method_path}

Authentication Methods

1. Session-based Authentication

After login, a session cookie is set which is used for subsequent requests.

2. Token-based Authentication

Generate API keys from the user settings:

1. Login to ERPNext UI
2. Go to Settings → My Settings
3. Scroll to "API Access" section
4. Generate API Secret
5. Use in requests:

curl -H "Authorization: token api_key:api_secret" \
     http://localhost:8080/api/resource/Item

3. Basic Authentication

curl -u Administrator:LocalDev123! \
     http://localhost:8080/api/resource/Item

Live API Documentation

1. Exploring Available DocTypes

Get a list of all available DocTypes (tables/resources):

# After login
curl -b cookies.txt http://localhost:8080/api/resource/DocType

2. Swagger/OpenAPI Documentation

While ERPNext doesn't have built-in Swagger, you can explore APIs through:

• Frappe Web UI: After logging in, press Ctrl+G (or Cmd+G on Mac) to open the awesome bar and type any DocType name
• Developer Console: Access via browser DevTools to see API calls made by the UI

3. Interactive Console

Access the Python console to explore APIs:

# Enter the backend container
docker exec -it erpnext /bin/bash

# Start bench console
bench --site frontend console

# Example commands in console:
>>> frappe.get_all('Item')
>>> frappe.get_doc('Item', 'ITEM-001')

Common API Operations

Customer Management

# List customers
GET /api/resource/Customer

# Create customer
POST /api/resource/Customer
{
  "customer_name": "Test Customer",
  "customer_type": "Company",
  "customer_group": "All Customer Groups",
  "territory": "All Territories"
}

Item Management

# List items
GET /api/resource/Item

# Create item
POST /api/resource/Item
{
  "item_code": "TEST-001",
  "item_name": "Test Item",
  "item_group": "All Item Groups",
  "stock_uom": "Nos"
}

Sales Order

# Create sales order
POST /api/resource/Sales%20Order
{
  "customer": "Test Customer",
  "delivery_date": "2024-12-31",
  "items": [
    {
      "item_code": "TEST-001",
      "qty": 10,
      "rate": 100
    }
  ]
}

API Response Format

Success Response

{
  "data": {
    // Response data
  }
}

Error Response

{
  "exc_type": "ValidationError",
  "exception": "Error details",
  "_server_messages": "..."
}

Testing APIs

Using cURL

# Login and save cookies
curl -c cookies.txt -X POST \
  -H "Content-Type: application/json" \
  -d '{"usr":"Administrator","pwd":"LocalDev123!"}' \
  http://localhost:8080/api/method/login

# Use cookies for subsequent requests
curl -b cookies.txt \
  http://localhost:8080/api/resource/Item

Using Postman

1. Import ERPNext collection (create your own based on endpoints above)
2. Set base URL to http://localhost:8080
3. Configure authentication in collection settings

Using Python

import requests

# Login
session = requests.Session()
login_response = session.post(
    'http://localhost:8080/api/method/login',
    json={'usr': 'Administrator', 'pwd': 'LocalDev123!'}
)

# Get items
items = session.get('http://localhost:8080/api/resource/Item')
print(items.json())

Using Node.js/Axios (Recommended)

Simple Usage

const { ERPNextSecureClient } = require('./secure_api_client');

async function example() {
    const client = new ERPNextSecureClient('http://localhost:8080');
    
    // Authenticate with API token (uses environment variables)
    await client.authenticateWithToken();
    
    // Get customers
    const customers = await client.get('/api/resource/Customer');
    console.log(customers.data);
    
    // Create new customer
    const newCustomer = await client.post('/api/resource/Customer', {
        customer_name: 'API Test Customer',
        customer_type: 'Individual'
    });
    
    await client.logout();
}

example().catch(console.error);

Advanced Usage with Caching and Retry

const { ERPNextAdvancedSecureClient } = require('./secure_api_client');

async function advancedExample() {
    const client = new ERPNextAdvancedSecureClient('http://localhost:8080', {
        enableCache: true,        // Response caching
        retryAttempts: 3,        // Auto-retry failures  
        rateLimitPerMinute: 60   // Rate limiting
    });
    
    await client.authenticateWithToken();
    
    // First call hits API
    const customers = await client.get('/api/resource/Customer');
    
    // Second call uses cache (faster)
    const cachedCustomers = await client.get('/api/resource/Customer');
    
    await client.logout();
}

Environment Variables Setup

# Create .env file
echo 'ERPNEXT_API_KEY="your_key_here"' > .env
echo 'ERPNEXT_API_SECRET="your_secret_here"' >> .env

# Test environment variables
node test_env_vars.js

Advanced Features

1. Filters

# Filter with conditions
GET /api/resource/Item?filters=[["item_group","=","Products"]]

# Multiple filters
GET /api/resource/Item?filters=[["item_group","=","Products"],["disabled","=",0]]

2. Field Selection

# Select specific fields
GET /api/resource/Item?fields=["item_code","item_name","standard_rate"]

3. Pagination

# Limit and offset
GET /api/resource/Item?limit_start=0&limit_page_length=20

4. Sorting

# Order by field
GET /api/resource/Item?order_by=modified%20desc

WebSocket API

ERPNext also provides WebSocket connections for real-time updates:

// Connect to WebSocket
const socket = io('http://localhost:8080', {
  withCredentials: true
});

// Listen for events
socket.on('connect', () => {
  console.log('Connected to ERPNext WebSocket');
});

Rate Limiting

ERPNext implements rate limiting for API calls:

• Default: 60 requests per minute per IP
• Can be configured in site_config.json

Security Best Practices

1. Always use HTTPS in production
2. Generate and use API tokens instead of passwords
3. Implement IP whitelisting for API access
4. Regular token rotation
5. Monitor API usage logs

Debugging

Enable Debug Mode

# In the backend container
bench --site frontend set-config developer_mode 1
bench --site frontend clear-cache

View API Logs

# Check frappe logs
docker exec -it erpnext tail -f sites/frontend/logs/frappe.log

References

• Frappe REST API Documentation
• ERPNext API Reference
• Frappe Client Scripts

Need Help?

• Check the logs: docker compose logs -f backend
• Access the console: docker exec -it erpnext bench --site frontend console
• Visit the ERPNext Forum for community support