# @facta-dte/api 中文文档

规范地址：https://npmcn.com/package/%40facta-dte/api/

版本：0\.6\.0
npm 元数据更新时间：2026-11-15T00:09:16.019Z
中文译文更新时间：2026-11-15T00:12:29.545Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：3.5 MB，254 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：0 个
- peer 依赖：react \>=18，react-dom \>=18
- 首次发布：2026-10-03T19:31:30.496Z
- 最新版本发布：2026-11-15T00:09:15.670Z
- 近 30 天下载量：4408（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

萨尔瓦多Facta电子发票API(DTE)的TypeScript客户端.

## 安装

```sh
npm install @facta-dte/api
```

也可以使用：`pnpm add @facta-dte/api`、`yarn add @facta-dte/api`、`bun add @facta-dte/api`

## README

# `@facta-dte/api` — 类型脚本 SDK

Facta电子税务文件API的官方TypeScript和JavaScript客户端. 它使用服务器作为财政授权:SDK发送DTE数据,处理证书和重试,并可以归档所发行的字节以进行重启安全恢复.

读取 [西班牙语读取](https://npmcn.com/package/%40facta-dte/api/README.es.md)全数 [方法参考](https://npmcn.com/package/%40facta-dte/api/guides/reference.md) 记录每种公用方法的论据、返回值、所需范围、副作用、错误、重复和恢复行为。 这个 [公布的API合同](https://hcnvknpsbadplnfcflxx.supabase.co/functions/v1/api-v1/v1/openapi.json) hTTP 字段和响应仍然具有权威性.

**软件包和源 :** [无 `@facta-dte/api`](https://www.npmjs.com/package/@facta-dte/api) • 妇女 [公共 GitHub 仓库](https://github.com/Facta-DTE/facta-api-sdk)。 。 。 .

**版本选择 :** 此源检出已放行 `0.6.0`,稳定版本(npm) `latest`) (中文(简体) ). 这个 [npm 登记](https://www.npmjs.com/package/@facta-dte/api?activeTab=versions) 对已出版的版本和发行标记具有权威性。 确认您已安装的已发布版本在使用前包含一个方法; 以装入的检出来验证纯源能力 .

**端点选择 :** `FACTA_PRODUCTION_BASE_URL` 指定默认使用的生产终点。 使用 `baseUrl: FACTA_STAGING_BASE_URL` 选择装配,或提供自定义终点。 官方的 PHP SDK 也可以在 [`facta-dte/api`](https://github.com/Facta-DTE/facta-api-sdk-php)。 。 。 .

官方SDK为TypeScript/JavaScript和PHP提供. 直接的HTTP示例并不代表已发布的SDK.

> **许可证 :** 麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40facta-dte/api/LICENSE)。 。 。 .

## 运行时间支持

SDK根条目在Node.js 22+,Deno,和Bun中工作,不急于导入文件系统模块. 这个 `@facta-dte/api/node` 条目添加仅节点加密文件档案和配置文件加载. 奉献 `@facta-dte/api/file-archive` 条目也是节点.

便携式客户端依赖标准 `fetch`网络加密, `AbortSignal`,以及 `crypto.randomUUID`。每个请求使用配置的 API 端点;a `facta_test_` 键在同一端点选择Hacienda的测试环境。 客户端默认使用生产 URL; 测试中转权限 `baseUrl: FACTA_STAGING_BASE_URL` (单位:千美元)`https://eobxzotnqzgtpuqvmpkc.supabase.co/functions/v1/api-v1`带有 `facta_test_` 启动应用程序的密钥 .

## 快开始

```sh
# Verify published versions and tags, then install the approved stable release:
npm view @facta-dte/api version dist-tags
pnpm add @facta-dte/api
# Optionally install a prerelease, when one is published:
pnpm add @facta-dte/api@next
```

```ts
import { Facta, type DteRequest } from "@facta-dte/api";

const facta = new Facta({
  apiKey: process.env.FACTA_API_KEY!,
  signKey: process.env.FACTA_SIGN_KEY!,
});

const sale: DteRequest = {
  tipoDte: "01",
  items: [{ descripcion: "Sample item", cantidad: 1, precioUni: 10 }],
};
const result = await facta.issue(sale, { idempotencyKey: "order-1042" });
```

`tipoDte`, (中文(简体) ), `codigoGeneracion`,所有其他财政电线字段保留 Facta API 定义的名称和值。 公共类型Script标识为英语;财政有效载荷属性不翻译.

一个 `IssueResult` 是一个受歧视的工会。 检查 `result.estado`数字 : `"sellado"` 表示Hacienda归还了封条; `"contingencia"` 意味着Facta接受并签署了DTE,但需要和解. 在回应不确定后,不要提交带有新等同键的销售.

## 全权证书和配置

| 选项 | 目的 |
| --- | --- |
| `apiKey` | 需求 `facta_test_…` 或者说 `facta_live_…` 键。 密钥选择了Hacienda环境. |
| `signKey` | 所需经费 `issue`, (中文(简体) ), `prepare` + 键 `sign`, (中文(简体) ), `invalidate`,以及 `registerReturn`只在签字行动时发送. |
| `unlockKey` | 可选 `factauk_…` 键用于解密同步目的捆绑。 从未送去API. |
| `baseUrl` | 可选 API 主机. Facta公开API URL的默认值. |
| `timeoutMs` | 请求超时,默认为60,000 ms,包括响应-body读取. |
| `region` | 职能区域 `x-region` 因此,请求运行在数据库旁边。 默认: 从 `/v1/status` (倒计时) `us-west-2` 年龄较大的APIs). 一个字符串覆盖, `false` 禁用; 还有 `config.region` 编辑 `FACTA_API_REGION` 环境变量. `await facta.region()` 返回; `diagnose()` 报告服务区. |
| `maxRetries` | 对明确可重试的运输/服务故障重试限制;默认为 3. |
| `fetch` | 可选获取自有运行时间或测试的执行 . |
| `clock` | 存档时间戳和S3签名的参考时钟 : `true` (违约,公众) `https://clock.factadte.com/`, URL,或 `false` 为设备时钟。 校准了懒散 从未失败 归档方法( E)`issueAndArchive`, (中文(简体) ), `recoverOperation`, (中文(简体) ), `invalidateAndArchive`, (中文(简体) ), `replicateArchive`)等一个过程的第一次校正:在正常情况下,在正常情况下,在服务无法到达时,大约为6 s (2 s 3 s 超时);后来的调用在当地回答. 故障后,SDK倒回了设备时钟. |
| `clockFetch` | 可选抓取只用于校正时钟 . |
| `config` | 可选版本的 scalar 配置 (`FactaConfigV1`) (中文(简体) ). |
| `runtime` | 可选的默认归档、无效归档、远程目的地和打印传输( E)`FactaRuntimeConfigV1`) (中文(简体) ). |

