跳转到内容
开发者文档
指南Partner API v1

Partner API：接入商户

面向将客户企业接入 VCR.AM 的集成商：按 TIN 获取访问权限、创建收银机、向税务局办理证书、激活并开具收据。

Partner API 参考
所有接口、请求与响应，均由 API 本身生成。

访问权限如何运作

商户始终是其企业在 VCR 中的所有者。您基于对某一企业的授权（grant）行事，所有者可随时撤回。一个合作伙伴密钥即可访问所有已向您授权的企业。

您的每项操作都会以合作伙伴名称和所用密钥记录在该企业的操作日志中，所有者随时可以看到谁做了什么。

发出第一个请求之前

  1. 我们将您的 VCR 账户加入合作伙伴团队，您会收到一封列有以下步骤的邮件。
  2. 由有权代表贵公司签署合同的人接受合作伙伴条款，只需一次。凭商户书面授权自行认证访问权限时需要它；请所有者确认则无需。 接受合作伙伴条款
  3. 团队成员在合作伙伴中心签发 API 密钥。密钥只显示一次；请在 X-API-Key 请求头中发送。 打开合作伙伴中心

检查密钥：GET /whoami 会返回合作伙伴、密钥，以及当前条款是否已被接受。

curl
curl https://vcr.am/api/partner/v1/whoami \
  -H "X-API-Key: $VCR_PARTNER_KEY"

1. 接入企业

使用 POST /entities 并提供商户的 TIN 来申请访问权限。如果 VCR 尚无该 TIN，会在国家登记簿中查找并创建该企业。访问权限基于以下两种依据之一。

由所有者确认

所有者会收到一封含一键确认链接的邮件，有效期 7 天。在其点击之前，授权处于 pending 状态。若该企业在 VCR 中已有所有者，请不要传 owner：请求会发给其现有所有者，而不是您指定的地址。

curl
curl -X POST https://vcr.am/api/partner/v1/entities \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "01234567",
    "access": {
      "basis": "owner_confirmation",
      "owner": { "email": "owner@merchant.am", "language": "hy" }
    }
  }'

由您认证

如果您与商户的合同以书面形式授权您，请引用该合同，授权将立即变为 active。endsOn 是授权书所载期限的最后一天，自 signedOn 起不超过三年；若未载明期限，请省略该字段，授权自签署之日起有效一年。

curl
curl -X POST https://vcr.am/api/partner/v1/entities \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "01234567",
    "access": {
      "basis": "partner_attestation",
      "merchantAuthorization": {
        "reference": "Service agreement No. 17, clause 4.2",
        "signedOn": "2026-10-01",
        "endsOn": "2027-09-30"
      }
    }
  }'

授权处于 pending 时，对于由您引入 VCR 的企业，您已可以创建收银机、获取 CSR 并上传证书；激活和开具收据须等待所有者确认。对于在您之前已存在于 VCR 的企业，在授权变为 active 之前不允许任何操作。

如需自行放弃授权，请调用 DELETE /entities/{entityId}/grant：它会取消所有者尚未答复的请求，或终止已生效的授权。合作伙伴条款要求在客户授权结束后三个工作日内完成。随后会收到原因为 relinquished 的 grant.ended。

curl
curl -X DELETE https://vcr.am/api/partner/v1/entities/42/grant \
  -H "X-API-Key: $VCR_PARTNER_KEY"

2. 创建收银机

POST /entities/{entityId}/registers 会创建一台收银机，生成新的密钥对以及用于 101 号申请的 CSR。tradingPlatformName 是申请表第 5.4 项，会打印在收据上；website 是第 5.3 项。

curl
curl -X POST https://vcr.am/api/partner/v1/entities/42/registers \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tradingPlatformName": "Merchant Cafe Abovyan",
    "website": "https://cafe.merchant.am",
    "mode": "production"
  }'

超时后重试会创建第二台收银机，因此请发送 Idempotency-Key 请求头（UUID）：重试将返回第一次调用创建的收银机，并带有 Idempotent-Replay: true。

