麦克纳克SDK

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

安装

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

使用量

应用程序启动时配置 SDK

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

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

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

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

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

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

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 的路由处理器

// 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);
}

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

// 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}`,
      };
    },
  });
}

// 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);
}

示例:同步信头提供者

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. 逐个呼叫头传递给单个端点函数

// 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 标题将继续按预期工作.

示例

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 这不是房客的钥匙.

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后置行(有驱动项).

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) 返回时 AttachmentFolderDtos. 列表为平面:从 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数字 :

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。每次搜索都使用一个参数对象,阵列参数作为重复键发送:

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 是同步的,不会改变任何东西.

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: (否则).

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数字 :

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起)

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

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:

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起)

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

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

npm run orval

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

捆绑的 OpenAPI 光谱

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

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

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

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

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

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

发展

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

npm install

• 运行代码源 + 构建 :

npm run orval && npm run build

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

npm test

版本

此套件遵循语义化版本 :

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

许可证

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