# Integration Overview

Understand the BioTech Open Platform access boundary, integration roles, and core conventions.

## What is the BioTech Open Platform?

The BioTech Open Platform is an external API access layer. It identifies callers through application credentials, authenticates requests with Access Tokens, and grants each application access to specific endpoints.

It does not expose every backend `/api/*` route. A protected endpoint is callable only when all of the following conditions are met:

1. The code explicitly publishes it with `#[OpenApiEndpoint]`.
2. Its path is under `/openapi/*` and is not a public authentication path.
3. A platform administrator has registered and enabled it in Endpoint Management.
4. The current application has been granted access to it.

## Integration roles

| Role                   | Responsibilities                                                                                                    |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Platform administrator | Create applications, save the one-time Secret, register endpoints, configure rate limits, and grant endpoint access |
| API client             | Securely store credentials, issue and refresh tokens, call business APIs, and handle errors and rate limits         |

## Request flow

1. An administrator delivers the `app_key` and `app_secret` to the client.
2. The client obtains tokens from `POST /openapi/auth/token`.
3. The client sends an Access Token with a business request.
4. The server validates the token, publication status, application grant, and endpoint rate limit.
5. The business endpoint returns a standard JSON response and an `X-Request-Id`.

## Production request URL

The production base URL of the BioTech Open Platform is:

```text
https://backend.biotech-mkt.com
```

For example, the complete URL for issuing tokens is `https://backend.biotech-mkt.com/openapi/auth/token`. Configure the base URL once on your server:

```text
OPENAPI_BASE_URL=https://backend.biotech-mkt.com
```

Each endpoint page shows both the complete request URL and the endpoint path. Ask the platform administrator for the base URL of a non-production environment.

## Standard response envelope

Successful and failed responses use the same JSON envelope:

```json
{
  "code": 200,
  "message": "Success",
  "data": {}
}
```

- `code`: Business status code. The OpenAPI middleware maps common error codes to the same HTTP status.
- `message`: Human-readable result description.
- `data`: Endpoint data; usually an empty array for errors.

## Currently published endpoints

The current code publishes two protected endpoints:

| Method | Path                                                | Purpose                                                   |
| ------ | --------------------------------------------------- | --------------------------------------------------------- |
| `GET`  | `/openapi/profile`                                  | Validate the token and inspect the current caller context |
| `GET`  | `/openapi/v1/doudian/order/union-settlement-orders` | List Douyin Selected Alliance settlement orders           |

:::caution[Published does not mean granted]
An endpoint existing in code does not make it callable by every application. Calls are still rejected when the endpoint is unregistered, disabled, or not granted to the application.
:::