3. 获取证书

GET /registers/{registerId}/application 返回 101 号申请需要填写的内容以及需附上的 CSR。

curl
curl https://vcr.am/api/partner/v1/registers/104/application \
  -H "X-API-Key: $VCR_PARTNER_KEY"
# -> { "tin": "...", "website": "...", "applicationName": "...", "csr": "-----BEGIN CERTIFICATE REQUEST-----..." }

纳税人在税务局门户提交 101 号申请，并用本人的电子签名签署，税务局随后签发证书。请以 PEM 格式上传。证书须链接到税务局根证书、包含该企业的 TIN 并与收银机的 CSR 匹配；重复上传同一证书不会产生任何变化。证书为收银机赋予注册号（CRN）。

curl
curl -X PUT https://vcr.am/api/partner/v1/registers/104/certificate \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile pem certificate.crt '{certificate: $pem}')"

沙盒收银机从沙盒证书机构获取证书，无需 101 号申请：

curl
curl -X POST https://vcr.am/api/partner/v1/registers/104/sandbox-certificate \
  -H "X-API-Key: $VCR_PARTNER_KEY"
# -> { "certificate": "-----BEGIN CERTIFICATE-----...", "crn": "99123456" }
# Upload it with PUT /registers/104/certificate, as you would SRC's.

4. 激活

激活需要 active 状态的授权。为收银机的第一个部门选择税制：vat、vat_exempt、turnover_tax 或 micro_enterprise。税制会打印在每张收据上，所有者会收到通知您所做选择的邮件。重复调用是安全的。

curl
curl -X POST https://vcr.am/api/partner/v1/registers/104/activation \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taxRegime": "turnover_tax" }'

GET /registers/{registerId} 显示收银机所处的步骤：

status下一步
awaiting_certificate附上 CSR 提交 101 号申请，并上传税务局签发的证书；沙盒收银机从沙盒证书机构获取。
awaiting_activation激活。
departments_pending税务局已激活收银机，但尚未接受其部门。请再次激活。
active可开具收据。

5. 开具收据

销售、退款、收银员和部门均通过常规 API /api/v1 处理，使用合作伙伴密钥，并在 VCR-Register 请求头中用 id 指定收银机。缺少该请求头返回 400；无权访问的收银机返回 404；仍在等待所有者确认的授权返回 403。

curl
# The regular API, with the partner key and the register named in a header.
curl https://vcr.am/api/v1/cashiers \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "VCR-Register: 104"

接口与使用收银机自身密钥时相同： API 文档

Webhook

在合作伙伴中心最多添加 5 个地址；每个地址都必须是可从公网访问的 https 地址。每个请求均按 Standard Webhooks 规范签名（webhook-id、webhook-timestamp、webhook-signature）：请用该地址的密钥校验签名，密钥仅在添加时显示一次。

事件触发时机
grant.activated您对某企业的授权已生效：所有者已确认，或由您认证。
grant.ended您的授权已终止。reason 为 revoked（所有者撤回）、relinquished（您主动放弃）或 expired（无人按时确认，或授权期限届满）。
register.activated税务局激活了您有权访问的企业的收银机。
register.activation_failed税务局拒绝激活收银机。
register.closed收银机已关闭。

投递失败时会在约一天内重试。各事件的请求体见参考文档中的 webhooks 部分。可在合作伙伴中心发送测试事件来检查地址。

错误

拒绝时返回 JSON，包含 error（供人阅读的说明）和 code（供程序使用的稳定代码）。代码含义不会改变，但可能新增代码，因此请按 HTTP 状态处理未知代码。参考文档列出了每个接口的状态码。

关闭收银机

POST /registers/{registerId}/closure 会在 VCR 中关闭收银机：其密钥停止工作，并发送 register.closed。

curl
curl -X POST https://vcr.am/api/partner/v1/registers/104/closure \
  -H "X-API-Key: $VCR_PARTNER_KEY"

税务局不会收到通知：注销收银机须由纳税人本人在税务局门户提交申请。 如何注销收银机