DIY Developer Guide: Building Custom Integrations for Brightpearl
Overview
This DIY Developer Guide for Brightpearl outlines a clear, step-by-step approach to building secure and efficient custom integrations. Brightpearl is a retail operations platform with a robust REST API, designed for seamless connectivity with eCommerce stores, marketplaces, accounting software, logistics providers, and CRM systems.
Whether you’re syncing orders, automating inventory updates, or integrating accounting workflows, Brightpearl integrations can greatly enhance operational efficiency.
Prerequisites for Brightpearl Integrations
- Brightpearl Developer Account and API access credentials
- Account ID, App Ref, App Token
- Familiarity with:
- RESTful APIs
- JSON structures
- OAuth 2.0 or API Key Authentication
- Tools: Postman, Brightpearl API Console, Node.js/Python SDKs, custom HTTP clients
Step 1: Authentication for Brightpearl Integrations
Brightpearl uses API Key authentication with an App Ref and App Token.
Authentication Request Example:
POST https://ws-use.brightpearl.com/{account}/authenticate
Content-Type: application/json
{
"apiAccountCredentials": {
"applicationId": "AppRef",
"applicationSecret": "AppToken"
}
}
The response provides an Authorization Token for API requests.
Step 2: Endpoint Discovery and Data Mapping for Brightpearl Integrations
Common API Resources:
- Sales Orders
- Products and Inventory
- Customers and Suppliers
- Accounting Journals
- Shipments
Process:
- Study the Brightpearl API documentation.
- Map fields accurately between external systems and Brightpearl.
Key considerations:
- Mandatory fields
- Reference fields (e.g., linking shipments to orders)
- Data formatting (dates, currencies)
Step 3: Building Integration Flows for Brightpearl
Integration Patterns:
- Inbound (to Brightpearl): POST and PUT operations
- Outbound (from Brightpearl): GET operations
Example: Creating a Sales Order:
POST /public-api/{account}/order-service/order
{
"customer": {"contactId": 1234},
"orderTypeCode": "SO",
"orderRows": [
{
"productId": 5678,
"quantity": 2,
"price": 100.00
}
]
}
Example: Retrieving Products:
GET /public-api/{account}/product-service/product-search
Step 4: Error Handling and Pagination for Brightpearl Integrations
Error Handling:
- Capture HTTP codes and Brightpearl-specific error details.
- Use retries and exponential backoff for recoverable errors.
Pagination:
- Use
offset
andlimit
query parameters when retrieving large datasets.
Example:
GET /public-api/{account}/order-service/order-search?offset=50&limit=50
Step 5: Testing and Validation for Brightpearl Integrations
- Test authentication and API calls using Postman or the Brightpearl API Console.
- Validate field mappings, record creation, and updates.
- Perform load testing to confirm scalability.
Step 6: Deployment and Security of Brightpearl Integrations
- Deploy integrations securely (Docker, AWS, Azure).
- Store credentials securely using secret managers.
- Always use HTTPS/TLS for data transfer.
- Enable full logging and error monitoring.
Step 7: Maintenance and Monitoring for Brightpearl Integrations
- Monitor for Brightpearl API version updates and deprecations.
- Set up real-time alerting for system errors or authentication failures.
- Track API usage metrics and error rates.
Optional Enhancements for Brightpearl Integrations
- Build webhook listeners for near real-time updates.
- Leverage middleware tools like Zapier or Workato.
- Create admin dashboards for integration health monitoring.
- Implement audit logs for security tracking.
Summary
Building robust Brightpearl integrations enables businesses to automate retail operations and scale efficiently. This DIY Developer Guide for Brightpearl provides the foundational steps needed to develop secure, reliable, and scalable integrations.
Apiworx is dedicated to helping eCommerce businesses scale faster than ever possible before by streamlining and managing complex OmniChannel data flows, we save our customers time and money, allowing them to scale their businesses faster and more effectively. We focus on automation and integration of often-overlooked back-office systems and processes such as order and inventory management. We work with major partners in the industry and build best-in-breed automation and integration solutions.