ERP handover REST API

The handover API exposes released bills of materials and related documents as immutable packages. Your ERP integrator can retrieve them, map articles and import them into your business workflow. Once released, packages can be read without an open confBuild editor.

Status: Initial implementation for pilot use. Arrange production access and availability with confBuild. This is a foundation for custom integration; it does not imply a ready-made SAP, Microsoft Dynamics or Odoo connector.

Download OpenAPI 3.1 · Download Python example

Release a package

1. Open your own saved project in the confBuild editor, then open its Bill of materials.
2. Check the positions and active filters. ERP handover uses exactly the displayed positions, including search and hidden-row filters. This can be a partial assembly.
3. Optionally enter an external reference, such as an ERP quote number. JSON and CSV are generated automatically from the submitted BOM.
4. Optionally attach PDF, STEP or DXF files and confirm that they belong to this snapshot. Their bytes are stored unchanged; the API does not automatically verify CAD/drawing revision matching.
5. Confirm and select Release package. You receive a release ID, sequence number and data coverage warnings.

Releases never change. Model changes require reopening the current BOM and creating a new release. “Released” records your handover decision, not automatic engineering certification.

Create a credential

Use API credentials for this project in the same dialog. A new secret is shown once; only its hash is stored on the server. Copy it into your ERP server’s secure configuration.

The credential can only read releases of this one project. It cannot edit models, publish packages or manage credentials. UI-created keys expire after 90 days; the management API permits 1–365 days. Each project allows 20 active keys. Revoke a key in the dialog to stop further access. Copies already downloaded remain with their recipients.

This first version supports the owner of a privately stored project. Shared company projects/public templates must first be copied into your own project collection. Deleting the source project or losing ownership prevents further API reads.

Base URL and first request

The Hosting address after production deployment is:

https://app.confbuild.com/api/v1

confBuild may supply a separate pilot address. All private endpoints require Authorization: Bearer …. Keep credentials on your server, never in public JavaScript or URLs.

# Set CONFBUILD_API_KEY securely in your environment first.
curl --fail-with-body \
  -H "Authorization: Bearer $CONFBUILD_API_KEY" \
  'https://app.confbuild.com/api/v1/releases?limit=25'

The response contains items and nextCursor. Each release has an ascending sequence. Persist the highest fully processed sequence and pass it as cursor for subsequent polls. nextCursor: null only means there is no further page right now; retain your last processed sequence.

curl --fail-with-body \
  -H "Authorization: Bearer $CONFBUILD_API_KEY" \
  "https://app.confbuild.com/api/v1/releases/$RELEASE_ID/bom"

Endpoints

Management endpoints POST /releases, GET/POST /keys and DELETE /keys/{id} require a current Firebase ID token from the project owner, not a read key. Pass projectId as a query parameter for GET/DELETE or in the JSON body for POST. The confBuild dialog handles this. OpenAPI provides complete request schemas for custom management clients.

POST /releases requires an Idempotency-Key of 16–128 letters, digits, hyphens or underscores. Repeating the same content/key returns the same release (200); a new release returns 201. Reusing a key with different content returns 409. After a timeout retry the same body and key.

Data contract

JSON is the authoritative structured format. CSV is a flat subset with spreadsheet formula prefixes escaped. Attachments carry provenance: publisher-attested; generated BOM documents use generated-from-bom. Verify downloaded sizes and SHA-256 hashes against the manifest.

This version excludes prices, stock, routings and full model parameters. Missing article, material or source data remain null or carry warnings. ERP article mapping and engineering-to-manufacturing BOM conversion belong to the customer-specific integration.

Limits and errors

Up to 2,000 positions and 600 KB normalized metadata/BOM per release. Up to eight optional attachments, 3 MiB each and 6 MiB combined; request size at most 9 MiB. Filenames allow ASCII letters, digits, spaces, dots, hyphens and underscores, with PDF/STEP/STP/DXF extensions.

120 authenticated requests per key or owner per minute; key creation additionally allows five and publishing attempts ten per owner per minute. 429 includes Retry-After: 60. Additional ingress protection may apply earlier.

Errors return { "error": { "code": "…", "message": "…", "requestId": "…" } }. Supply the request ID to support, never your credential.

Consumer example

The Python example uses only the Python 3 standard library. It downloads packages and attachments, verifies hashes and advances the cursor only after successful processing.

# Provide CONFBUILD_API_KEY securely first.
python3 confbuild-handover-pull.py

Optional CONFBUILD_API_BASE and CONFBUILD_OUTPUT_DIR select the API address and output directory. After credential rotation, use a new output directory or deliberately reset the checkpoint. The example does not write to an ERP; add your customer-specific import after downloading.

Discuss an ERP pilot