开发者文档

通过任何技术栈向亚美尼亚税务机关注册销售、预付款和退款。

基准 URLhttps://vcr.am/api/v1

快速开始

通过单次 POST 请求注册销售。

bash

curl https://vcr.am/api/v1/sales \
  -H "X-API-Key: $VCR_AM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cashier": { "id": 1 },
    "items": [{
      "offer": { "externalId": "SKU-001" },
      "department": { "id": 1 },
      "quantity": "1",
      "price": "20000",
      "unit": "pc"
    }],
    "amount": { "nonCash": "20000" },
    "buyer": {
      "type": "individual",
      "receipt": { "email": "buyer@example.com", "language": "en" }
    }
  }'

无需税务凭证即可开始

沙盒收银机在创建时立即获得注册号——无需与税务机关交换证书，无需等待。基础 URL、接口和密钥机制完全相同；唯一的区别是收据带有 TEST 标记且从不上报。

1在仪表板中打开「虚拟收银机」，点击「创建虚拟收银机 (VCR)」并选择「沙盒收银机」。可按需创建任意数量。
2在该收银机上签发 API 密钥。密钥仅属于一台收银机，因此来自生产收银机的密钥仍会返回 403。
3使用相同的基础 URL 调用相同的接口。准备好正式上线时，创建生产收银机并替换密钥。

专为生产环境集成而构建

基于 JSON 的 REST

您可以从任何语言、框架或运行时调用的无状态 JSON 端点。

类型化的 Node.js 和 PHP SDK

npm 和 Packagist 上的端到端类型化客户端，可直接放入您的 Node.js 或 PHP 服务器代码中。

API 密钥身份验证

通过您的仪表板管理有范围限制、可轮换的 API 密钥。

完整的收银机 API

通过单一、一致的界面处理销售、预付款、退款和收据。

您的系统必须提供的内容

在进行对接之前，请确保每笔销售都包含国家税务局（SRC）所需的数据。

分类器编码

商品的商品编码或服务的活动编码。

计量单位

公斤、件、平方米、小时、服务、工作等。

部门 ID

销售在收银机中登记的位置 — 也决定收据上打印的税制。可选：不传时该行将采用其商品所属的部门。

收银员 ID

注册销售的人员。

身份验证

每个请求都必须在 X-API-Key 请求头中包含您的 API 密钥。唯一的例外是 GET /exchange-rate，该接口公开开放，无需密钥。

X-API-Key: your_api_key

在您的收银机设置中生成和轮换 API 密钥。

对您的 API 密钥保密

切勿在客户端代码、公共代码库或共享日志中泄露它。如果泄露，请立即从您的收银机设置中进行轮换重置。

错误

错误使用标准 HTTP 状态码以及包含详细信息的 JSON 主体。

状态	名称	触发时机
400	错误请求	载荷格式错误或架构验证失败。
401	未授权	API 密钥缺失或无效。
403	禁止访问	该收银机尚不能上报文件：未获得注册号，或未在税务机关激活。
404	未找到	所请求的资源不存在。
500	内部错误	我们方发生意外故障。请使用指数退避重试。