ERPNext API, External Integration, Deployment & Troubleshooting

🌐 REST API, In Depth

Part 1's REST API Basics established the core, verified pattern: Frappe auto-generates a REST-style endpoint for every DocType at /api/resource/<DocType>, with the standard HTTP verbs mapping onto list/read, create, update, and delete:

GET    /api/resource/Customer                  # list
GET    /api/resource/Customer/CUST-00001        # read one
POST   /api/resource/Customer                   # create
PUT    /api/resource/Customer/CUST-00001        # update
DELETE /api/resource/Customer/CUST-00001        # delete

This article goes further into how that same list endpoint is actually used in practice: filtering, choosing which fields come back, and paging through large result sets. The exact query-parameter syntax below is illustrative — verify it against the API docs for your installed ERPNext/Frappe version before relying on it operationally.

# Filter a list — illustrative query-param syntax, verify per version
GET /api/resource/Customer?filters=[["customer_group","=","Retail"]]

# Choose which fields come back
GET /api/resource/Customer?fields=["name","customer_name"]

# Combine filter + field selection
GET /api/resource/Customer?filters=[["customer_group","=","Retail"]]&fields=["name","customer_name"]

# Pagination
GET /api/resource/Customer?limit_start=0&limit_page_length=20
GET /api/resource/Customer?limit_start=20&limit_page_length=20

Beyond the auto-generated per-DocType CRUD, a custom app (see Part 7's custom Frappe app development) can expose its own server-side functions as whitelisted methods — Python functions decorated to be callable over HTTP — reachable at a different URL shape:

# Calling a whitelisted custom method
POST /api/method/my_custom_app.api.approve_lab_report

# Python (requests)
import requests
headers = {"Authorization": "token API_KEY:API_SECRET"}
r = requests.post(
    "https://site.example.com/api/method/my_custom_app.api.approve_lab_report",
    headers=headers,
    json={"lab_report": "LR-2026-00042"}
)

This is the mechanism that lets a custom app do more than expose its DocTypes as data — it can expose actual business operations (an approval, a calculation, a multi-document transaction) as a single callable endpoint, instead of forcing an external system to reconstruct that logic itself via multiple raw CRUD calls.

🏗️ Connecting an External Application

Part 1's Internal vs External Connections diagram sketched the outside world touching ERPNext through the REST API. Here's the concrete shape that takes in a typical setup — a separate customer-facing application (e.g. Next.js frontend + Django backend) sitting in front of ERPNext rather than inside it:

The pattern this enables: the external Django app owns its own business logic and authentication for its own end users — signup, sessions, app-specific preferences — while treating ERPNext as the system of record for the business entities ERPNext already models well: Customers, Items, Sales Orders, Invoices, and Payments. The two systems stay in sync through API calls or webhooks, not a shared database.

🔁 Common Sync Patterns

In this two-system architecture, different entities tend to flow in different directions depending on which system actually owns that data:

🔒 Securing the API in Production

Part 1's Security, Backup & Troubleshooting section covered the basics — HTTPS, scoped keys, rotation. In a real external integration, each of those needs to be treated as an operational discipline, not a one-time setup step:

• HTTPS only. Never send API keys, secrets, or payloads over plain HTTP — a key sent in cleartext is a key that has already leaked.
• Dedicated integration user. Create a separate User specifically for the integration and scope its API key to only the roles it actually needs — see Part 2's Role Permission Manager — rather than issuing a key against a System Manager account. If the key leaks, the blast radius is whatever that scoped role can do, not the whole site.
• Rotate and revoke through the User record. If a key is ever exposed — committed to a repo, logged accidentally, shared in a support ticket — regenerate it immediately from that User's API Access section; the old key stops working the moment a new one is generated.
• Rate-limit and monitor. Watch for unusual API call volume from a given key — a sudden spike is either a bug in the integration or a sign the key is being used somewhere it shouldn't be.
• Treat inbound webhook payloads as untrusted input. A webhook receiver on the external app's side should validate and sanitize whatever it receives before writing it back into ERPNext — never assume the payload is well-formed or that it actually originated from ERPNext without verifying it.

It's worth restating the layered permission chain from Part 1's Users, Roles & Permission Flow, because it applies identically to API traffic:

An API key does not bypass any of this — a request authenticated with an API key runs through the exact same Role/User/Document permission chain a human clicking through the Desk UI would go through. If the integration user's role can't submit a Sales Invoice, neither can a script calling that user's API key.

💾 Backup & Recovery Strategy

Part 1 sketched backup as a single step in its security diagram. In production, it's really a four-stage discipline, and skipping any stage quietly turns "we have backups" into a false sense of safety:

For convenience, the relevant command from Part 1's Developer Command Cheat Sheet:

bench --site SITE backup                # database backup (+ optional files, version-dependent)
# flags such as --with-files exist to include attachments in the same run —
# verify the exact flag names against your installed bench version

🧯 Troubleshooting Reference, Expanded

Part 1's troubleshooting table covered the site-down basics: site doesn't open, MariaDB errors, Redis errors, scheduled jobs not firing, migration failure, build failure, and Nginx 502s. The symptoms below are ones that show up specifically once a site has external integrations, custom apps, and a real deployment pipeline running against it:

✅ Production Readiness Checklist

Extending Part 1's Production Deployment Architecture into a concrete pre-launch checklist:

🗺️ What's Next

This article is Part 8 of the 9-part ERPNext series, going deep on the API integration and production-operations ground that Part 1 only sketched — see its REST API Basics and Production Deployment Architecture sections for where this all started. It also builds on Part 5's external connections coverage of how Accounting and Stock data reaches the outside world, and on Part 7's custom app development practices for exposing whitelisted methods and managing deployments.

Part 9 — the capstone — is next: the full Laboratory Management custom-module project, built end to end. Its Lab Report → Sales Invoice automation, and any patient/customer-facing portal exposure it adds, are built using exactly the API design, security hardening, and deployment practices covered in this article — modules, database design, customization, and custom app development from Parts 3 through 7 all converge there into one working project.