Документация для разработчиков

Регистрируйте продажи, предоплаты и возвраты в налоговой Армении из любого стека.

Базовый 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В личном кабинете откройте «Кассы», нажмите «Создать кассу» и выберите «Тестовая касса». Создавайте столько, сколько нужно.
2Выпустите API-ключ на этой кассе. Ключ привязан к одной кассе, поэтому ключ от боевой так и будет отвечать 403.
3Вызывайте те же эндпоинты по тому же базовому URL. Когда будете готовы к реальной фискализации, создайте боевую кассу и замените ключ.

Создано для боевых интеграций

REST поверх JSON

Эндпоинты без состояния, JSON, вызов из любого языка и фреймворка.

Типизированные Node.js и PHP SDK

Типизированные клиенты на npm и Packagist — готовы к использованию на сервере как из Node.js, так и из PHP.

Аутентификация по API-ключу

Отзываемые API-ключи, которыми вы управляете из личного кабинета.

Полный API кассы

Продажи, предоплаты, возвраты и чеки — единый последовательный интерфейс.

Что должна предоставить ваша система

Перед интеграцией убедитесь, что каждая продажа несёт данные, которые требует налоговая.

Код классификатора

Код из товарного классификатора для товаров или классификатора видов деятельности — для услуг.

Единица измерения

кг, шт, м², час, услуга, работа и т.д.

Идентификатор отдела

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

Идентификатор кассира

Кто регистрирует продажу.

Аутентификация

Каждый запрос должен содержать ваш API-ключ в заголовке X-API-Key. Единственное исключение — GET /exchange-rate: он публичный и ключа не требует.

X-API-Key: your_api_key

Создавайте и обновляйте API-ключи в настройках вашей кассы.

Храните API-ключ в секрете

Не размещайте его в клиентском коде, публичных репозиториях и общих логах. Если ключ утёк — сразу отзовите его и сгенерируйте новый в настройках кассы.

Ошибки

Ошибки возвращаются стандартными HTTP-кодами и JSON-телом с подробностями.

Статус	Название	Когда возникает
400	Неверный запрос	Неверный формат тела или ошибка валидации схемы.
401	Не авторизован	API-ключ отсутствует или недействителен.
403	Доступ запрещён	Касса ещё не может подавать документы: нет регистрационного номера или она не активирована в налоговой.
404	Не найдено	Запрашиваемый ресурс не существует.
500	Внутренняя ошибка	Непредвиденный сбой на нашей стороне. Повторите с экспоненциальной задержкой.