# @devgoliiive/unidigital-sdk 中文文档

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

版本：0\.1\.4
npm 元数据更新时间：2026-10-12T17:34:01.003Z
中文译文更新时间：2026-11-12T05:13:00.619Z
软件包许可：UNLICENSED

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

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

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

- 包体积（解压后）：113 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-09-25T20:43:32.663Z
- 最新版本发布：2026-10-12T17:34:00.714Z
- 近 30 天下载量：2821（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

为Unidigital财政计费API打入客户端,并有webhook签名验证.

## 安装

```sh
npm install @devgoliiive/unidigital-sdk
```

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

## README

# @devgolive/单数sdk

El sdk tipado del servicio de facturación 财政统一数字. 环生母 人权 `/v1`, verifica las firms de los webhoks 和 正常的 los 错误 una jerarquía districtada por un código sistable. 中国植物物种信息数据库.

(原始内容存档于2013-10-12). El sdk hace tres cosas y ninguna más. **没有** retenta respuestas HTTP, 无 重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置重置 espara a que un documento se finalice, 无本地有效有效载荷 y no trae 运行时间需要依赖.

## 起义组织

(原始内容存档于2018-09-21) (英语). El sdk se publica como paquete público en **npmjs.com (英语)**组织组织 `devgoliiive`。无花果 `.npmrc`, (中文(简体) ), `bunfig.toml` ni sord: ni en local, ni 指代语 : ni 本地语 : en CI, ni en el built de Railway. 中国铁路总公司.

```sh
pnpm add @devgoliiive/unidigital-sdk
# o
bun add @devgoliiive/unidigital-sdk
```

### 技能辅助代理人

(原始内容存档于2012-10-12) (英语). El paquete tree una skill de Claude Code con las invarants del SDK, versionada con. Enlázala desde la raíz de tu repo: (原始内容存档于2018-09-31)

```sh
mkdir -p .claude/skills
ln -s ../../node_modules/@devgoliiive/unidigital-sdk/skills/unidigital-sdk .claude/skills/unidigital-sdk
```

## 乌苏

### 建筑设计师

```ts
import { createClient } from "@devgoliiive/unidigital-sdk";

const unidigital = createClient({
  baseUrl: process.env.UNIDIGITAL_API_URL!,
  apiKey: process.env.UNIDIGITAL_API_KEY!,
  // Opcionales:
  timeoutMs: 10_000, // por defecto; ajustable por llamada
  retry: { attempts: 2 }, // solo fallos de transporte, nunca respuestas HTTP
  // fetch: miFetchInstrumentado,
});
```

无干草 URL por 叛逃:角地 una envejece mal, y apuntar al entoro {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}那又怎样.

### 经济管制委员会

(原始内容存档于2018-10-21). Verifica la conectividad y las credenciales antes de emitir nada real.

```ts
await unidigital.checkConnectivity();
```

### 解析器 un a serie

```ts
const { series } = await unidigital.series.lookup({
  unidigitalAccountId: accountId,
});
const seriesId = series.find((serie) => serie.name === "A")?.seriesId;
```

(原始内容存档于2018-10-03). Cada serie tree el `seriesId` 击球 `documents.issue`. 埃尔查普登记处 así que una serie nueva aparece en la (原始内容存档于2019-10-21). siguiente lamada. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}请来个咨询 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}请说一下. 索利骗局 `seriesId: null` 平起平起平起地 迷幻药 任何音乐都不可能出现.

### 埃米蒂尔·乌斯拉

```ts
const { trackingId, status } = await unidigital.documents.issue({
  unidigitalAccountId: accountId,
  seriesId,
  idempotencyKey: order.id, // obligatoria, y sale de tu dominio
  payload: {
    Name: "Carlos Perez",
    FiscalRegistryCode: "J",
    FiscalRegistry: "297182748",
    Address: "Av. Principal, Caracas",
    PaymentType: "CONTADO",
    EmailTo: "cliente@example.com",
    EmissionDateAndTime: "2026-01-02T10:00:00Z",
    Currency: "USD",
    TaxBase: 100,
    TaxAmount: 16,
    Total: 116,
    GrandTotal: 116,
    IGTFPercentage: 3,
    TaxPercentReduced: 8,
    TaxPercentSumptuary: 31,
    Details: [
      {
        Description: "Boleto general",
        Quantity: 1,
        UnitPrice: 100,
        Amount: 100,
        TaxAmount: 16,
        TaxPercent: 16,
        TotalAmount: 116,
        OperationCode: "C001",
        ProductType: 1,
      },
    ],
  },
});
```

**(原始内容存档于2012-10-12). La clave de idempotencia es offeroria y el SDK nineca la genera.** 无 {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1}重新来过 {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1}我们来过 (原始内容存档于2019-10-21) (英语). Si generras una nueva, el servicio 点数 **dos 文档财务** {\\fn华文楷体\\fs16\\1che0e0e0}康斯·克马多斯.

洛斯·坎波斯 que el servicio se signa a sí mismo - - 萨斯·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克·克`Number`, (中文(简体) ), `SerieStrongId`, (中文(简体) ), `DocumentType` y 输 `Affected*` qe 描述 el documento afectado——无子 羡慕:el tipo los rechaza antes del 来回旅行.

