# @cycomdatasystems/mackinac-sdk 中文文档

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

版本：13\.16\.0
npm 元数据更新时间：2026-11-06T19:30:37.955Z
中文译文更新时间：2026-11-11T07:12:48.218Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40cycomdatasystems/mackinac-sdk
原文对照：https://npmcn.com/package/%40cycomdatasystems/mackinac-sdk/?lang=original
项目主页：https://github.com/CycomDataSystems/mackinac-sdk#readme
源码仓库：https://github.com/CycomDataSystems/mackinac-sdk

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

- 包体积（解压后）：4 MB，1336 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2026-04-22T14:38:01.582Z
- 最新版本发布：2026-11-06T19:30:37.731Z
- 近 30 天下载量：3201（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：38（近 12 个月 38 个）

## 中文简介

Mackinac API 的共享TypeScript客户端.

## 安装

```sh
npm install @cycomdatasystems/mackinac-sdk
```

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

## README

# 麦克纳克SDK

Mackinac API 的共享TypeScript客户端.  
由Mackinac OpenAPI规格生成,这个SDK为网络和移动应用程序提供了强烈的打字模型和统一的取取取客户端. 它确保API使用的一致性,减少重复,并使所有消费者都与最新的API合同保持一致.

* * *

## 安装

```bash
npm install @cycomdatasystems/mackinac-sdk
# or
yarn add @cycomdatasystems/mackinac-sdk
# or
pnpm add @cycomdatasystems/mackinac-sdk
```

* * *

## 使用量

### 应用程序启动时配置 SDK

```ts
import { configureMackinac } from '@cycomdatasystems/mackinac-sdk';

configureMackinac({
  baseUrl: process.env.MACKINAC_API_URL!,
});
```

对于SDK呼叫中需要附加授权信头或其他特定请求信头的应用程序,您可以提供 `headersProvider` 函数 :

```ts
import { configureMackinac } from '@cycomdatasystems/mackinac-sdk';

configureMackinac({
  baseUrl: process.env.MACKINAC_API_URL!,
  headersProvider: () => ({
    'Authorization': `Bearer ${getToken()}`,
  }),
});
```

这个 `headersProvider` 也可以是async,支持从async源获取符:

```ts
configureMackinac({
  baseUrl: process.env.MACKINAC_API_URL!,
  headersProvider: async () => {
    const token = await getAccessToken();
    return {
      'Authorization': `Bearer ${token}`,
    };
  },
});
```

### 认证

#### 使用信头提供者( 建议)

SDK提供了一个 `headersProvider` 函数用于请求范围认证。 对于需要附加的应用程序,建议采用这种方法 `Authorization` 每个SDK呼叫的发信头或其他动态发信头.

**福利:**

-   所有SDK电话的集中头管理
-   支持 async 令牌检索
-   自动与每个呼叫标题合并
-   按请求援引防止象征性地泄漏请求

**示例: Next.js 带 Auth0 的路由处理器**

```ts
// app/api/finance/payments/route.ts
import { getSession } from '@auth0/nextjs-auth0';
import { configureMackinac } from '@cycomdatasystems/mackinac-sdk';
import { getApiV1MattersMatterIdFinancePayments } from '@cycomdatasystems/mackinac-sdk';

export async function GET(request: Request) {
  const session = await getSession();
  
  // Configure SDK with token provider for this request
  configureMackinac({
    baseUrl: process.env.MACKINAC_API_URL!,
    headersProvider: () => ({
      'Authorization': `Bearer ${session.accessToken}`,
    }),
  });
  
  // All SDK calls now include Authorization header
  const payments = await getApiV1MattersMatterIdFinancePayments(123);
  
  return Response.json(payments);
}
```

或者,如果您需要同步符号检索:

```ts
// src/server/mackinac/config.ts
import { configureMackinac } from '@cycomdatasystems/mackinac-sdk';

export function configureMackinacForRequest(getToken: () => Promise<string>) {
  configureMackinac({
    baseUrl: process.env.MACKINAC_API_URL!,
    headersProvider: async () => {
      const token = await getToken();
      return {
        'Authorization': `Bearer ${token}`,
      };
    },
  });
}
```

```ts
// app/api/finance/payments/route.ts
import { configureMackinacForRequest } from '@/server/mackinac/config';
import { getApiV1MattersMatterIdFinancePayments } from '@cycomdatasystems/mackinac-sdk';

export async function GET(request: Request) {
  // Configure SDK with async token provider for this request
  configureMackinacForRequest(async () => {
    // Simulate async token retrieval
    return await fetchTokenFromAuthService();
  });
  
  // All SDK calls now include Authorization header
  const payments = await getApiV1MattersMatterIdFinancePayments(123);
  
  return Response.json(payments);
}
```

**示例:同步信头提供者**

```ts
import { configureMackinac } from '@cycomdatasystems/mackinac-sdk';

configureMackinac({
  baseUrl: process.env.MACKINAC_API_URL!,
  headersProvider: () => ({
    'Authorization': `Bearer ${process.env.API_TOKEN}`,
  }),
});
```

