ERPNext REST API integration

The integration needs a clear owner for each kind of change: how does the external system learn that a delivered order, a payment entry or a new employee was created or updated in ERPNext? In practice, there are two routes. The first is an outbound webhook configured on document events. The second is polling the REST API for records whose modified timestamp has moved forward. Decide which route carries each event type before you build anything. Webhooks give the lowest latency but depend on how ERPNext sends and retries calls. Polling is slower but entirely under your control. Most teams make webhooks the primary channel and polling the safety net. Before you commit, confirm in your installed version that the webhook feature exists, which document events it can fire on, and whether it can sign payloads. The receiver should be designed around one rule: acknowledge quickly, then process later. When a call arrives, validate it, write the raw payload to a durable queue or table, return a success response, and let a worker handle the business logic. Do not call ERPNext, the bank or the payroll provider inside the inbound request, because slow downstream work causes timeouts, and timeouts cause resends. Validate the inbound call before parsing it. If the release signs payloads, check the signature against the raw request body using the shared secret, and reject any call that fails. Keep the secret in your secrets manager and plan how to rotate it. If the release offers no signing, restrict the endpoint at the network or reverse proxy layer and record the gap as a known risk for your security review. Assume every event can arrive more than once and that events can arrive out of sequence. A payment entry may be reported after a later update to the same record, or an older update may arrive after a newer one. Build idempotent handling: key each processed event on the document name, the event type and the modified timestamp, or on an event identifier if the payload includes one. Do not trust the order of payloads. Before acting, fetch the current document through the REST API and act on what ERPNext returns. The payload may be stale, and the document may have changed again or been cancelled since the event fired. Checking the current document status before posting downstream prevents a cancelled order from creating a shipment or a reversed payment from creating a duplicate entry. Polling covers what webhooks miss, including events lost during receiver outages and changes made while a webhook was disabled. Store a cursor for each DocType that records the last successfully processed modified timestamp. Read with a small overlap window so that records saved at the same moment as the cursor are not skipped, and rely on idempotent handling to absorb the overlap. Choose the polling interval with your team, weighing freshness against load on the ERPNext site and any API limits that apply to your hosting. Reconciliation is the periodic check that confirms both systems agree. For a chosen date range, compare record names and counts between ERPNext and the external system, list the gaps, and reprocess them through the same pipeline. Run reconciliation after any outage and on a schedule agreed with finance or HR owners. Before go-live, test the failure paths on a non-production site. Take the receiver down and confirm that events are queued and then processed. Replay the same payload twice. Send an update before its create. Change a document after its event fires and confirm the receiver reads the current state. Confirm the payload format, the retry schedule and the behavior after repeated failures with the vendor documentation for your exact ERPNext release, and write those details into your runbook. Ask any implementation partner to show the test results and the reconciliation report, not only the happy-path demonstration.

A working ERPNext integration is one that behaves correctly when the other system is slow, when a request is repeated, and when the integration user lacks a permission. Before go-live, the test plan should cover each of those cases explicitly, not only the happy path where a sales order or payment record arrives once and is accepted. Start by writing a contract test for every endpoint the integration calls or exposes, whether it is the standard Frappe REST resource routes or a whitelisted method. Each test should check the request shape, required fields, the response body and the status codes for both valid and invalid input. Confirm against the version of ERPNext you run, since field names and validation rules are the part most likely to differ between your staging and production sites.

Permission testing deserves its own pass. Run every test with the dedicated integration user and its API key or token, not with an administrator account, because administrator sessions hide missing role and user permissions. Include denied actions on purpose: an attempt to read a company the user should not see, to submit a document the role cannot submit, or to modify a DocType outside its scope. Each denial should return a clear error and leave no partial record behind. Record which roles and user permissions the integration user holds, so that a later change to them is caught by a failing test rather than discovered by a finance team member.

Idempotency and failure tests are where most integrations fail in production. Replay the same create or payment request several times and confirm that ERPNext does not produce duplicate documents, or that your middleware detects the duplicate using an external reference you store on the record. Then inject failures: force timeouts between your middleware and the ERPNext API, return errors from the bank or e-commerce side mid-batch, and cut the connection after a write has been sent but before the response is received. For each case, decide in advance whether the correct outcome is a retry, a quarantine for manual review or an alert, and verify that the system does what the design says. Partial failures in a multi-document flow, such as a sales invoice created without its payment entry, need a documented recovery path.

Reconciliation and load testing confirm the result at the business level. After a test run, compare record counts and totals between the source system and ERPNext for each object type, such as orders, invoices, payments and stock movements, and investigate every difference. For the load test, follow the Data Import guidance in the ERPNext documentation, which advises importing only a few thousand records at a time, and apply the same batching to any bulk API job. Keep test volumes within what your infrastructure and rate limits can sustain, and confirm the actual limits with your hosting provider and your own configuration rather than assuming defaults.

After go-live, the integration needs operational controls. Log every API call with a correlation identifier, the integration user, the endpoint, the outcome and the error message, and keep those logs separate from ERPNext application logs so they can be searched during an incident. Alert on retries that have exhausted their attempts, and on any record moved to a failed or quarantine state. Monitor the queue backlog on background workers, because a growing queue often signals a problem before users see one. Put credentials on a documented rotation schedule, and rotate API keys and secrets through the same change process used for other production secrets. Take a verified backup before any schema change or custom field migration, and keep endpoint documentation, field mappings and runbooks current with each release so that the next engineer can diagnose a failure without reconstructing the design from memory.