Arcanum 文档

Arcanum 把 ARCA SOAP Web 服务里那些脏活累活——构建 TRA、签名、登录 WSAA、缓存、封装 SOAP 信封、解析 XML——变成一次干净的 REST 调用。你用 JSON 提问；其余的交给 Arcanum。

curl -X POST https://your-arcanum/api/ws/padron_a5/getPersona_v2 \
  -H "X-API-Key: YOUR_KEY" -H "Content-Type: application/json" \
  -d '{ "cuit": "20111111112", "params": { "idPersona": "20999999993" } }'

它如何运作

100% 本地 WSAA 签名

TRA 以 CMS/PKCS#7 形式在内存中、在你的容器内部用 node-forge 签名——没有任何会调用第三方的 SDK。私钥以 AES-256-GCM 加密形式存储于 Postgres；主密钥仅存在于环境变量中。

缓存令牌，自我修复

访问票据（Token + Sign）按 CUIT + 服务 + 环境进行缓存，并带有咨询锁，因此两个同时发起的请求绝不会触发两次登录。一个守护进程会在其过期前续期，而一旦 ARCA 拒绝了过期令牌， Arcanum 会透明地重试。

可编辑目录 + 通用引擎

每一项 ARCA 服务都存在于一份声明式目录中。POST /api/ws/{service}/{operation} 可用一个 JSON 请求体调用任意服务的任意操作。ARCA 经常变更端点——超级管理员可从界面编辑它们，保存且留有审计，无需重新部署。

多客户、多环境

从一个实例管理多个 CUIT，并从界面在测试环境与生产环境之间切换——热切换且持久化，无需触碰变量或重新部署。

REST 接口

通用引擎 — POST /api/ws/{service}/{operation} 可触达任意目录操作。Arcanum 会为你构建信封并解析认证。
丰富的模块 — 最常用的服务（开票、登记册查询等）还提供符合人体工学的 REST 端点，带有校验和干净的 JSON 响应。
API key — 每次调用都携带 X-API-Key。Arcanum 的设计是部署在你自己的网络上，或置于带 TLS 的反向代理之后。

开票

开票模块开具并取得 CAE，支持自动编号，处理带关联凭证的贷记与借记凭证，事先校验金额，强制幂等性（不会重复出 CAE），并生成一份带 ARCA 二维码的合法 PDF。重打与查询都只需一次调用。

证书生命周期

Arcanum 生成 CSR；你将其上传到 ARCA，再把 .crt 粘贴回来。从此私钥在静态存储时保持加密，面板还会就即将过期的证书向你发出提醒。

从 n8n 自动化

由于接口就是带 API key 的纯 REST，把 ARCA 接入一个 n8n 流程（或任何系统）只需一次 HTTP 请求——无需 SOAP，无需 SDK。