**标题合并优先级**

标题按以下顺序合并(后被更早地推翻) :

1.  默认信头( E)`Content-Type: application/json`(中文(简体) )
2.  信头来自 `headersProvider()`
3.  逐个呼叫头传递给单个端点函数

```ts
// Example of per-call override
const payments = await getApiV1MattersMatterIdFinancePayments(
  123,
  {
    headers: {
      'X-Request-Id': 'custom-id', // Merges with provider headers
      'Authorization': 'Bearer override-token', // Overrides provider's Authorization
    }
  }
);
```

#### 基于中件的认证( Legacy)

这个SDK **不处理内部认证**。 。 。 .

如果您的应用程序使用Auth0(或另一个 IdP),并且通过中间软件或框架级取取取截取器向外请求添加访问符, **您不应该直接向 SDK 提供符号**。 。 。 .

SDK只是打电话 `fetch()`中软件或运行时环境 `Authorization` 标题将继续按预期工作.

* * *

## 示例

```ts
import { getApiV1MattersMyOpen } from '@cycomdatasystems/mackinac-sdk';

// Fetch "My Open Matters" for the current user
const matters = await getApiV1MattersMyOpen({ moduleCode: 'Claims' });

console.log('Open matters:', matters);
```

所有生成的函数都会直接返回响应机构(不是被包裹的对象),遵循所配置的 Orval 输出.

### WRP Matter 自动收件人(自13.9.0起)

NG 用户管理员可以为创建的事项配置可选自动指定人 由现任房客的WRP公司负责。 这些终点需要 `users:update` 还有一个 已接受, 启用了 NG 调用器, 其用户账户提供链接的 StaffId . 配置 SDK 和认证信头 ; 使用应用程序当前租户认证的上下文. URL 或请求中没有租户ID, SDK 不选择 与经认证的请求无关的租户. Mackinac解决了NG的认证 `org_id` 给房客的支票 名称空格 Entra `tid` 对抗那个房客的图案 不发送 `X-Org-Id` 或者另一个习惯租户头。 WRP现有的M2M流量解决了房客来自 `azp`;这些SDK的电话不会改变流. NG 呼叫器链接使用已注册的用户账户并签名 Entra `oid`,而不是一个 表示 StaffId 或 Auth0 主题 。 合格用户和有联系的工作人员必须共享 已解决整数 `STAFF.ORG_ID` 这不是房客的钥匙.

```ts
import {
  getWrpMatterAutoAssignee,
  setWrpMatterAutoAssignee,
  getEligibleWrpMatterAutoAssignees,
} from '@cycomdatasystems/mackinac-sdk';

const current = await getWrpMatterAutoAssignee();
const choices = await getEligibleWrpMatterAutoAssignees();
// After the administrator selects a choice, save its userId, not its staffId:
const saved = await setWrpMatterAutoAssignee({ userId: 123 });
const disabled = await setWrpMatterAutoAssignee({ userId: null });
```

-   `getWrpMatterAutoAssignee(options?: RequestInit)` 财务报告和审定财务报表 `setWrpMatterAutoAssignee(body: SetWrpMatterAutoAssigneeDto, options?: RequestInit)` 返回时 `Promise<WrpMatterAutoAssigneeDto>`数字 : `{ userId: number | null, staffId: string | null }`。 。 。 . 两个字段在禁用时均为无效. PUT机构是 `{ userId: number | null }`· ; 明确发送无效以禁用,而不是省略的字段.
-   `getEligibleWrpMatterAutoAssignees(options?: RequestInit)` 返回时 `Promise<WrpMatterAutoAssigneeUserDto[]>`: 光线阵列 `{ userId: number, staffId: string, displayName: string }`,或 `[]` 当没有用户时 符合条件,由用户ID订购,并仅限于呼叫者组织. 也不要求这样 `users:read` 或 Auth0 访问. `displayName` 来了 从被裁员的工作人员。 姓名, 归工作人员 Id;没有光标或包装.
-   Mackinac 验证目标是一个活动且未锁定的带有约束的 NG 用户 将现租户中的在职工作人员联系在一起。 工作人员必须 非空白,最多七个字符;不需要AS/模块旗. 无效的选中项 `Mackinac 400:` 接下来是 验证 问题详情 `errors.userId`认证、授权、, 缺少组织上下文,并拒绝存储失败 `Mackinac 401:`, (中文(简体) ), `Mackinac 403:`, (中文(简体) ), `Mackinac 503:`,以及 `Mackinac 500:` 分别使用 SDK已经存在 `Error` 行为而不是输入出错返回值. JWT挑战和现有政策否定可能没有反应机构; 租户中间软件也可以在这些终点执行前拒绝请求.
-   被选中的用户 StaffId 只能成为 WRP 的初级工作人员 `assignment-matter` 财务报告和审定财务报表 `create-as-matter` 行动。 无 WRP 提交有效载荷 需要改变。 环境为租户范围,不由租户分担 不是每个用户或每个表格.