### 埃米蒂尔·乌纳·德比托

(原始内容存档于2018-09-29) (英语). El documento afecado va por su id, y nada más sobre él.

```ts
await unidigital.notes.issue({
  unidigitalAccountId: accountId,
  seriesId,
  documentType: "credit_note", // o "debit_note"
  affectedDocumentId: invoiceId,
  idempotencyKey: refund.id,
  payload: {/* como arriba */},
});
```

### 埃斯塔多协商会议

(原始内容存档于2018-10-21). Es el respaldo cuando el webhook no legó. 拉斯·莱克图拉斯(Las lecturas)`getStatus`, (中文(简体) ), `getContent`, (中文(简体) ), `void`)受克丹尔 `id` 德尔文件 `trackingId` 页:1 萨尔瓦多 `issue`。 。 。 .

```ts
const doc = await unidigital.documents.getStatus(trackingId);

doc.invoiceNumber; // el correlativo dentro de la serie
doc.controlNumber; // el número de control del SENIAT, null hasta `issued`
```

控制之子 **脱口而出**。取消文档编号 (原始内容存档于2018-09-21). está legente completo hasta tener el segundo.

没有干草帮手 de espera a estado 决赛, y es deliberado: la finalización tarda minutos, así que una espera blopeante dentro de un handler HTTP es una Caida 互联网档案馆的存檔,存档日期2013-12-02 (原始内容存档于2018-09-26). esperando su Tourno. {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}"重新找回工作" {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}"重新找回工作".

### 文件翻译

```ts
const { url } = await unidigital.documents.getContent(documentId);
```

### 角解文档

```ts
const result = await unidigital.documents.void(documentId);

if (result.outcome === "voided_local_record_pending") {
  // La anulación SÍ ocurrió en el proveedor; solo nuestro registro no ha
  // cuadrado, y el servicio lo cierra con un barrido propio. No es un fallo.
}
```

Es síncrona, no leva clave de idempotencia (法语:aular dos veces es seguro) y el (法语) SDK没有la retenta.

### 虚拟无网点

Es una función suelta: verifica no nacesita API 密钥 ni URL 基础, y el proceso {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}请检查date=中的日期值 (帮助).

```ts
import { verifyWebhook, WebhookVerificationError } from "@devgoliiive/unidigital-sdk";

// El cuerpo tiene que ser el CRUDO, tal cual llegó. Re-serializarlo reordena
// claves y la firma deja de coincidir.
try {
  const event = verifyWebhook({
    rawBody,
    headers: req.headers,
    secret: process.env.UNIDIGITAL_WEBHOOK_SECRET!,
    toleranceSeconds: 300, // por defecto
  });

  // Deduplica por el delivery id, NUNCA por el document id: un mismo documento
  // genera más de un evento, y cada uno es un hecho distinto.
  if (await alreadyProcessed(event.deliveryId)) return;

  switch (event.type) {
    case "fiscal_document.issued":
      // event.data.controlNumber ya está disponible
      break;
    case "fiscal_document.approved":
    case "fiscal_document.rejected":
    case "fiscal_document.voided":
      break;
  }
} catch (error) {
  if (error instanceof WebhookVerificationError) {
    // error.reason: "missing_header" | "malformed_header" | "invalid_secret"
    //             | "timestamp_out_of_window" | "signature_mismatch"
    //             | "malformed_body"
  }
}
```

## 错误

(原始内容存档于2018-10-25) (英语). Toda respuesta no exterosa llega como excepción tipada. **歧视 `code`, (中文(简体) ), 第 二 部 分**: el mensaje es libre, leva el texto de Unidigital en un (原始内容存档于2012-10-10). fallo guas arriba, y cambia cuando alguien corrige un a mrotata.

头 **树枝** 排除错误, y un `catch` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}拉普莱托·拉斯·立方体·拉斯·特雷斯: `UnidigitalError` (服务回应), `UnexpectedResponseError` (对) i. 邮箱没有说明 `TransportError` (nunca hubeo respuesta) (英语). 埃尔 警卫 `isUnidigitalSdkError` (原始内容存档于2012-10-12). cubre las tres de una vez.

```ts
import { ConflictError, UnidigitalError, ValidationError } from "@devgoliiive/unidigital-sdk";

try {
  await unidigital.documents.void(documentId);
} catch (error) {
  if (error instanceof ConflictError) {
    if (error.code === "void_in_flight") {
      // Ya hay una anulación en vuelo: espera y consulta el estado.
    }
    if (error.code === "document_not_voidable") {
      // Definitivo: el documento no existe fiscalmente. Ríndete.
    }
  }

  if (error instanceof ValidationError) {
    error.issues; // qué campo corregir
  }

  if (error instanceof UnidigitalError) {
    error.code;
    error.status;
    error.requestId; // cítalo al pedir soporte
  }
}
```

