Polling and Reconciliation with the BSimple API
The current BSimple Public API does not provide webhooks. An integration that needs to stay aligned with BSimple should use deliberate polling, pagination and reconciliation rather than assuming that a single request or an event callback is enough.
Poll only what the workflow needs
Choose the smallest set of resources and a polling interval that matches the business decision. A customer portal may read inventory when a customer opens a product page. An internal dashboard may refresh operational data on a schedule. Do not repeatedly download every customer, invoice or product if the user is looking at one record.
Follow pagination
List responses expose page, per_page, total and total_pages in meta. Continue until the final page:
page = 1
repeat:
response = request(resource, page=page, per_page=100)
process(response.data)
page = page + 1
until page > response.meta.total_pages
Use the documented maximum page size of 100 where appropriate, but keep memory bounded and process pages incrementally for large accounts.
Store a checkpoint
A synchronisation job should record safe progress after each successful page or resource. A checkpoint might include the resource name, page number, time of the last successful run and a checksum or count of processed rows. Store enough information to resume without silently skipping data after a process restart.
The current public reference does not define a universal updated_since parameter for every endpoint. Do not invent incremental-sync behavior; use the supported filters for each resource and confirm any date-filter requirement with BSimple before implementation.
Retry carefully
Network failures and server errors are different from validation failures. Use a bounded retry policy for transient transport or server failures, with backoff and a maximum attempt count. Do not retry 400, 401, 403, 404 or 422 indefinitely.
A timeout on a write request does not prove that the server did not accept it. Before repeating a write such as invoice creation, reconcile the likely result or require a human review path. The current public API documentation does not promise idempotency keys.
Reconcile regularly
A reconciliation job compares the local integration state with a fresh BSimple read. It should report missing records, changed totals, unexpected statuses and failed pages to an operator. A successful HTTP response is not the same as a successful business synchronisation if processing failed after the response arrived.
For invoices, preserve the BSimple invoice identifier and returned totals. For inventory, preserve the item code or identifier and the location context used by the workflow.
Design for current API boundaries
The API currently has no webhooks, bulk operations or general write access for stock adjustments, stocktakes, purchase orders and transfers. If your workflow requires those capabilities, keep the integration read-only or discuss the requirement with BSimple rather than simulating unsupported writes.
Read the full API reference and the inventory guide before finalising a sync design.
Operational checklist
- Keep the API key server-side and rotate it without code changes.
- Log safe error metadata, not secrets or full customer records.
- Monitor incomplete pages and failed reconciliation jobs.
- Alert when the last successful sync is older than the business tolerance.
- Make manual re-runs safe and visible to an operator.
- Review the API changelog before changing endpoint behavior.