BrightCom API Reference

Overview

The BrightCom Gateway is a queue-based store-and-forward integration hub, not a direct CRUD API. Business Central pushes messages into a resource’s queue with POST; your system pulls the next batch out with GET, using FIFO ordering and an acknowledge-token handshake.

Base URLs

QA:         https://qa.onbrightcom.com/gateway/v1
Production: https://onbrightcom.com/gateway/v1

How the queue works

GET a batch (default 100 entries unless you pass count). The response is wrapped in an envelope: { "count": ..., "acknowledgeToken": "...", "nextLink": "...", "data": [...] }. nextLink is only present when more entries remain beyond this batch — treat it as your pagination signal, not a field to expect on every response.
Process the batch.
Pass acknowledgeToken back as the acknowledge query parameter on your next GET. This closes out the batch you just processed and advances the queue — if you don’t acknowledge, the same entries stay open and you’ll receive them again.

Queues are configured per target: which source’s updates go to which queue is set up in the Gateway configuration, and multiple sources may share a common queue.

Consumers must be idempotent

When an already-delivered entry needs correcting, the Gateway doesn’t edit it in place — it appends a new copy to the end of the queue instead, to avoid disturbing the acknowledge watermark. That means the same logical record can arrive more than once. Match incoming entries on your own key (e.g. externalId) and treat a repeat as an update, not a new record — don’t assume delivery is exactly-once.

Authentication

Every endpoint requires a Bearer API key — the documentation UI itself is publicly viewable, but the endpoints behind it are not. Contact BrightCom Solutions to get a key issued; the exact provisioning process isn’t part of this reference yet.

This reference covers six resources:

Item

Item, variant, and parent-grouping messages — non-variant items, BC-level variants, and virtual parent groupings.

Products & variants

Customer

Customer master data, addresses, and contacts.

Customers & contacts

Price

Price list entries per item/variant, with currency, VAT, and validity dates.

Price entries

Warehouse

Stock levels and movements per warehouse — absolute quantities, deltas, and planning/history data.

Stock & inventory

Order

Sales orders, closed invoices, and credit memos, with lines, buyer/payer/ship-to, payments, and delivery.

Orders, invoices & credit memos

Shipment

Full or partial shipment notifications, with tracking and line-level handled/closed quantities.

Shipment notifications

Extended Info

The typed, config-driven mechanism used to extend every message beyond its base fields.

Flexible attributes

What’s not covered yet

Exact auth setup details — every endpoint requires a Bearer API key (see Authentication below), but the specific process for obtaining a key and the tenant-resolution details aren’t part of this reference yet — ask BrightCom Solutions.
Item cross-references, structure (BOM), suppliers, and units of measure — these exist on the Item message but are only listed by name here, not expanded field-by-field yet.
Operational endpoints (dead-letter queue, configuration, mapping, admin/stats/tooling) — internal to BrightCom Solutions, not part of the integrator-facing surface documented here.
Interactive try-it-out reference — this version is documentation to read, not a live console.

Two other integration paths exist and are out of scope here

Business Central also exposes its own direct REST/OData API pages (/api/brightcom/brccore/..., /api/brightcom/brcconnect/...) for automation directly against BC. Those are a different integration path from the Gateway documented here and aren’t covered on this page.

Other product API references

These aren’t the Gateway — they’re the separate integration/extension references for other BrightCom Business Central apps, kept here for a single API-docs entry point.