### 附件文件夹(自13.1.5.0起)

一个事项的附件文件夹在 SQL 中 `MATTERFOLDER`),而不是作为SharePoint嵌入路径. `listMatterAttachments` 是附件标签读取的单页: 它返回所选附件加上整个事项的平面文件夹列表, 因此表格和树视图是从一个响应中构建的 。 仅列出或计算SPE后置行(有驱动项).

```ts
import {
  listMatterAttachments, createAttachmentFolder, patchAttachmentFolder,
  deleteAttachmentFolder, moveMatterAttachments, patchMatterAttachment,
} from '@cycomdatasystems/mackinac-sdk';

// view: 'all' (default) | 'unfiled' | 'recent'; folderId cannot be combined with a view other than 'all'.
const { items, folders, unfiledCount, totalCount } = await listMatterAttachments(matterId, { folderId: 42, q: 'brief' });

const folder = await createAttachmentFolder(matterId, { name: 'Pleadings', parentId: null });
await patchAttachmentFolder(folder.id, [{ op: 'replace', path: '/name', value: 'Pleadings 2026' }]);
await moveMatterAttachments(matterId, { attachmentIds: [101, 102], folderIds: [], targetFolderId: folder.id });
await patchMatterAttachment(matterId, 101, [{ op: 'replace', path: '/category', value: 'PLD' }], { moveToCategoryFolder: true });
const { deletedFolderCount, movedAttachmentCount } = await deleteAttachmentFolder(folder.id); // contents move to Unfiled
```

-   `listAttachmentFolders(matterId)` 财务报告和审定财务报表 `getAttachmentFolder(folderId)` 返回时 `AttachmentFolderDto`s. 列表为平面:从 `parentId` (null = 一个根文件夹). `totalAttachmentCount` 包括子文件夹; `categoryCode` 设置在类文件夹上.
-   `patchAttachmentFolder` 财务报告和审定财务报表 `patchMatterAttachment` sDK发送的 RFC 6902 JSON 补丁阵列 `application/json-patch+json`,并决心 `undefined` (204) (英语). 在文件夹上, `replace /name` 重命名和 `replace /parentId` 移动( 无效或 `remove` =物质根). 在一个附件, `replace` 或者说 `remove` 适用于 `/category` (DOCCAT代码)和 `/description`。 。 。 .
-   `moveMatterAttachments` 全部或无(最多为1000 ids). `targetFolderId: null` 将附件移动到未归档中,并将文件夹移动到物质根中.
-   文件夹名称在兄弟姐妹之间被剪切并独一无二,对大小写不敏感;冲突与 `Mackinac 409:` (单位:千美元)`attachment-folder-name-conflict`) (中文(简体) ). 深于6级,或将文件夹移入自身或后人,拒绝 `Mackinac 400:`。 。 。 .
-   文档登记`postApiV1MattersMatterIdDocumentsItemsItemIdRegister`接受 `folderId`,或 `fileInCategoryFolder: true` 带有 `category` (该类的根文件夹, 如果缺少则创建) 。 上传到容器根; `DocumentRegistrationDto.folderId` 报告文件存档的地方.

### 计费(自13.5.0起)

计费参考数据终点命名 `*Billing*`数字 : `listBillingPeriods`, (中文(简体) ), `getBillingPeriod`, (中文(简体) ), `createBillingPeriod`, (中文(简体) ), `patchBillingPeriod`, (中文(简体) ), `deleteBillingPeriod`,同样的五项行动,用于 `...BillingRevenueCode(s)`,以及 `getBillingProfile` 编号 : `patchBillingProfile`编辑 `PATCH` 操作需要一个 RFC 6902 JSON 补丁阵列, SDK 作为 `application/json-patch+json`数字 :

```ts
import { listBillingPeriods, patchBillingProfile } from '@cycomdatasystems/mackinac-sdk';

const periods = await listBillingPeriods({ page: 1, pageSize: 50, sortBy: 'beginDate', sortDirection: 'desc' });

const profile = await patchBillingProfile([
  { op: 'replace', path: '/billTo', value: 'Department' }, // BillingBillTo: 'Account' | 'Department'
  { op: 'replace', path: '/billGeneralExpenses', value: true },
]);
```

`deleteBillingPeriod` 财务报告和审定财务报表 `deleteBillingRevenueCode` 拒绝 `Error` 谁的消息开始 `Mackinac 409:` 当发票或收据仍然提及该物品时(详情如下)。 收入代码为代码表行(`code`, (中文(简体) ), `description`, (中文(简体) ), `isDefault`, (中文(简体) ), `isInactive`),而不是收费类.

#### 发票、收据和应收款(自13.7.0起)

