ERP integration · Pilot

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 (9 October 2026): The REST API and editor handover are deployed and available. Owners of private projects create project-scoped credentials directly in the BOM dialog. Agree a pilot scope with us for integration into your ERP. 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.

After a connection failure, retry with identical fields and files in the same browser tab. Session storage retains the pending request across reopening the dialog or reloading that tab. Only a fingerprint and retry identifier are stored, never BOMs or credentials. Select the same attachments again and enter the same external reference. After acknowledged success, publishing again creates a new package. With session storage disabled, protection lasts only until the page reloads; a new tab or changed input is a new request.

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. Use Copy credential to transfer it into your ERP server’s secure configuration, then hide it. The list distinguishes active, expired and revoked credentials.

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 production base URL is:

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

The live OpenAPI endpoint also serves the current contract. 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

Method Path Purpose
GET /releases?cursor=0&limit=25 Project releases in ascending order
GET /releases/{id} Metadata, warnings and document manifest
GET /releases/{id}/bom Frozen BOM JSON
GET /releases/{id}/documents Documents with media type, size and SHA-256
GET /releases/{id}/documents/{documentId} Authorized download
GET /openapi.json Public API description

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

Field Meaning
articleNumber Internal article number from the BOM, otherwise null
manufacturerPartNumber Manufacturer article number, separate from the internal number
lineId Identity of a BOM grouping, not an automatic ERP article identifier
quantity, unit Quantity and piece, meter, sqm, kg or liter
sourcing make, buy or unknown
material Material label from the BOM
mechanicalMaterialId, materialStatus The initial editor adapter reports null / unknown; do not infer verified physical material IDs from labels
articleRevision Unknown (null) in the initial editor adapter
sourceRevision Project-provided revision label; not proof of a server-verified CAD revision
contentHash SHA-256 of the normalized handover payload and document manifest
externalReference Optional link to your ERP quote/order

For custom publication clients: required names, lineId and entries in sourceIds/assemblies must contain non-whitespace text. Outer whitespace is trimmed; blank optional labels become null and remain identifiable as missing data. Text labels allow up to 500 characters, lineId 128 and source identifiers 250; limits apply before trimming. position is a positive integer up to 9,007,199,254,740,991. Send unknown sources as an empty array []. Line identifiers must remain unique after trimming.

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.

HTTP status Action
400 Correct fields, identifiers or pagination
401 Missing, expired or revoked credential/sign-in
403 Operation exceeds the credential’s scope
404 Project, release or document is not accessible
405 HTTP method unsupported for this endpoint
409 Idempotency conflict or active-key limit
413 Package exceeds size limits
429 Retry after the indicated delay
431 Reduce request header size
503 Temporary or integrity error; do not advance the processing cursor

Errors return { "error": { "code": "…", "message": "…", "requestId": "…" } }. The same ID appears in X-Request-Id, including rejected oversized packages. Supply the request ID to support, never your credential. Errors from an upstream hosting or network layer may differ.

Consumer example

The Python example uses only the Python 3 standard library. It downloads packages and attachments, verifies sizes and SHA-256 hashes, and advances the cursor only after a complete verified download. After an interruption, rerunning reuses already verified files and downloads corrupted files again. Temporary network failures and HTTP 429/502/503/504 receive up to four attempts, with delays of 2, 4 and 8 seconds or Retry-After (capped at 60 seconds). Authentication failures stop immediately. Response sizes and increasing cursors are checked. Run only one consumer per output directory.

# 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