SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsbimface-helper-backend

bimface-helper-backend

Coding & development

View repository

Updated 10-15 20:06

About this skill

BIMFACE Backend Service Development Skill

Usage Notes

  • Only supports BIMFACE v3 server-side RESTful API
  • You must first obtain an Access Token before you can call any interface
  • references/ Each API document below corresponds to one interface; when writing code,you must read the corresponding document
  • For asynchronous operations (conversion/integration/comparison), it is recommended to use callback to obtain results
  • Only implement the functionality explicitly requested by the user

Requirement Analysis (mandatory before coding)

After receiving the user's requirement, complete the following steps before starting to code:

  1. Capability Mapping: Compare the keywords of the user's requirement against § 模块接口指南 to find the matching module and reference document
  2. Scope Confirmation: If the requirement involves more than 2 modules or is expected to call more than 5 interfaces, list the planned interfaces to be called and let the user confirm whether the plan is correct or whether the priority needs to be adjusted
  3. Process Completeness Assessment: Confirm whether the end-to-end process of the requirement is complete (authentication → upload → conversion → query → obtain viewToken → frontend display); if anything is missing, proactively ask about the intent of the missing steps
  4. Unsupported Notification: If the requirement cannot match any reference document, immediately inform the user that "the current backend API capability scope does not support it" to avoid silently generating incorrect code or fabricating interfaces
  5. Asynchronous Operation Reminder: If the requirement involves model conversion, integration, or comparison, confirm whether the user understands that these are asynchronous operations and require polling or callbacks to obtain results

General Invocation Process

All backend calls follow the steps below. For specific interface implementation, directly open references/ the API document of the corresponding module.

1. Authentication

Refer to references/authentication.md

  • POST /oauth2/token to obtain an Access Token (valid for 7 days)
  • Add the following to the Header of all subsequent requests Authorization: Bearer {accessToken}
  • appKey / appSecret Absolutely no hardcoding, see below for detailsSecurity Specifications

2. Asynchronous Operation Callback

Refer to references/callback.md

  • The caller passes in the callback parameter, and BIMFACE sends a GET notification after completion
  • After receiving the callback, you must verify the signature signature
  • You must return HTTP 200 as an acknowledgment

3. Obtain View Token

Refer to references/view-token.md

  • GET /view/token, obtain the model access credential through fileId / integrateId / compareId , etc.
  • The View Token is valid for 12 hours and is automatically renewed on each use
  • Pass the View Token to the frontend JSSDK to load the model

4. Component DSL Query

  • Purpose: Precisely filter components through DSL syntax, supporting match / contain / in / boolAnd / boolOr
  • targetType optional file(single file) or integration(integrated model)
  • First learn DSL syntax from references/dsl-query.md , then call it in the specific API document

Module Interface Guide

File Management Service

Core capabilities: file upload/download, version management, folder structure. Supports Hub → Project → Folder → File Item → Version File five-level management.

⚠️ Key concept distinction (must understand)

  • fileItem(File Item): Represents a "file entity" and is the main object of daily operations. When uploading a file, a fileItem is created first, and subsequent uploads of new versions also belong to the same fileItem.If version management is not needed, fileItem is enough。
  • file/version(Version File): Is a specific version under a fileItem. Each fileItem has at most 100 versions, and most operations target the "current version" by default. This concept is involved only when historical versions need to be operated on (viewing old versions, downloading a specific version, deleting old versions).
  • projectId Relationship with the root folder: The project's root folder ID equals projectId. To list all folders and files under the project root directory,parentId directly pass in projectId ; no additional retrieval is needed.

API naming pattern: API paths containing /fileItems operate at the file item level, and those containing /files/{fileId} operate at the version level.

Common API quick reference:

Scenario Entry Document
Upload file (file stream) uploadFileItemUsingPOST.md
Upload file (URL method) uploadByUrlUsingPOST.md
Multipart upload (>5GB large files) initMultipartUploadUsingPOST.md
Get file item information getFileItemUsingGET.md
Download file getVersionSignedUrlUsingGET.md
Upload new version createVersionUsingPOST.md

Complete API index (48 APIs, grouped by scenario) → INDEX.md

Model Data Service

Core capabilities: component property query, floor/category tree, room space, collision detection. Prerequisite: The file must first complete conversion.

Scenario Entry Document
Query component IDs by conditions (DSL) getElementsUsingPOST_2.md
Get component details getElementUsingGET_1.md
Get component materials getElementMaterialUsingGET.md
Get floor list getFloorsUsingGET_1.md
Get component category tree getTreeUsingPOST.md
Collision detection createClashDetectiveUsingPOST.md
Model comparison results pageGetModelCompareResultUsingGET.md

Complete API index (67 APIs, grouped by 11 major scenarios) → INDEX.md

Model Conversion Derived Service

Core capabilities: file conversion (Translate), model integration (Integrate), model comparison (Compare). Prerequisite: The file must first be uploaded to BIMFACE.