| 线索 | 状态 | 准将 |
| --- | --- | --- |
| `ValidationError` | 400个 | 有效载荷 es inválido; `issues` 无名小卒. |
| `AuthenticationError` | 401 (中文(简体) ) | (原始内容存档于2018-10-21) (英语). API key ausente, inválida o sin loent. |
| `PermissionError` | 403 (韩语) | {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1}艾尔租户没有领带 {\\fn黑体\\fs20\\shad2\\2aH82\\3aH20\\4aH33\\fscx95\\3cH592001\\be1}埃勒租户没有领带. |
| `NotFoundError` | 404 (韩语) | 不存在——o es de otro 租户, que response igual. |
| `ConflictError` | 409个 | (原始内容存档于2017-09-28). El estado del documento impide la operación. |
| `UpstreamError` | 502 (中文(简体) ) | Fallo de Unidical. (原始内容存档于2018-09-29). |
| `ServiceUnavailableError` | 第503条 | (原始内容存档于2013-10-12). Normane: puerto sin Cablear o Credenciales. |
| `InternalError` | 500个 | 错误 nuestro 。 俱乐部 `requestId`。 。 。 . |
| `UnexpectedResponseError` | —— 说 | La repuesta no encaja en el bread; conserva status y cuerrpo. 中国植物物种信息数据库. |
| `TransportError` | —— 说 | Fallo de transporte agestado. (原始内容存档于2018-09-27). 不,不,不,不,不,不,不. |

### 罪过 `strict`

编辑员 **无 te sostrará ningún 语句 `| null`** {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}那就叫超级美人 洛斯坎波斯语 克·普德活佛塔之子: en `DocumentStatusView`, (中文(简体) ), `strongId`, (中文(简体) ), `invoiceNumber`, (中文(简体) ), `controlNumber`, (中文(简体) ), `batchStrongId`, (中文(简体) ), `rejectionReason` 电子 `issuedAt`页:1 `data` 页:1 解开网路, `invoiceNumber`, (中文(简体) ), `controlNumber`, (中文(简体) ), `issuedAt` 尔 `reason`; y (韩语) `issues` 内 `ValidationError`康普鲁埃巴洛斯是曼诺.

### 莱茵滕多斯

El SDK retenta (英语) **单人运输** (DNS、Conexión reciciada、插座) colgado, 超时), con tope bajo y backoff com jitter, reusando la misma clave de (英语:calve de) 爱德波多伦西亚.

**Ninguna respuesta HTTP se retenta (英语)**(原始内容存档于2013-10-12). anque la intuición diga lo contrario: 阿基乌 `503` 永久居留权,y un `502` 阿拉伯和平协会 阿拉伯文化协会 **圣阿普利科**{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}这才是真正的和解 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}不 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}不.

## Dobles 测试

(原始内容存档于2018-10-21). La interfaz del sdk se exporta como tipo, para que escribas tus propios dobles y (原始内容存档于2018-10-12) (英语). se rompan en CI Cuando la superficie cambie.

```ts
import type { UnidigitalClient } from "@devgoliiive/unidigital-sdk";

const fake: UnidigitalClient = {/* el compilador te dice qué falta */};
```

无公子嘲弄无公子:没有子道 嘲弄他人的言论 (原始内容存档于2018-06-21). metería código de test en el bund de producción.

## 版本和公众

出自"活泼活泼"手册,"活泼活泼"(semver independente),"罪恶之地"(sin gestor de changets). 埃尔·德·斯德克(El Major del SDK) (原始内容存档于2019-03-26). sige al major de la API; sind y sad son suyos.

公关 **法语区 `packages/sdk/package.json` y 勒瓦罗 a 主要**: el工作流程 `.github/workflows/publish-sdk.yml` (原始内容存档于2018-10-21). vifica el empaquetado 你公开。 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}请登记 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}请登记 {\\fn黑体\\fs22\\bord1\\shad0\\3aHBE\\4aH00\\fscx67\\fscy66\\2cHFFFFFF\\3cH808080}请登记.

等一等 等一等, `.github/workflows/sdk-version.yml` (原始内容存档于2018-10-21) (英语). falla un PR hacia main que toca `src/` 欧 `tsdown.config.ts` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}我就是这个意思. 苏贝坦比昂 `SDK_VERSION` 内 `src/version.ts`; 未经测试 exige que choncidan.

工作流程 se autentica con **值得信赖的出版** (OIDC): npmjs.com confía (英语) 工作流程没有干草标志 " 生命之交 " 组织 npmjs.com, en (英语) _设置_ → _信任的出版商_ (原始内容存档于2018-10-21). del paquete.

宣传马诺语, sesión con `npm login` 喀麦隆 组织 `devgoliiive`数字 :

```sh
pnpm --filter @devgoliiive/unidigital-sdk release
```

## 常见问题

### @devgoliiive/unidigital-sdk 是什么？

为Unidigital财政计费API打入客户端,并有webhook签名验证\.

### 如何安装 @devgoliiive/unidigital-sdk？

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

### @devgoliiive/unidigital-sdk 支持 TypeScript 吗？

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

### @devgoliiive/unidigital-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @devgoliiive/unidigital-sdk 可以商用吗？

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

### @devgoliiive/unidigital-sdk 的下载量有多少？

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

### @devgoliiive/unidigital-sdk 还在维护吗？

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