读取模式是 `listBillingInvoices`, (中文(简体) ), `getBillingInvoice`, (中文(简体) ), `listBillingInvoiceTransactions`, (中文(简体) ), `listBillingReceipts` 财务报告和审定财务报表 `listBillingReceivables`。每次搜索都使用一个参数对象,阵列参数作为重复键发送:

```ts
import {
  listBillingInvoices, getBillingInvoice, listBillingInvoiceTransactions,
  listBillingReceipts, listBillingReceivables,
} from '@cycomdatasystems/mackinac-sdk';

const page = await listBillingInvoices({
  statuses: ['Pending', 'Billed'],                 // BillingInvoiceStatus; any of them
  accountIds: [101], departmentIds: [202],          // unioned
  billedDateFrom: '2026-01-01', billedDateTo: '2026-01-31', // inclusive whole days
  page: 1, pageSize: 50, sortBy: 'invoiceDate', sortDirection: 'desc',
});
const invoice = await getBillingInvoice(page.hits[0].id);
const lines = await listBillingInvoiceTransactions(invoice.id, { pageSize: 100 });
const receipts = await listBillingReceipts({ revenueCodes: ['FEE'], checkNumber: '10' });
const outstanding = await listBillingReceivables({ sortBy: 'balance', sortDirection: 'desc' });
```

-   `status` 实值 `Pending`, (中文(简体) ), `Billed`, (中文(简体) ), `Paid`, (中文(简体) ), `Cancelled`,或 `Unknown`。 。 。 . `Unknown` 仅出现在回复中: 它覆盖了遗留值或 NULL 值, 作为过滤器传递给 `Mackinac 400:`。 。 。 .
-   `transactionType` 是一个 `BillingTransactionType`。 。 。 .
-   `invoiceNumber`, (中文(简体) ), `fileNumber` 财务报告和审定财务报表 `checkNumber` 是字面前缀匹配.
-   1753-01-01年之前的日期,或 `...To` 这早于它的 `...From`,为 `Mackinac 400:`。 。 。 .
-   `getBillingInvoice` 财务报告和审定财务报表 `listBillingInvoiceTransactions` 拒绝 `Mackinac 404:` 您可能看不到一张发票。 他们从不返回空页.
-   `InvoiceDto` 携带总数的组成部分: `amount = attorneyAmount + staffAmount + expenseAmount + creditCardExpenseAmount + settlementAmount + adjustmentAmount - collectionAmount`。 。 。 .
-   应收款为账单,未付发票,金额为正数。 每个都有 `balance`。 。 。 .

#### 计费运行(自13.16.0起)

开票是背景工作. `createBillingRun` 队列运行并用 `BillingRunDto` 谁 `status` 实值 `Queued` (HTTP 202) (韩语). 票价 `getBillingRun` 直到状态 `Succeeded`, (中文(简体) ), `Failed` 或者说 `Cancelled`,然后列出它生产的发票 `listBillingRunInvoices`。 。 。 . `previewBillingRun` 是同步的,不会改变任何东西.

```ts
import {
  previewBillingRun, createBillingRun, getBillingRun, listBillingRunInvoices,
  cancelBillingRun, listBillingRuns,
} from '@cycomdatasystems/mackinac-sdk';
import type { BillingRunCriteriaDto, BillingRunDto } from '@cycomdatasystems/mackinac-sdk';

const criteria: BillingRunCriteriaDto = { periodId: 42 }; // fromDate / toDate default to the period's dates

const preview = await previewBillingRun(criteria);
// preview.billTos: the accounts (or departments, per preview.billTo) that would get an invoice
// preview.pendingInvoiceCount: Pending invoices the run would delete and regenerate

let run: BillingRunDto = await createBillingRun(criteria);
while (run.status === 'Queued' || run.status === 'Running') { // BillingRunStatus
  await new Promise((resolve) => setTimeout(resolve, 3000));
  run = await getBillingRun(run.id); // progress: run.billTosProcessed of run.billToCount
}

if (run.status === 'Failed') {
  console.error(run.errorDetail);
}
const invoices = await listBillingRunInvoices(run.id, { pageSize: 100 }); // InvoiceSummaryDto rows
```

-   **过滤器选择什么得到计费;它们不限制计费的工作.** `departmentIds`, (中文(简体) ), `accountIds` 财务报告和审定财务报表 `fileNumber` 选择哪些账户(或部门)开具账单。 然后,每个选定的项目将为其日期范围内的所有未开票工作开出账单.
-   **运行的ANDs `departmentIds` 财务报告和审定财务报表 `accountIds`。 。 。 .** 发票和收据的搜索结合了他们。 在UI中标出两种差异.
-   **每个房客一次跑一次.** `createBillingRun` 拒绝方式 `Mackinac 409:` 而另一个运行是 `Queued` 或者说 `Running`。接下来的问题细节机构 包含活动运行的 ID in `activeRunId`。要找到活动运行,请拨 `listBillingRuns({ statuses: ['Queued', 'Running'] })`。 。 。 .
-   **取消计划.** `cancelBillingRun` 解决运行( HTTP 202) .
    -   A 类 `Queued` 运行是 `Cancelled` 马上.
    -   A 类 `Running` 运行回来 `cancelRequested: true` 在下一个账户或部门之前停止。 已经开具的发票暂不开,并列在运行清单中.
    -   一旦运行结束,电话是 `Mackinac 409:`。 。 。 .