Terminology note: The "model merging" commonly referred to in business scenarios corresponds to the backendmodel integration (Integrate)—merging multiple model files from the data layer into a single whole. Note that this should not be confused with the "model merging tool" in the frontend bimface-helper-v3-3d (which adjusts the display positions of multiple models); the two concepts are different.

Scenario Entry Document
Initiate conversion translateUsingPUT_1.md
Query conversion status getTranslateStatusUsingGET.md
Initiate integration integrateUsingPUT.md
Query integration status integrateUsingGET.md
Initiate comparison compareUsingPOST.md
Query comparison status queryUsingGET.md

Complete API index (17 APIs, grouped by 4 major scenarios) → INDEX.md

End-to-end process overview

认证 → 上传 → 转换 → 获取 viewToken ──→ 前端 SDK 加载模型/图纸

Modules corresponding to each stage:

  • Authentication: Refer to authentication.md
  • Upload: File Management Module
  • Conversion: Model Conversion Derivation Module
  • Query Data: Model Data Service Module
  • Obtain viewToken: Reference view-token.md, pass in according to the scenario fileId / integrateId / compareId

viewToken: The bridge between the backend and the frontend (3D/2D SDK)

The backend obtains the viewToken string via GET /view/token , which is the frontend'ssole credential：

Frontend Scenario Skill Used viewToken Parameter Source
3D Model Display and Interaction bimface-helper-v3-3d fileId(single model) / integrateId(integrated model)
2D Drawing Display and Interaction bimface-helper-v3-2d fileId(single drawing)

Call chain:后端 API → 返回 viewToken 字符串 → 前端通过 SDK 传入 viewToken → 加载模型/图纸

⚠️ The viewToken is valid for 12 hours (auto-renewed on each use); the frontend does not need to worry about the refresh logic.

Security Specifications

appKey and appSecret are the root credentials of a BIMFACE application; leaking them is equivalent to handing over all model data and file permissions under the application.The following specifications must be strictly followed:

Credential Protection

  • 🔴 Absolutely prohibited to hard-code appKey / appSecret into source code
  • 🔴 Absolutely prohibited to commit appKey / appSecret to a version control system (Git)
  • 🟢 Must inject credentials via environment variables or a key management service
  • 🟢 Must add configuration files containing sensitive information (such as .env) to .gitignore
  • 🟢 Recommended use a key management service in the production environment

Environment Variable Configuration Example

# .env（已加入 .gitignore，绝不提交）
BIMFACE_APP_KEY=your_app_key_here
BIMFACE_APP_SECRET=your_app_secret_here

Different technology stacks read environment variables in different ways (such as process.env、System.getenv()、os.environ , etc.); please read them according to the standard practice of the language used in the project.

Access Token Management

  • The Access Token is valid for 7 days; it can be globally cached and reused, with no need to re-obtain it each time
  • The Token should not be exposed to the frontend—the frontend should obtain the View Token through a backend proxy

PaaS Call Architecture and End-User Authentication

BIMFACE is a PaaS product; developers build their own applications on top of BIMFACE and then deliver them toend usersfor use.The correct call chainis as follows:

❌ 错误架构（禁止）：
   终端用户 → 前端 → BIMFACE API（直接暴露 Access Token）

✅ 正确架构（必须）：
   终端用户 → 开发者的应用 → 开发者后端认证鉴权 → 开发者后端调用 BIMFACE API（带 Access Token）→ 返回结果给终端用户

Core Principles：

  • 🔴 Absolutely prohibited to pass the Access Token directly through to the end user's frontend or client. The Token is the authentication credential of the developer's application, not the end user's credential
  • 🟢 Must have the developer's backend authenticate and authorize the end user, and only after confirming that the user has the right to operate may it call the BIMFACE interface on their behalf
  • 🟢 Must encapsulate BIMFACE API calls in the developer's backend service; end users should not directly know the BIMFACE interface addresses
  • 🟢 When the frontend needs to display a model, the backend should act as a proxy to obtain the View Token (see view-token.md) and deliver it to the frontend, rather than passing the Access Token

Foolproof Checks

  • ⚠️ Before calling any API, confirm that the Access Token has been obtained and is correctly set in the Header
  • ⚠️ fileId / integrateId Numeric parameters such as Number.MAX_SAFE_INTEGERin JS; pass them as strings
  • ⚠️ Asynchronous operations (conversion/integration/comparison) must be confirmed as having a status of in a callback or via polling success before proceeding to the next step
  • ⚠️ In DSL queries, targetType must match targetIds :file corresponds to the file ID,integration corresponds to the integration model ID
  • ⚠️ When handling callbacks, be sure to verify signatureto prevent forged callbacks
  • ⚠️ When obtaining the View Token,fileId / integrateId / compareId and other parameters are optional and only one should be filled in; the correspondence must be correct

Naming Conventions

Variable Description
accessToken Globally cached access token, automatically refreshed on a 401 response
instance axios instance, with the Authorization header uniformly injected via an interceptor

In all API documentation, {accessToken} refers to this variable.