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 and limit 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.