-   **复作是说已.** 重新运行一个时期只取代其待付发票。 开具发票、付款发票和注销发票从未被碰过.

#### 发票使用周期和收据(自13.1.6.0起)

人工发票、发票行、状况变化(“最后”是指 `Billed`)和收据。 每个变种都需要 `billing:write` 和与工作人员记录链接的打电话者`Mackinac 403:` (否则).

```ts
import {
  createBillingInvoice, createBillingInvoiceTransaction, patchBillingInvoiceTransaction,
  deleteBillingInvoiceTransaction, deleteBillingInvoice, updateBillingInvoiceStatus,
  updateBillingInvoiceStatuses, createBillingReceipt, getBillingReceipt, patchBillingReceipt,
  deleteBillingReceipt,
} from '@cycomdatasystems/mackinac-sdk';

// A manual invoice: Pending, numbered by the server, with one adjustment line for `amount`.
const invoice = await createBillingInvoice({
  invoiceDate: '2026-11-05', periodId: 42, billToId: 7, amount: 150, description: 'Manual fee',
});

// Lines can change only while the invoice is Pending; totals are recomputed by the server.
const line = await createBillingInvoiceTransaction(invoice.id, { transactionDate: '2026-11-05', amount: 25 });
await patchBillingInvoiceTransaction(invoice.id, line.id, [{ op: 'replace', path: '/amount', value: 30 }]);
await deleteBillingInvoiceTransaction(invoice.id, line.id);

// Finalize: marks the invoice's time, time adjustments and payments billed.
const billed = await updateBillingInvoiceStatus(invoice.id, { status: 'Billed' });

// Record a payment. paidAmount becomes the sum of the receipts; the invoice is Paid once they cover it.
const receipt = await createBillingReceipt({ invoiceId: billed.id, receiptDate: '2026-11-20', amount: 180 });
await patchBillingReceipt(receipt.id, [{ op: 'replace', path: '/checkNumber', value: '1001' }]);
await getBillingReceipt(receipt.id);
await deleteBillingReceipt(receipt.id); // the invoice goes back to Billed

// "Change Status (All)": a partial-success summary, never an all-or-nothing error.
const result = await updateBillingInvoiceStatuses({ invoiceIds: [101, 102, 103], status: 'Cancelled' });
for (const failure of result.failures) {
  console.warn(failure.invoiceId, failure.reason, failure.detail); // reason: 'NotFound' | 'Conflict'
}
await deleteBillingInvoice(invoice.id); // only a Pending invoice without receipts
```

-   **付款状态是衍生的,从未设定.** `paidAmount` 是发票收据的总和。 开具或支付的发票是: `Paid` (单位:千美元)`isPaid: true`确切地说,其收据涵盖何时 `amount`;多付款按已付款计算。 编辑一张收据或删除一张发票 `Billed`。 。 。 .
-   **地位规则** (单位:千美元)`Mackinac 409:` 断后,没有什么变化:
    -   有收据的发票不能移动到 `Pending` 或者说 `Cancelled`· ;
    -   `Paid` 需要开具发票或付款发票,发票的收据必须包括(有记录的付款与 `createBillingReceipt`(三);
    -   `Pending` 发票的时间、调整和付款、准确反向 `Billed`。 。 。 . `Unknown` 属于 `BillingInvoiceStatus` 仅用于回复;发送是 `Mackinac 400:`。 。 。 .
-   **仅待决.** 只有待发发票才能被删除(而且只有没有收据)或增加、编辑或删除行。 手动行总是 `GeneralExpense` 类型(代码 6).
-   **收款** 仅凭账单或付款发票。 付款人为发票票对账单;发票和付款人不能补发. `amount` 绝不能是零,和 `revenueCode` 必须是收入代码(`listBillingRevenueCodes`) (中文(简体) ). `receiptType` 是没有已知值集的原始数字.
-   ⚠️ **当计费运行排队或运行时**,开出/删除发票,更改行并拒绝两个状态呼叫 `Mackinac 409:` 详细情况 `activeBillingRunId`. 收款不受影响。 显示活动运行( E)`getBillingRun`)而后再试.
-   **散装状态 .** `invoiceIds` 持有1至500个识别码。 隐形身份归来 `NotFound` 和不合格的 `Conflict`;两者都不被触动,其余的被一起更新. A 类 `Mackinac 409:` 表示批次被整体拒绝(主动运行,或成为不合格中途请求的发票);没有更新,所以重试.
-   **补丁体** 使用通用软件 `Operation[]`一样 `patchBillingPeriod`。行路径 : `/transactionDate`, (中文(简体) ), `/amount`, (中文(简体) ), `/hours`。接收路径 : `/receiptDate`, (中文(简体) ), `/amount`, (中文(简体) ), `/checkNumber`, (中文(简体) ), `/revenueCode`, (中文(简体) ), `/receiptType`, (中文(简体) ), `/notes`。任何其他路径是 `Mackinac 400:`。 。 。 .
-   另一个租户的发票、线路或收据是: `Mackinac 404:`,从来没有403.

