Integration guide¶
Public · Status: ⬜ draft
1. Purpose¶
Get BulkScanPro measurements into your systems with minimal effort. There are four surfaces — use whichever fits your stack; you can combine them.
2. Choose a surface¶
| Surface | Latency | Shape | Typical consumer | Status |
|---|---|---|---|---|
| REST API | on-demand / near-real-time | JSON | apps, dashboards, webhooks | 🔄 |
| Modbus TCP | live (at the edge) | registers | SCADA / PLC | ⬜ planned |
| S3 export | per-convoy (push) | files (MCAP/Parquet/PNG/PDF) | data lake, batch ETL, archive | ✅ |
| Database | historical | tables | BI / SQL analytics | ⬜ design |
3. What every measurement carries¶
Regardless of surface, a measurement gives you, per car: volume (m³), length (m), position in the convoy, timestamp, direction, confidence, and (if tagged) the RFID equipment id. The net loaded volume is the loaded−empty delta across passes. See the data model.
4. Authentication¶
All cloud surfaces use a single, simple scheme: a per-organization API key. Send it as
X-API-KEY: bsp_live_xxx (or Authorization: Bearer bsp_live_xxx) on every request to the cloud base
URL https://bsp.ita.builders/api/v1. The key both authenticates and scopes results to your
organization — you never pass an org id and never see another tenant's data. The same key gates
presigned S3 access (REST returns the URLs) and is the credential used to provision DB access.
The Modbus surface is local to the edge node and uses network-level access, not the API key. See
Getting started. 🔄 Proposed contract — finalized as the public API ships.