Partner API: подключение мерчантов

Владельцем компании в VCR остаётся мерчант. Вы действуете по доступу (grant) к конкретной компании, который владелец может отозвать в любой момент. Один ключ партнёра работает со всеми компаниями, которые дали вам доступ.

Всё, что вы делаете, попадает в журнал действий компании с названием партнёра и ключом, так что владелец всегда видит, кто и что сделал.

1. Мы добавляем ваш аккаунт VCR в команду партнёра. Вам приходит письмо с этими шагами.
2. Человек, который вправе подписывать договоры за вашу компанию, один раз принимает Условия для партнёров. Они нужны, чтобы заверять доступ по письменному поручению мерчанта; запросить подтверждение у владельца можно и без них. Принять Условия
3. Участник команды выпускает API-ключ в кабинете партнёра. Ключ показывается один раз; передавайте его в заголовке X-API-Key. Открыть кабинет партнёра

Проверьте ключ: GET /whoami вернёт партнёра, ключ и то, приняты ли текущие Условия.

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

Запросите доступ через POST /entities с ИНН мерчанта. Если VCR ещё не знает этот ИНН, компания находится в госреестре и создаётся. Доступ держится на одном из двух оснований.

Подтверждает владелец

Владелец получает письмо со ссылкой в один клик, она действует 7 дней. Пока он не нажал, доступ в состоянии pending. Если у компании в VCR уже есть владельцы, не передавайте owner: запрос уйдёт её текущим владельцам, а не на адрес, который назовёте вы.

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 -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. Вызов отменяет запрос, на который владелец ещё не ответил, или прекращает действующий доступ. Условия для партнёров требуют сделать это в течение трёх рабочих дней после окончания поручения клиента. Придёт grant.ended с причиной relinquished.

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

POST /entities/{entityId}/registers создаёт кассу с новой парой ключей и CSR для заявления 101. tradingPlatformName — поле 5.4 заявления, оно печатается на чеках; website — поле 5.3.

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.

GET /registers/{registerId}/application возвращает, что вписать в заявление 101, и CSR, который к нему прикладывается.

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. Он должен вести к корневому сертификату налоговой, содержать ИНН этой компании и соответствовать CSR кассы; повторная загрузка того же сертификата ничего не меняет. Сертификат даёт кассе регистрационный номер (CRN).

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 -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.

Для активации нужен доступ active. Выберите налоговый режим первого отдела кассы: vat, vat_exempt, turnover_tax или micro_enterprise. Он печатается на каждом чеке, и владельцам приходит письмо с вашим выбором. Повторный вызов безопасен.

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} показывает, на каком шаге касса:

Продажи, возвраты, кассиры и отделы идут через обычный API, /api/v1, с ключом партнёра. Касса указывается по id в заголовке VCR-Register. Без заголовка ответ 400; касса, к которой у вас нет доступа, — 404; доступ, который ещё ждёт владельца, — 403.

# 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

Добавьте до 5 адресов в кабинете партнёра; каждый должен быть https и доступен из интернета. Каждый запрос подписан по спецификации Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature): проверяйте подпись секретом адреса, он показывается один раз при добавлении.

Неудачная доставка повторяется в течение примерно суток. Тело каждого события описано в справочнике, в разделе webhooks. Из кабинета можно отправить тестовое событие, чтобы проверить адрес.

Отказ приходит JSON с полями error — фраза для человека — и code — стабильный код для программы. Смысл кодов не меняется, но могут появляться новые, поэтому незнакомый код обрабатывайте по HTTP-статусу. Статусы каждого метода перечислены в справочнике.

POST /registers/{registerId}/closure закрывает кассу в VCR: её ключи перестают работать, отправляется register.closed.

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

Налоговой об этом не сообщается: снятие кассы с учёта — заявление самого налогоплательщика на портале налоговой. Как снять кассу с учёта