配置值不包括证书. 平面后遗症选项覆盖匹配的版本配置值 。 见 [节点指南](https://npmcn.com/package/%40facta-dte/api/guides/node.md) 或者说 [德诺向导](https://npmcn.com/package/%40facta-dte/api/guides/deno.md) 用于运行时间设置和环境权限.

## 参考钟

文档自己的日期和时间由Facta的服务器设定,从未由这个SDK设定. SDK的时钟对两个本地事物有关系: S3相容上传上的SigV4签名(S3拒绝从自己时间算起15分多签的请求, `RequestTimeTooSkewed`)和存档记录中的时间戳. `new Facta({ apiKey })` 保留一个 NTP 风格的参考时钟(`facta.clock`: 三分校正样品,最初使用,然后单调时钟回答局部,并只有当其不确定性超过500毫秒时再重新校正 `nextSyncAfterMs` 或当设备时间跳出。 与 S3 目标共享 `createS3ArtifactDestination({ ..., clock: facta.clock ?? false })`没有它,目的地就有自己的。 一个无法到达的时钟服务倒回了设备时钟. 见 [时钟指南](https://sdk.factadte.com/guias/reloj-de-referencia/)。 。 。 .

## 公共客户面

这个 `Facta` 客户端披露以下英语方法:

-   **状况和诊断:** `status`, (中文(简体) ), `diagnose`, (中文(简体) ), `getContract`, (中文(简体) ), `getStorageStatus`。 。 。 .
-   **目的地和目录如下:** `syncDestinations`, (中文(简体) ), `listCustomers`, (中文(简体) ), `getCustomer`, (中文(简体) ), `searchCustomers`, (中文(简体) ), `listProducts`, (中文(简体) ), `getProduct`, (中文(简体) ), `searchProducts`。 。 。 .
-   **Catalog 写作( 平面文本目录, 范围) `catalog:write`:** `createCustomer`, (中文(简体) ), `updateCustomer`, (中文(简体) ), `deactivateCustomer`, (中文(简体) ), `createProduct`, (中文(简体) ), `updateProduct`, (中文(简体) ), `deactivateProduct`。每个目录模式下的读取通过 API;服务器解析 `customerId` 编号 : `productId`见 [目录编写指南](https://npmcn.com/package/%40facta-dte/api/guides/catalog-write.md)。 。 。 .
-   **目录更改和webhooks( 镜片) `catalog:read`:** `listCatalogChanges`, (中文(简体) ), `createWebhook`, (中文(简体) ), `listWebhooks`, (中文(简体) ), `getWebhook`, (中文(简体) ), `updateWebhook`, (中文(简体) ), `deleteWebhook`, (中文(简体) ), `rotateWebhookSecret`, (中文(简体) ), `testWebhook`,以及接收方 `verifyWebhook` 编号 : `constructWebhookEvent` 编号 : `signWebhook`。记录一次读取一次 `revision`;通过它作为 `ifMatch` 改为 `updateCustomer` 编号 : `updateProduct`见 [网络用户指南](https://npmcn.com/package/%40facta-dte/api/guides/webhooks.md)。 。 。 .
-   **草稿(范围) `draft`:** `createDraft`, (中文(简体) ), `listDrafts`, (中文(简体) ), `getDraft`, (中文(简体) ), `getDraftByKey`, (中文(简体) ), `updateDraft` (单位:千美元)`version` 以 `If-Match`, (中文(简体) ), `cancelDraft` 财务报告和审定财务报表 `issueDraft`:给公司人员留一张发票,由其审查并签发. 一个拼错的字段又回来了 `draft.unknownFields` (草案中没有)。 见 [指南草案](https://npmcn.com/package/%40facta-dte/api/guides/drafts.md)。 。 。 .
-   **DTE 生命周期 :** `issue`, (中文(简体) ), `prepare`, (中文(简体) ), `sign`, (中文(简体) ), `getDocumentStatus`, (中文(简体) ), `listDocuments`, (中文(简体) ), `invalidate`, (中文(简体) ), `registerReturn`, (中文(简体) ), `listHolding`, (中文(简体) ), `downloadDocument`, (中文(简体) ), `getDocumentCopies`, (中文(简体) ), `retryDocumentStorage`。 。 。 .
-   **临时副本和确认(新):** `listUnconfirmedDocuments`, (中文(简体) ), `confirmDocumentStorage`, (中文(简体) ), `storeAndConfirmUnconfirmed`Facta 在您报告存储的文件2天后删除其临时加密副本,或者在封存后30天,如果没有人这样做;公司所有人从第1天起就被邮寄。 见 [临时副本](https://npmcn.com/package/%40facta-dte/api/guides/temporary-copy.md)。 。 。 .
-   **永久档案:** `issueAndArchive`, (中文(简体) ), `recoverOperation`, (中文(简体) ), `listPendingOperations`, (中文(简体) ), `invalidateAndArchive`, (中文(简体) ), `recoverInvalidation`, (中文(简体) ), `listPendingInvalidations`, (中文(简体) ), `replicateArchive`, (中文(简体) ), `diagnoseDestinations`。 。 。 .
-   **通过电子邮件和WhatsApp发送:** `issue(request, { deliver })`, (中文(简体) ), `deliverEmail`, (中文(简体) ), `deliverWhatsApp`, (中文(简体) ), `getDelivery`, (中文(简体) ), `waitForDelivery`. 发布从不等待交付;每个频道是一个单独的请求,带有5分钟的符号,故障报告为状态.
-   **本地打印 :** `print`。 。 。 .

全数 [方法参考](https://npmcn.com/package/%40facta-dte/api/guides/reference.md) 描述每种方法的输入,返回类型,证书范围,网络/局部效果,出错,以及重试或恢复行为.

## 安全发放和恢复

每个能够保留财政控制号的操作都需要一个稳定的 `idempotencyKey`。在超时后,用相同的请求重用相同的密钥;用该密钥更改的请求被拒绝. `AbortSignal` 停止本地等待/ 重复, 但无法证明服务器已经接受的请求已被取消 .

对于必须在进程重新启动后幸存的应用程序,使用 `issueAndArchive` 有坚固的档案, `operationId`,以及 `idempotencyKey`数字 :

```ts
import { Facta, type DteRequest } from "@facta-dte/api";
import { FileInvoiceArchive } from "@facta-dte/api/node";

const archive = await FileInvoiceArchive.open({
  directory: "./private-invoices",
  passphrase: process.env.FACTA_ARCHIVE_PASSPHRASE!,
});
const facta = new Facta({
  apiKey: process.env.FACTA_API_KEY!,
  signKey: process.env.FACTA_SIGN_KEY!,
  runtime: { archive },
});

const sale: DteRequest = {
  tipoDte: "01",
  items: [{ descripcion: "Sample item", cantidad: 1, precioUni: 10 }],
};
const result = await facta.issueAndArchive(sale, {
  includeTicket: false,
  operationId: "order-1042",
  idempotencyKey: "order-1042",
});
if (result.archive.state !== "complete") {
  // Fiscal success and archival status are separate. Keep the operation ID.
  await facta.recoverOperation("order-1042");
}
```

`issueAndArchive` 在财政请求之前存储不可更改的已解决的请求和操作身份。 它将服务器返回的确切签名的JSON和PDF存档,从JSON那里取出JWS,并且可选地要求只从支持它的API那里取出收据PDF. 使用 `includeTicket: false` 将 JSON、PDF 和 JWS 归档,而不要求票。 默认启用出票归档,需要配置 API `kind=ticket` PDF支持. 恢复在提出任何财政要求之前,先核实终点、API的关键身份、发行人和环境。 没有这种身份的遗留日记仍然可以检查,但不能自动重放.

存档是敏感数据 . `FileInvoiceArchive` 使用认证的加密和限制性本地文件权限;其密码口号必须独立于API,签名,以及金库证书. 将备份和保留置于应用程序的控制之下。 读取 [存储适配器](https://npmcn.com/package/%40facta-dte/api/guides/storage-adapters.md) 用于远程复制适配器和调节.

## 单独准备和签署

使用 `prepare` 财务报告和审定财务报表 `sign` 只有在人或批准制度在签署之前必须审查犬科文件时:

```ts
const prepared = await facta.prepare(sale, { idempotencyKey: "order-1042:prepare" });
// Review prepared.documento and prepared.totales without changing them.
const result = await facta.sign(prepared, { idempotencyKey: "order-1042:sign" });
```

准备保留一个控制号。 准备好的文件和标志必须不加修改地传递给 `sign`页:1. `prepare` 没有使用 `signKey`时 `sign` 已经 两种路由都需要一等键,API 范围按 API 键,而不是按路由: 对每一步使用不同的键(绝不重复使用) `prepare` 键 `sign`,API拒绝使用 `idempotency_key_reuse`) (中文(简体) ). 见 [编写/签名指南](https://npmcn.com/package/%40facta-dte/api/guides/prepare-sign.md)。 。 。 .

## DTE 类型和财政有效载荷

导出类型Script 类型包括 `DteRequest`, (中文(简体) ), `IssueResult`, (中文(简体) ), `PreparedDte`, (中文(简体) ), `DocumentStatus`, (中文(简体) ), `InvalidationRequest`, (中文(简体) ), `InvalidationResult`, (中文(简体) ), `DteType`, (中文(简体) ), `Recipient`, (中文(简体) ), `Address`, (中文(简体) ), `LineItem`, (中文(简体) ), `Totals`,以及 `DtePage`DTE 请求类型构成一个按不变键的联盟 `tipoDte` 字段,覆盖 `"01"`, (中文(简体) ), `"03"`, (中文(简体) ), `"05"`, (中文(简体) ), `"06"`, (中文(简体) ), `"11"`,以及 `"14"`。 。 。 .

该类型系统帮助构建有效载荷,但并不取代服务器侧税验证. SDK没有当地的增值税引擎,也不推断财政总额. 对于目录支持的价格,项目的增值税基础必须与DTE类型相匹配;提供明确的 `precioUni` 在文档的预期基础 推翻目录价格.

## 目录和目的地快照

`syncDestinations()` 使用 `unlockKey`。它不创建或更新服务器记录,也不将文物写入存储目的地。 由于0.6没有目录快照: `customerId` 编号 : `productId` 由服务器解决,目录读取名为 API.

`issue()` 从不写到存储 。 与 `unlockKey` 和已发表的快照, `issueAndArchive()` 财务报告和审定财务报表 `recoverOperation()` 并复制合法的 JSON 和 PDF 到您的同步目的地 在 Facta 的峡谷 `DTE/…/YYYY/MM/<numeroControl>` 路径( 选择退出) `replicate: false`),报告他们写给Facta的每份副本(一份报告,不是一份核实),以及表面问题作为非投掷 `warnings`。见 [每个模式都做什么](https://npmcn.com/package/%40facta-dte/api/guides/storage-adapters.md#where-documents-go-each-mode)。 。 。 .

-   [读取目录和 id 分辨率](https://npmcn.com/package/%40facta-dte/api/guides/catalog.md)
-   [创建、编辑和关闭客户端和产品](https://npmcn.com/package/%40facta-dte/api/guides/catalog-write.md)
-   [存储适配器](https://npmcn.com/package/%40facta-dte/api/guides/storage-adapters.md)
-   [临时拷贝、确认书和急救店](https://npmcn.com/package/%40facta-dte/api/guides/temporary-copy.md):持有1小时,2天/30天临时副本,所有者邮件,以及如何报告所储存的文件
-   [紧急保障](https://npmcn.com/package/%40facta-dte/api/guides/emergency.md)数字 : `runtime.emergencyStore` 当 Facta 无法持久存储时, 将 JSON 和 PDF 除外( 它没有确认; 报告有)
-   [节点集成](https://npmcn.com/package/%40facta-dte/api/guides/node.md)
-   [德诺融合](https://npmcn.com/package/%40facta-dte/api/guides/deno.md)

SDK本身不发送任何信息:电子邮件和WhatsApp的发送由API在您标记频道后进行. 它不在当地签署,不选择签署证书,也不取代API的财政合同.

## Archivo DTE(接收器得到的)

密封结果携带 `archivoDte`: Archivo DTE 准确的 UTF-8 文本,即签名文件加 `firmaElectronica` (JWS,字节换字节)和 `selloRecibido`。这是给客户或会计师的文件。 在尚未加封的紧急情况下,没有封条. `archivoJson` 不变(所储存的原件, `{codigoGeneracion, ambiente, jws}`);继续归档.

```ts
import { archivoDteOf } from "@facta-dte/api";

const result = await facta.issue(sale);
if (result.estado === "sellado") {
  // `archivoDte` when the API serves it; otherwise built from documento + jws + selloRecibido.
  const archivo = archivoDteOf(result);
}
const file = await facta.downloadDocument(code, "json");               // Archivo DTE (default)
const original = await facta.downloadDocument(code, "json", { raw: true }); // stored bytes
console.log(file.jsonFormat, original.jsonFormat);                     // "archivo-dte" "raw"
```

`downloadDocument(code, "json")` 现在默认返回 Archivo DTE 并报告 `jsonFormat` 从 `X-Facta-Json-Format` 页眉; `{ raw: true }` 返回存储的正本,并且只对 `json`。没有封条的文档答案 `409 not_sealed`; 使用 `raw: true` 为它的原作。 反应接收和下载按钮将Archivo DTE作为“Descargar JSON ” ;“JSON 原创( raw ) ” `rawJson` prop,服务器处理器只有在 `capabilities.rawJson` 实值 `true`。本地复制品和复制品仍然保存着它们之前所储存的.

## 错误

经认证的 API 失败使用 `FactaError`,有一个稳定 `code`, HTTP 软件 `status`保险 `details`, (中文(简体) ), `isRejection`选择 `spent` 控制数字信息。 分会 `code`,而不是本地化消息文本。 本地验证可能投出 `TypeError` 或者说 `RangeError`;归档和存储适配器可以抛出自己打出的错误. 类似证书的值会从 API 错误细节中校正 .

只用相同的同能键重试同一请求. `operation_outcome_unknown` 并且归档完整性失败需要检查或核对;它们不授权发布替换的DTE。 这个 [方法参考](https://npmcn.com/package/%40facta-dte/api/guides/reference.md) 包括每项公共行动的成果和恢复指导,以及 [错误目录](https://npmcn.com/package/%40facta-dte/api/guides/errors.md) 列出每个错误代码及其 HTTP 状态、 重试行为和要做什么 .

## 实例和检查

输入的示例 [`examples/`](https://npmcn.com/package/%40facta-dte/api/examples/dte-types.ts). 该套件的测试套件使用德诺. `pack:check` 建立节点无害环境管理捆绑和申报,将包装入一个临时目录,然后对照所包装的产出检查新鲜节点和德诺消费者.

```sh
pnpm test
pnpm pack:check
```

## AI 编码代理的代理技能

[`skills/facta-dte-api/`](https://npmcn.com/package/%40facta-dte/api/skills/facta-dte-api/SKILL.md) 是一种可安装的代理技能( e)`SKILL.md` + 引用 + 类型检查的启动模板),它教给一个编码代理如何将这个SDK和Facta DTE HTTP API正确整合:密钥,DTE类型,一能性,应急性,文件和交付,出错和生产核对表. 安装和下载指令(英文和西班牙文): [技能/README.md](https://npmcn.com/package/%40facta-dte/api/skills/README.md)。 。 。 . `pnpm skill:pack` 正在建设 `dist/facta-dte-api-skill.zip`。 。 。 .

## 指南

每个向导在 `guides/`英文和西班牙文。 两种反应指南只有英语.

| 专题 | 联合国 | 西班牙语Name |
| --- | --- | --- |
| 方法参考:每一种公共方法 | [页:1](https://npmcn.com/package/%40facta-dte/api/guides/reference.md) | [参考文献](https://npmcn.com/package/%40facta-dte/api/guides/reference.es.md) |
| 节点集成 | [节点.md](https://npmcn.com/package/%40facta-dte/api/guides/node.md) | [节点s.md](https://npmcn.com/package/%40facta-dte/api/guides/node.es.md) |
| 德诺融合 | [(单位:千美元)](https://npmcn.com/package/%40facta-dte/api/guides/deno.md) | [(单位:千美元)](https://npmcn.com/package/%40facta-dte/api/guides/deno.es.md) |
| 错误目录: 每个代码, HTTP 状态, 重试 | [错误 md](https://npmcn.com/package/%40facta-dte/api/guides/errors.md) | [错误.s.md](https://npmcn.com/package/%40facta-dte/api/guides/errors.es.md) |
| 目 录(续) | [专有能力.md](https://npmcn.com/package/%40facta-dte/api/guides/idempotency.md) | [一能性.es.md](https://npmcn.com/package/%40facta-dte/api/guides/idempotency.es.md) |
| 待发文件:清单和重试,不印发两次 | [待决文件. md](https://npmcn.com/package/%40facta-dte/api/guides/pending-documents.md) | [待定文档.es.md](https://npmcn.com/package/%40facta-dte/api/guides/pending-documents.es.md) |
| 准备,审查,然后签署 | [备注](https://npmcn.com/package/%40facta-dte/api/guides/prepare-sign.md) | [备注](https://npmcn.com/package/%40facta-dte/api/guides/prepare-sign.es.md) |
| Archivo DTE(接收器得到的) | [数据](https://npmcn.com/package/%40facta-dte/api/guides/archivo-dte.md) | [数据](https://npmcn.com/package/%40facta-dte/api/guides/archivo-dte.es.md) |
| 通过电子邮件和WhatsApp发送 | [交货](https://npmcn.com/package/%40facta-dte/api/guides/delivery.md) | [交付.es.md](https://npmcn.com/package/%40facta-dte/api/guides/delivery.es.md) |
| 支付,全球折扣`descuentoGlobal`),非税线(`noGravado`),出口,预扣所得税 | [支付-出口-retta.md](https://npmcn.com/package/%40facta-dte/api/guides/payments-export-renta.md) | [支付-出口-retanta.es.md](https://npmcn.com/package/%40facta-dte/api/guides/payments-export-renta.es.md) |
| 回返(Evento de Redrono) | [返回活动md](https://npmcn.com/package/%40facta-dte/api/guides/return-event.md) | [返回活动](https://npmcn.com/package/%40facta-dte/api/guides/return-event.es.md) |
| 诊断, `diagnoseDestinations` | [诊断](https://npmcn.com/package/%40facta-dte/api/guides/diagnose.md) | [诊断](https://npmcn.com/package/%40facta-dte/api/guides/diagnose.es.md) |
| 区域定位 | [区域](https://npmcn.com/package/%40facta-dte/api/guides/region.md) | [区域.s.md](https://npmcn.com/package/%40facta-dte/api/guides/region.es.md) |
| 调试时间 | [时间 . md](https://npmcn.com/package/%40facta-dte/api/guides/timings.md) | [时间 . s. md](https://npmcn.com/package/%40facta-dte/api/guides/timings.es.md) |
| 参考钟 | [参考时间:](https://npmcn.com/package/%40facta-dte/api/guides/reference-clock.md) | [参考点.s.md](https://npmcn.com/package/%40facta-dte/api/guides/reference-clock.es.md) |
| 读取目录和 id 分辨率 | [目录. md](https://npmcn.com/package/%40facta-dte/api/guides/catalog.md) | [目录.es.md](https://npmcn.com/package/%40facta-dte/api/guides/catalog.es.md) |
| Catalog 写作( 客户和产品) | [目录- write.md](https://npmcn.com/package/%40facta-dte/api/guides/catalog-write.md) | [目录- write.es.md](https://npmcn.com/package/%40facta-dte/api/guides/catalog-write.es.md) |
| 目录更改和网络选择 | [网络用户](https://npmcn.com/package/%40facta-dte/api/guides/webhooks.md) | [网络用户](https://npmcn.com/package/%40facta-dte/api/guides/webhooks.es.md) |
| 草稿 | [草案](https://npmcn.com/package/%40facta-dte/api/guides/drafts.md) | [草案](https://npmcn.com/package/%40facta-dte/api/guides/drafts.es.md) |
| 存储适配器 | [存储适应器. md](https://npmcn.com/package/%40facta-dte/api/guides/storage-adapters.md) | [储存适应器](https://npmcn.com/package/%40facta-dte/api/guides/storage-adapters.es.md) |
| 临时副本和确认书 | [临时拷贝](https://npmcn.com/package/%40facta-dte/api/guides/temporary-copy.md) | [临时副本.s.md](https://npmcn.com/package/%40facta-dte/api/guides/temporary-copy.es.md) |
| 紧急保障 | [紧急情况](https://npmcn.com/package/%40facta-dte/api/guides/emergency.md) | [紧急情况](https://npmcn.com/package/%40facta-dte/api/guides/emergency.es.md) |
| 无头浏览器客户端( E)`@facta-dte/api/browser`(中文(简体) ) | [浏览器. md](https://npmcn.com/package/%40facta-dte/api/guides/browser.md) | [浏览器.es.md](https://npmcn.com/package/%40facta-dte/api/guides/browser.es.md) |
| React 的签名窗口 | [反应.md](https://npmcn.com/package/%40facta-dte/api/guides/react.md) | —— 说 |
| 签名窗口: 服务器侧和存储 | [反应-服务器.md](https://npmcn.com/package/%40facta-dte/api/guides/react-server.md) | —— 说 |

## 文件语文

该存放处保存西班牙文文件 [`README.es.md`](https://npmcn.com/package/%40facta-dte/api/README.es.md)英文指南 [方法参考](https://npmcn.com/package/%40facta-dte/api/guides/reference.md) 并引导。 每个指南都与西班牙对应的链接.

### 公众现场测试报告

分组直播工作流程只发布公关和工作中的验证表 总结。 它核实签发的测试发票,在JSON和PDF上签字以保存 和一个加密的临时归档,然后删除归档。 从不上传 \* 发票文件或出版发行人/客户识别码、生成码, 控制号、原始API错误或断言有效载荷.

文档查询和列出接收器元数据在Facta应用程序中加密、导入或恢复的文档,而API没有公司密钥,则可能无效。 SDK 保存为无效; 当前目录客户无法建立历史接收器 . `unlockKey` 只打开已公布的目录/目的地快照, 而不是历史发票接收符.

整个运行现场工作流程要求,对于BYOS的设置,其所有者公布的目的地快照在签发测试发票之前打开。 已准备好的只管理设置不需要 BYOS 的快照 。 无法获取的快照失败了运行; 库的发布与遗留状态响应的兼容性不会放弃此集成门 .

### 可执行的工作流程实例和存储失败

运出 [工作流程实例](https://npmcn.com/package/%40facta-dte/api/examples/workflows.ts) 涵盖管理下的排放, 管理加加密本地/ BYOS 副本, 重新启动恢复, 目录引用, 58毫米车票,指定检验无效和老服务器诊断. 这个 [6个DTE请求实例](https://npmcn.com/package/%40facta-dte/api/examples/dte-types.ts) 输入固定模板 : 替换接收方占位符,并提供适当封存的发行方 实时使用前的注释参考。 进口货物不从事财政工作.

安装 `@facta-dte/api`,将示例复制到您的项目中,并呼叫 明确导出函数。 举个小例子:

```sh
node --experimental-strip-types --input-type=module -e "import { main } from './examples/hola-factura.ts'; await main();"
deno eval "import { main } from './examples/hola-factura.ts'; await main();"
```

设置测试 API 密钥, 明确 API URL并稳定 `ERP_ORDER_ID` 先说 失踪 配置在发行前停止最小示例. `pack:check` 编译 所有已运出实例并针对合成固定装置执行功能 在节点/德诺使用已打包的软件包。 这证明了实例兼容性; 实际的财政先决条件仍然是单独的验证门.

错误的存储收据并不能抵消财政上的成功: `storageErrorCode` 实值 `storage_contract_invalid`,而无效的收据被省略。 文件 归档持续了这一状况,并包括在待定的作业中,直到 修理提供有效收据。 永远不要用新的财政身份重新尝试. 目前的存储能力有缺陷的阻断诊断;没有更古老的路径 仍明确不详。 有管理的只有准备使BYOS同步 在签名和请求目录引用时保留其检查.

中转直播套房需要有管理的准备,核实耐用JSON/PDF 准确的内含字节的收据 从管理下的存储器读回来, 重放原始的一能键,只修复发票和检查 储存会计保持不变。 它只发布固定的结果标签. 车票/有效证和6个财政变体仍需明确指定 固定装置及其在实际支持索赔之前的财政先决条件.

使用 `downloadDocument(generationCode, "pdf", { source: "managed" })` 需要管理好的 JSON/PDF 副本而无需背书。 本地出票请求拒绝此选项; 一个旧服务器, 没有源文件返回 `storage_unsupported`。默认下载顺序不变.

## 发布自动化

维护者从 `publish.yml` GitHub 动作工作流程 `Facta-DTE/facta-api-sdk` 使用 npm 信任出版(OIDC),不保存 npm 发布符. 受信任的出版商必须允许 `npm publish`。 。 。 . A 类 `v<package-version>` 标记触发测试、包装消费者验证和 出版物。 标记的承诺必须属于 `main` 匹配 `package.json`。 。 。 . 使用稳定版本 `latest`;预放出使用其预放出标记.

合并并验证释放 `main`,然后按下新版本标签。 别动 或尝试重印已出版的版本。 工作流程 直接发布; 没有单独的 npm 阶段- 包装批准步骤 .

## 常见问题

### @facta-dte/api 是什么？

萨尔瓦多Facta电子发票API\(DTE\)的TypeScript客户端\.

### 如何安装 @facta-dte/api？

在项目目录运行 npm install @facta-dte/api，或使用 pnpm add / yarn add / bun add。

### @facta-dte/api 支持 TypeScript 吗？

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

### @facta-dte/api 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @facta-dte/api 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @facta-dte/api 可以商用吗？

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

### @facta-dte/api 的下载量有多少？

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

### @facta-dte/api 还在维护吗？

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