### 合同管理(自13.6.0起)

合同管理(单元) `CM`读作: `searchContracts` 编号 : `getContractSearchHits` (搜索和呼唤,相同 `MatterSearchHitDtoPaginatedResultDto` 作为 `searchMatters`, (中文(简体) ), `getContract` 财务报告和审定财务报表 `listContractOrders`数字 :

```ts
import { searchContracts, getContractSearchHits, getContract, listContractOrders } from '@cycomdatasystems/mackinac-sdk';

const first = await searchContracts({ searchCriteria: { contType: 'CO', title: 'Paving*' }, pageSize: 25 });
const next = first.hasMoreHits ? await getContractSearchHits(2, { pageSize: 25 }) : undefined;

const contract = await getContract(1234);
const step = contract.currentApprovalStep?.description; // currentApprovalStep and master may be null
const { orders, contractsTotal, purchaseOrdersTotal } = await listContractOrders(1234);
```

-   搜索需要合同管理访问(V16)并拒绝 `Mackinac 403:` 没有它. `title` 财务报告和审定财务报表 `number` 属于前缀匹配( e)`*` 是通配符,仅限于 ASCII 和 Latin-1 字符;其他的字符都是 `Mackinac 400:`。 。 。 .
-   `getContract` 编号 : `listContractOrders` 拒绝 `Mackinac 404:` 对于你可能看不到的事情, 这不是模块CM, 或者没有合同记录。 他们不信 `Mackinac 409:` (a) 事项有不止一份合同记录 `ContractProblemDetails` 与 `errorCode: 'DuplicateContractRecord'`。 。 。 .
-   单位 `orders`更改单(`contType: 'CH'`携带 `null` 页:1 `department`, (中文(简体) ), `account`, (中文(简体) ), `expiration`, (中文(简体) ), `authAmount`, (中文(简体) ), `totalPaid` 财务报告和审定财务报表 `openBalance`。 。 。 . `contractsTotal` 编号 : `purchaseOrdersTotal` 覆盖每个直接的孩子,包括你可能看不见的孩子.

#### 证书和批准步骤(自13.1.6.0起)

合同的保险凭证及其批准步骤,加上租户的核准情况(只读):

```ts
import {
  listContractCertificates, createContractCertificate, patchContractCertificate, deleteContractCertificate,
  listContractApprovalSteps, createContractApprovalStep, patchContractApprovalStep, deleteContractApprovalStep,
  importContractApprovalProfile, listApprovalProfiles,
} from '@cycomdatasystems/mackinac-sdk';

const certificates = await listContractCertificates(1234); // latest expiration first, none last
const cert = await createContractCertificate(1234, { type: 'GL', number: 'N-1', expirationDate: '2027-01-01' });
await patchContractCertificate(1234, cert.id, [{ op: 'replace', path: '/remarks', value: 'Renewed' }]);

const { items, currentStepId } = await listContractApprovalSteps(1234);
await patchContractApprovalStep(1234, currentStepId!, [{ op: 'replace', path: '/completedDate', value: '2026-11-02' }]);

const profiles = await listApprovalProfiles();
const seeded = await importContractApprovalProfile(1234, { profileId: profiles[0].id }); // only into a contract with no steps
```

-   PATCH 机构按路径输入(`PatchContractCertificateOperation`, (中文(简体) ), `PatchContractApprovalStepOperation`: 只有列出的路径和 `add` 编号 : `replace` 编号 : `remove` 现予接受. `/stageOrder` 可能不会变成无效。 代码,部门或工作人员ID仅在其值变化时被检查,所以遗留行仍然可以编辑.
-   完成一步标志着下一个步骤(到 `stageOrder`)于该日期收到,合同的 `approvalStep` 遵循当前步骤。 无效 `getContract` 经过一步的写.
-   拒绝 : `Mackinac 400:` 无效体(a) `ValidationProblemDetails` 按字段键); `Mackinac 404:` 合同 `getContract`(一) 另一合同的证明或步骤,或未知的部门、工作人员身份或简介; `Mackinac 409:` 与 `errorCode` `DuplicateContractRecord`,或 `ApprovalStepsExist` 在输入一项已有步骤的合同时.

#### 创建、编辑和删除合同、参与组织和更改单(自13.1.6.0起)

`previewContractOrder`, (中文(简体) ), `createContract`, (中文(简体) ), `patchContract` 财务报告和审定财务报表 `deleteContract` 写作合同(`CO`),定购单`PO`)和变更单(`CH`:

```ts
import { previewContractOrder, createContract, patchContract, deleteContract } from '@cycomdatasystems/mackinac-sdk';

// Would this PO under contract 1234 need an automatic change order? Writes and allocates nothing.
const preview = await previewContractOrder({ masterMatterId: 1234, contType: 'PO', authAmount: 700 });

const { contract, autoChangeOrder } = await createContract({
  contType: 'PO', masterMatterId: 1234, title: 'Paving phase 2', authAmount: 700,
  confirmAutoChangeOrder: preview.wouldCreateChangeOrder, // only after the user has confirmed
});

await patchContract(contract.matterId, [
  { op: 'replace', path: '/authAmount', value: 900 },
  { op: 'replace', path: '/description', value: 'Revised scope' },
], { confirmAutoChangeOrder: false });

await deleteContract(contract.matterId, { deleteAttachments: false });
```

-   `createContract`数字 : `contType` 实值 `CO`, (中文(简体) ), `PO` 或者说 `CH`. CO没有主机,PO的主机是可选的(CO或PO),而CH需要一个(CO或PO). 无效 `fileNumber` 从 CTYLAW 口罩中分配。 儿童令没有 `number` 当 `CM/AUTOFILLCHANGE` 开始 服务器设置 `netAuthAmount = authAmount`, (中文(简体) ), `totalPaid = 0` 财务报告和审定财务报表 `approvalStep = null`。 。 。 .
-   **自动更改顺序(R6).** 当CO下的PO将CO的开放平衡推到零以下时,创建或 `authAmount` 补丁拒绝方式 `Mackinac 409:` 财务报告和审定财务报表 `errorCode: 'ChangeOrderConfirmationRequired'`;身体携带着 `changeOrderAmount` 财务报告和审定财务报表 `masterOpenBalanceAfter`。在用户确认后,以 `confirmAutoChangeOrder: true` (在体内为 `createContract`,在查询中查找 `patchContract`) (中文(简体) ). 创建的更改顺序返回为 `autoChangeOrder` (一无所出即为无效). 无效 `getContract` 编号 : `listContractOrders` 为师也.
-   `patchContract` 使用输入的操作( e)`PatchContractOperation`:只接受所列路径 `/contType`, (中文(简体) ), `/masterMatterId`, (中文(简体) ), `/netAuthAmount`, (中文(简体) ), `/totalPaid` 财务报告和审定财务报表 `/approvalStep` 以 `Mackinac 400:`更改 `/authAmount` 另设 `netAuthAmount`更改 `/assocMatterId` 还按儿童直接订购,移动订购费。 一个空的 `/description` 删除描述.
-   `deleteContract` 需求 `deleteAttachments`它拒绝 `Mackinac 409:` 财务报告和审定财务报表 `errorCode: 'ContractHasDependents'` 儿童订单、付款、批准步骤或证明 `childOrders`, (中文(简体) ), `payments`, (中文(简体) ), `approvalSteps` 财务报告和审定财务报表 `certificates`。 。 。 . `deleteMatter` 就合同管理事项而言,行为也一样.
-   其他拒绝: `Mackinac 400:` 无效体(a) `ValidationProblemDetails` a. 按字段键,包括1753年之前的日期和小数点后缀超过4个; `Mackinac 403:` 从 `previewContractOrder` 编号 : `createContract` 不得进入合同管理系统; `Mackinac 404:` 你可能看不见的合同,或 `masterMatterId`, (中文(简体) ), `assocMatterId` 或者说 `vendorId` 这不是你的房客; `Mackinac 409:` 与 `errorCode` `DuplicateFileNumber` 或者说 `DuplicateContractRecord`· ; `Mackinac 503:` 当另一个请求持有编号锁(重试)时.

#### 合同付款和支出限额(自13.1.6.0起)

合同或定购单的付款分页、支出限额预览和“进入付款”:

```ts
import {
  listContractPayments, checkContractPaymentLimit, createContractPayment,
  patchContractPayment, deleteContractPayment,
} from '@cycomdatasystems/mackinac-sdk';

const { items, paidTotal } = await listContractPayments(1234); // newest first; no paging

// Before saving: would this amount warn or be blocked? Writes nothing.
const preview = await checkContractPaymentLimit(1234, { amount: 250 });
if (preview.warningLevel > 0) { /* show preview.warningMessage */ }

const { payment, limit } = await createContractPayment(1234, {
  date: '2026-11-04', objectCode: 'PROF', amount: 250, // vendorId defaults to the contract's vendor
});

await patchContractPayment(1234, payment.id, [{ op: 'replace', path: '/amount', value: 300 }]);
await deleteContractPayment(1234, payment.id);
```

-   **什么付款.** APO 列出付款情况 `poId` = PO;任何其他类型列表 `contractId` = 问题,因此合同中也列出了带有其ID的PO付款. 每行都算数,随便 `paid` 说. `paidTotal` 总和,标记行支付.
-   **服务器设置字段 .** 创建服务器集 `contractId` 编号 : `poId` (购买力平价付款也带有购买力平价总合同), `matterId` (合同涉及的事项,否则请求涉及 `matterId`,供应商的收款人和地址(违约:合同供应商), `payType` (从对象代码)和 `origin` (1) 答复中从未包括收款人的纳税凭证.
-   **支出限额.** 警告( E)`warningLevel` 1/2 与 `warningMessage`永远不要挡住。 其订单未结余额低于零的付款将被拒绝 `Mackinac 422:` 财务报告和审定财务报表 `errorCode: 'ContractLimitExceeded'`; 尸体 (`ContractPaymentProblemDetails`载体 `openBalanceBefore`, (中文(简体) ), `openBalanceAfter`, (中文(简体) ), `amount` 财务报告和审定财务报表 `targetMatterId`. 限额适用于金额的增加,以支付本身的订单为限(如果支付时有购买权). `checkContractPaymentLimit` 返回 200 即使在 `blocked` 真实; 通过 `paymentId` 预览现有付款的新金额.
-   `TOTAL_PAID` (单位:千美元)`ContractDto.totalPaid`, (中文(简体) ), `ContractOrderSummaryDto.totalPaid`)现在由服务器在每份支付笔记上维护,包括事项财务端点. 无效 `getContract` 编号 : `listContractOrders` (和"主人会",为"PO") 付款后写作.
-   `patchContractPayment` 使用输入的操作( e)`PatchContractPaymentOperation`:只有所列出的路径被接受,链接,收款人和地址无法补齐. 发送 `/vendorId` 重新复印供应商;不复印则保留储存的供应商。 一个空的 `/notes` 删除注释.
-   拒绝 : `Mackinac 400:` 无效体(a) `ContractValidationProblemDetails` 按字段键),包括不活动对象代码或保留对象代码,数量为0,小数位数超过2个或超出货币范围,日期为1753年之前 `errorCode: 'PayeeRequired'` (一) 请求或合同均未指明供应商; `Mackinac 404:` 对于你可能看不到的合同, 支付另一订单,或 `vendorId`, (中文(简体) ), `requestor` 或者说 `matterId` 不在你租户; `Mackinac 409:` 与 `errorCode: 'DuplicateContractRecord'`· ; `Mackinac 422:` 与 `errorCode: 'ContractTypeNotPayable'` 在更改单上创建付款时( )`CH`) (中文(简体) ).

* * *

## 代码生成

此 SDK 由 Mackinac OpenAPI 光谱生成 **阴性**。 。 。 .

### 重新生成 SDK

```bash
npm run orval
```

确保最新的 `swagger.json` 从Mackinac API 位于 `/contracts` 目录或配置的 URL .

### 捆绑的 OpenAPI 光谱

用来生成SDK 飞船的 OpenAPI 精确文档, 其软件包为 `dist/openapi.json`,通过 `./openapi.json` 子路径 :

```ts
import spec from '@cycomdatasystems/mackinac-sdk/openapi.json'; // typed as OpenAPIV3.Document

console.log(spec.info.title, spec.info.version);
```

对于非导入工具( codegen, docs, Postman等) , 解析文件路径 :

```ts
const path = require.resolve('@cycomdatasystems/mackinac-sdk/openapi.json');
```

> **说明:** 软件包 `exports`因此,只有根管(`@cycomdatasystems/mackinac-sdk`和 `./openapi.json` 可导入。 深度进口 `dist/` 不支持.

* * *

## 发展

-   要求节点18+
-   安装依赖性 :

```bash
npm install
```

-   运行代码源 + 构建 :

```bash
npm run orval && npm run build
```

-   运行 WRP 自动指定运行时间和公共类型合同检查 :

```bash
npm test
```

* * *

## 版本

此套件遵循语义化版本 :

-   **贾斯汀:** 重新生成没有 API 合同更改的 SDK
-   **迈克尔:** 新的终点或不可突破的添加
-   **大师:** 中断API合同变更

* * *

## 许可证

此套件意在Cycom内部使用.  
如果在外部分发,则添加适当的开源许可证(如麻省理工学院).

## 常见问题

### @cycomdatasystems/mackinac-sdk 是什么？

Mackinac API 的共享TypeScript客户端\.

### 如何安装 @cycomdatasystems/mackinac-sdk？

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

### @cycomdatasystems/mackinac-sdk 支持 TypeScript 吗？

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

### @cycomdatasystems/mackinac-sdk 支持 ESM 还是 CommonJS？

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

### @cycomdatasystems/mackinac-sdk 可以商用吗？

@cycomdatasystems/mackinac-sdk 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @cycomdatasystems/mackinac-sdk 的下载量有多少？

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

### @cycomdatasystems/mackinac-sdk 还在维护吗？

最新版本 13\.16\.0 发布于 2026/11/07（4 天前）；至今共发布 38 个版本，其中过去 12 个月发布了 38 个；首次发布于 2026/04/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。