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

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

读取 西班牙语读取全数 方法参考 记录每种公用方法的论据、返回值、所需范围、副作用、错误、重复和恢复行为。 这个 公布的API合同 hTTP 字段和响应仍然具有权威性.

软件包和源 : 无 @facta-dte/api • 妇女 公共 GitHub 仓库。 。 。 .

版本选择 : 此源检出已放行 0.6.0,稳定版本(npm) latest) (中文(简体) ). 这个 npm 登记 对已出版的版本和发行标记具有权威性。 确认您已安装的已发布版本在使用前包含一个方法; 以装入的检出来验证纯源能力 .

端点选择 : FACTA_PRODUCTION_BASE_URL 指定默认使用的生产终点。 使用 baseUrl: FACTA_STAGING_BASE_URL 选择装配,或提供自定义终点。 官方的 PHP SDK 也可以在 facta-dte/api。 。 。 .

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

许可证 : 麻省理工学院. 见 自由主义。 。 。 .

运行时间支持

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_ 启动应用程序的密钥 .

快开始

# 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

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,但需要和解. 在回应不确定后,不要提交带有新等同键的销售.

全权证书和配置

配置值不包括证书. 平面后遗症选项覆盖匹配的版本配置值 。 见 节点指南 或者说 德诺向导 用于运行时间设置和环境权限.

参考钟

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

公共客户面

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

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

全数 方法参考 描述每种方法的输入,返回类型,证书范围,网络/局部效果,出错,以及重试或恢复行为.

安全发放和恢复

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

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

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,签名,以及金库证书. 将备份和保留置于应用程序的控制之下。 读取 存储适配器 用于远程复制适配器和调节.

单独准备和签署

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

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) (中文(简体) ). 见 编写/签名指南。 。 。 .

DTE 类型和财政有效载荷

导出类型Script 类型包括 DteRequest, (中文(简体) ), IssueResult, (中文(简体) ), PreparedDte, (中文(简体) ), DocumentStatus, (中文(简体) ), InvalidationRequest, (中文(简体) ), InvalidationResult, (中文(简体) ), DteType, (中文(简体) ), Recipient, (中文(简体) ), Address, (中文(简体) ), LineItem, (中文(简体) ), Totals,以及 DtePageDTE 请求类型构成一个按不变键的联盟 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。见 每个模式都做什么。 。 。 .

• 读取目录和 id 分辨率
• 创建、编辑和关闭客户端和产品
• 存储适配器
• 临时拷贝、确认书和急救店:持有1小时,2天/30天临时副本,所有者邮件,以及如何报告所储存的文件
• 紧急保障数字 : runtime.emergencyStore 当 Facta 无法持久存储时, 将 JSON 和 PDF 除外( 它没有确认; 报告有)
• 节点集成
• 德诺融合

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

Archivo DTE(接收器得到的)

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

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。 这个 方法参考 包括每项公共行动的成果和恢复指导,以及 错误目录 列出每个错误代码及其 HTTP 状态、 重试行为和要做什么 .

实例和检查

输入的示例 examples/. 该套件的测试套件使用德诺. pack:check 建立节点无害环境管理捆绑和申报,将包装入一个临时目录,然后对照所包装的产出检查新鲜节点和德诺消费者.

pnpm test
pnpm pack:check

AI 编码代理的代理技能

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

指南

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

文件语文

该存放处保存西班牙文文件 README.es.md英文指南 方法参考 并引导。 每个指南都与西班牙对应的链接.

公众现场测试报告

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

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

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

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

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

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

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 阶段- 包装批准步骤 .