# @corsa-labs/sdk 中文文档

规范地址：https://npmcn.com/package/%40corsa-labs/sdk/

版本：5\.0\.1
npm 元数据更新时间：2026-10-20T12:52:49.159Z
中文译文更新时间：2026-11-10T19:34:53.885Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40corsa-labs/sdk
原文对照：https://npmcn.com/package/%40corsa-labs/sdk/?lang=original
项目主页：https://docs.corsa.finance/sdk/configuration

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，1490 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-05-27T10:02:57.896Z
- 最新版本发布：2026-10-20T12:52:48.956Z
- 近 30 天下载量：16594（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：96（近 12 个月 56 个）

## 中文简介

官方Node.js SDK for Corsa (cosa.finance),代理合规OS:AML交易监测,提醒,案例,KYC/KYB和风险API.

## 安装

```sh
npm install @corsa-labs/sdk
```

也可以使用：`pnpm add @corsa-labs/sdk`、`yarn add @corsa-labs/sdk`、`bun add @corsa-labs/sdk`

## README

# @corsa-labs/ sdk (英语)

[![npm version](https://badge.fury.io/js/%40corsa-labs%2Fsdk.svg)](https://badge.fury.io/js/%40corsa-labs%2Fsdk)

官方节点.js SDK [科萨](https://corsa.finance/)银行、金融机构和金融技术的代理遵守操作系统。 利用它向克萨发送客户端,账户和交易,管理警报,案件和监测规则,并处理webhooks.

联合国 [财务](https://docs.corsa.finance/)

## 目录

-   [安装](https://npmcn.com/package/%40corsa-labs/sdk/#readme-installation)
-   [API 客户端使用](https://npmcn.com/package/%40corsa-labs/sdk/#readme-api-client-usage)
    -   [配置](https://npmcn.com/package/%40corsa-labs/sdk/#readme-configuration)
    -   [可用服务](https://npmcn.com/package/%40corsa-labs/sdk/#readme-available-services)
    -   [API 请求的工作示例](https://npmcn.com/package/%40corsa-labs/sdk/#readme-working-example-for-api-requests)
-   [Webhook 处理](https://npmcn.com/package/%40corsa-labs/sdk/#readme-webhook-handling)
    -   [Webhook 页眉](https://npmcn.com/package/%40corsa-labs/sdk/#readme-webhook-headers)
    -   [正在验证签名](https://npmcn.com/package/%40corsa-labs/sdk/#readme-verifying-signatures)
    -   [事件类型](https://npmcn.com/package/%40corsa-labs/sdk/#readme-event-types)
-   [发展](https://npmcn.com/package/%40corsa-labs/sdk/#readme-development)
    -   [大楼](https://npmcn.com/package/%40corsa-labs/sdk/#readme-building)
    -   [测试](https://npmcn.com/package/%40corsa-labs/sdk/#readme-testing)
-   [捐款](https://npmcn.com/package/%40corsa-labs/sdk/#readme-contributing)
-   [许可证](https://npmcn.com/package/%40corsa-labs/sdk/#readme-license)

## 安装

您可以使用 npm 或纱线安装软件包 :

```bash
npm install @corsa-labs/sdk
# or
yarn add @corsa-labs/sdk
```

* * *

## API 客户端使用

本节涵盖如何使用SDK与遵守API端点交互.

### 配置

首先导入 `ComplianceClient` 并配置您的 API 细节 :

```typescript
import { ComplianceClient, OpenAPI } from '@corsa-labs/sdk';

// Configure API key (or other authentication methods) via Headers
// OpenAPI.TOKEN = 'YOUR_API_KEY'; // Deprecated: Use HEADERS instead

// Configure the base URL
OpenAPI.BASE = 'https://api.corsa.finance'; 

// Configure Headers for Authentication (Recommended)
OpenAPI.HEADERS = {
  "Authorization": `Bearer ${process.env.API_TOKEN}` 
};

const client = new ComplianceClient();

// Or configure directly in the constructor
const clientWithConfig = new ComplianceClient({
    BASE: "https://api.corsa.finance",
    HEADERS: {
        "Authorization": `Bearer ${process.env.API_TOKEN}`
    }
});
```

### 可用服务

SDK提供以下服务: `ComplianceClient` 实例:

-   `client.alerts`:管理合规提示.
-   `client.clients`:管理个人和公司客户.
-   `client.health`:检查API的健康状况.
-   `client.operations`:管理财务业务(存款、提款、交易).
-   `client.transactions`: 管理交易.

每个服务都暴露出对应API端点的方法. 参考类型定义(从 `index.ts` 内部 `models/` 财务报告和审定财务报表 `services/` 详细请求和响应结构目录).

### API 请求的工作示例

```ts
import { ClientRiskDto, ComplianceClient, CreateIndividualClientDto, IndividualClientCustomFieldDataDto, IndividualClientGeneralInformationDto } from "@corsa-labs/sdk";
import { v4 as uuidv4 } from 'uuid';

async function main() {
    const client = new ComplianceClient({
        BASE: "https://api.corsa.finance",
        HEADERS: {
            "Authorization": `Bearer ${process.env.API_TOKEN}` // Use Authorization header
        }
    });

    const referenceId = uuidv4();
    const { id } = await client.clients.createIndividualClient({
        referenceId,
        activityStatus: CreateIndividualClientDto.activityStatus.ACTIVE,
        accountStatus: CreateIndividualClientDto.accountStatus.APPROVED,
        currentRisk: {
            score: 75,
            level: ClientRiskDto.level.HIGH,
            reason: "Multiple high-value transactions in high-risk jurisdictions",
            calculatedAt: "2023-08-15T14:30:00Z"
        },
        tags: ["high-value", "vip-client"],
        controls: ["enhanced-due-diligence", "quarterly-review"],
        address: {
            addressLine1: "123 Main Street",
            addressLine2: "Apt 4B",
            city: "New York",
            country: "USA",
            postalCode: "10001"
        },
        adverseMedia: {
            isAdverseMedia: false
        },
        application: {
            submittedAt: "2023-08-15T10:30:00Z",
            onboardedAt: "2023-08-20T14:00:00Z",
            onboardingRisk: {
                score: 75,
                level: ClientRiskDto.level.HIGH,
                reason: "Multiple high-value transactions in high-risk jurisdictions",
                calculatedAt: "2023-08-15T14:30:00Z"
            },
            nextPeriodicReview: "2024-08-20T14:00:00Z"
        },
        riskHistory: [{
            score: 75,
            level: ClientRiskDto.level.HIGH,
            reason: "Multiple high-value transactions in high-risk jurisdictions",
            calculatedAt: "2023-08-15T14:30:00Z"
        }],
        contact: {
            emailAddress: "john.doe@example.com",
            phoneNumber: "+1-555-123-4567"
        },
        customFields: {
            additionalProp1: {
                label: "Preferred Contact Time",
                value: "Morning",
                category: IndividualClientCustomFieldDataDto.category.GENERAL
            },
            additionalProp2: {
                label: "Preferred Contact Time",
                value: "Morning",
                category: IndividualClientCustomFieldDataDto.category.GENERAL
            },
            additionalProp3: {
                label: "Preferred Contact Time",
                value: "Morning",
                category: IndividualClientCustomFieldDataDto.category.GENERAL
            }
        },
        financial: {
            annualDepositEstimate: "100000"
        },
        general: {
            firstName: "Yarin SDK",
            lastName: "Test",
            gender: IndividualClientGeneralInformationDto.gender.MALE,
            dateOfBirth: "1980-01-15",
            citizenship: "USA",
            personalId: "123-45-6789"
        },
        politicalExposure: {
            isPoliticallyExposed: false
        },
        sanctions: {
            isSanctioned: false
        },
        work: {
            occupation: "Software Engineer"
        }
    });

    console.log(id);
    await client.clients.updateIndividualClient(id, {
        activityStatus: CreateIndividualClientDto.activityStatus.NOT_ACTIVE,
    });
}

main();
```

* * *

## Webhook 处理

SDK为处理来自遵守API的webhooks提供公用事业.

### Webhook 页眉

在接收webhooks时,检查以下 HTTP 标题 :

-   `x-hub-signature-256`: HMAC SHA256 请求有效载荷的签名. 用于验证"网络呼克"的真实性. (见下文核查签字).
-   `x-hook-event`:引发webhook的事件类型(如, `individual_client.created`) (中文(简体) ).
-   `x-hook-id`:发送此请求的 Webhook 配置的独特标识符 .
-   `x-hook-delivery`: 此特定送出尝试的独特标识符 .
-   `x-request-id`: 生成 Webhook 的请求的独特标识符 .
-   `x-request-origin`: 生成 Webhook 的请求的出处( 或 `API` 或者说 `WEB`(中文(简体) )

### 正在验证签名

关键是验证进入的网络呼声的签名,以确保它们源于遵守API,不被篡改. 使用 `verifyWebhookSignature` 从 SDK 导出函数.

```typescript
import { verifyWebhookSignature } from '@corsa-labs/sdk';

async function verifyWebhookRequest(request: Request) { // Assuming a standard Request object
  const signature = request.headers.get('x-hub-signature-256'); 
  const payload = await request.text(); // Raw request body
  const secret = process.env.WEBHOOK_SECRET; // Your webhook secret

  if (!signature || !secret) {
      console.error("Missing signature or secret");
      // Return an error response (e.g., HTTP 400 Bad Request)
      return false; 
  }

  const isValid = await verifyWebhookSignature(secret, payload, signature);

  if (!isValid) {
    console.error('Invalid webhook signature');
    // Return an error response (e.g., HTTP 401 Unauthorized)
    return false;
  }

  console.log("Webhook signature verified successfully!");
  // Signature is valid, proceed with processing the webhook payload
  // const webhookEvent = JSON.parse(payload);
  // console.log('Received valid webhook:', webhookEvent.type);
  // ... process event ...
  return true;
}
```

### 事件类型

以下 Webhook 事件类型可供使用(定义于 `WebhookEventType`:

-   `individual_client.created`: 创建单个客户端时触发.
-   `individual_client.updated`: 单个客户端更新时触发.
-   `corporate_client.created`: 创建公司客户端时触发.
-   `corporate_client.updated`:公司客户端更新后触发.
-   `alert.created`: 当创建提醒时触发 .
-   `alert.updated`: 当警报更新时触发 .
-   `case.created`:当一个案件被创建时触发.
-   `case.updated`: 当案件更新时触发.

每个事件类型的有效载荷结构(`WebhookEvent`, (中文(简体) ), `EntityCreatedPayload`, (中文(简体) ), `EntityUpdatedPayload`)和 `WebhookEventType` enum 可以从 `@corsa-labs/sdk`。 。 。 .

关于如何设置网页处理器的实际例子,请参见: [Webhook 示例](https://npmcn.com/package/%40corsa-labs/sdk/docs/WEBHOOK_EXAMPLE.md)。 。 。 .

* * *

## 发展

### 大楼

为在当地建设该项目:

```bash
yarn install
yarn build
```

### 测试

使用 :

```bash
yarn test
```

* * *

## 捐款

欢迎捐款! 请遵循拖取请求的标准做法 .

## 许可证

[麻省理工学院](https://npmcn.com/package/%40corsa-labs/sdk/LICENSE)

## 常见问题

### @corsa-labs/sdk 是什么？

官方Node\.js SDK for Corsa \(cosa\.finance\),代理合规OS:AML交易监测,提醒,案例,KYC/KYB和风险API\.

### 如何安装 @corsa-labs/sdk？

在项目目录运行 npm install @corsa-labs/sdk，或使用 pnpm add / yarn add / bun add。

### @corsa-labs/sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @corsa-labs/sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @corsa-labs/sdk 可以商用吗？

@corsa-labs/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @corsa-labs/sdk 的下载量有多少？

根据 npm 官方下载统计，@corsa-labs/sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 16,594 次，日均约 553 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @corsa-labs/sdk 还在维护吗？

最新版本 5\.0\.1 发布于 2026/10/20（21 天前）；至今共发布 96 个版本，其中过去 12 个月发布了 56 个；首次发布于 2025/05/27。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。