Building Custom Integrations

OpenBoxes exposes a REST API that you can use to build integrations with any external system. Whether you need to connect an ERP, a reporting tool, or an in-house application, the API gives you programmatic access to your supply chain data.

REST API Basics

The OpenBoxes REST API is available at your instance URL under the /openboxes/api path:

https://yourorg.openboxes.cloud/openboxes/api/

Authentication

API requests require authentication. Two methods are supported:

Session-based (cookie): Authenticate by posting credentials to the login endpoint:

curl -X POST https://yourorg.openboxes.cloud/openboxes/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "apiuser@yourorg.com", "password": "your-password", "location": "LOCATION_ID"}'

The response includes a JSESSIONID cookie. Include it in subsequent requests:

curl -b "JSESSIONID=abc123" \
  https://yourorg.openboxes.cloud/openboxes/api/products

API key (Dedicated+ tiers): Use a long-lived API key in the request header. Contact support to generate one for your instance.

Tip: Create a dedicated service account for API integrations rather than using a personal account. This avoids disruption when staff members leave the organization.

Available API Endpoints

The OpenBoxes API covers the core supply chain entities:

Endpoint Methods Description
/api/products GET, POST, PUT Manage product catalog
/api/locations GET, POST, PUT Warehouses, depots, facilities
/api/stockMovements GET, POST, PUT Inbound and outbound shipments
/api/purchaseOrders GET, POST, PUT Procurement orders
/api/putAways GET, POST, PUT Receiving and put-away workflows
/api/inventoryItems GET Current inventory by product and lot
/api/users GET, POST User management

For a complete reference, see the API documentation.

Webhook Events (Roadmap)

We are building support for webhook notifications that will push events to your systems in real time. Planned events include:

  • stockMovement.shipped --- Triggered when a shipment is sent
  • stockMovement.received --- Triggered when goods are received
  • purchaseOrder.approved --- Triggered when a PO is approved
  • inventory.adjusted --- Triggered when stock levels are manually adjusted
  • product.created --- Triggered when a new product is added

Note: Webhooks are on the product roadmap. In the meantime, use scheduled polling against the API to detect changes.

Middleware Options

You do not need to write code from scratch to build integrations. Several middleware platforms can orchestrate data flows between OpenBoxes and other systems:

n8n (Self-hosted or Cloud)

n8n is an open-source workflow automation tool. It supports HTTP request nodes that can call the OpenBoxes API and connect to hundreds of other services.

Example workflow: Every morning, query OpenBoxes for items below reorder point, then post a summary to a Slack channel.

Zapier

Zapier's webhook triggers and HTTP action steps can connect OpenBoxes to 5,000+ apps without writing code.

Example workflow: When a new purchase order is created in OpenBoxes (detected via polling), create a corresponding record in Google Sheets for finance review.

Custom Scripts

For straightforward integrations, a cron job running a Python or Node.js script is often the simplest approach:

import requests

# Authenticate
session = requests.Session()
session.post("https://yourorg.openboxes.cloud/openboxes/api/login", json={
    "username": "api-user@yourorg.com",
    "password": "secure-password",
    "location": "LOCATION_ID"
})

# Fetch low-stock products
response = session.get("https://yourorg.openboxes.cloud/openboxes/api/products", params={
    "max": 100
})
products = response.json().get("data", [])

Best Practices

  1. Use a service account --- Do not embed personal credentials in integration scripts. Create a dedicated user with the minimum permissions needed.

  2. Respect rate limits --- Shared tier allows 60 requests per minute; Dedicated allows 300. Add backoff logic when you receive 429 responses.

  3. Handle errors gracefully --- The API may return 500 errors during maintenance windows. Implement retry logic with exponential backoff.

  4. Log sync activity --- Keep a record of what was synced and when. This makes troubleshooting much easier when discrepancies appear.

  5. Start with read-only --- Test your integration with GET requests before enabling writes (POST/PUT). Verify the data looks correct before automating changes.

  6. Use pagination --- List endpoints return paginated results. Always check for a next page and iterate until complete.

Example Use Cases

Use Case Data Flow Approach
Reorder alerts to email OpenBoxes --> Email Cron script polls inventory levels, sends email via SMTP
ERP financial sync OpenBoxes --> ERP n8n workflow pushes PO data to ERP API on a schedule
BI dashboard OpenBoxes --> Warehouse Script extracts stock data nightly into a data warehouse
Mobile barcode scanning Mobile app --> OpenBoxes App posts scanned data to the stock movement API
Supplier portal Supplier --> OpenBoxes External form submits advance shipping notices via API

Getting Help

If you need assistance designing or building a custom integration:

  • Community forum at community.openboxes.com --- Ask questions and share solutions with other implementers.
  • Enterprise tier customers receive dedicated integration engineering support. Contact support to schedule a consultation.