Общие положения

Сервис расположен по адресу https://cashbox.octonica.ru.
Обмен данными с Сервисом осуществляется по открытым каналам связи сети Интернет по протоколу HTTP(S) версии 1.1.
Данные передаются в Сервис стандартными HTTP POST запросами.
Соединение с Сервисом происходит с использованием криптографического протокола ТLS 1.2. Алгоритм шифрования канала: RSA.

Авторизация

Идентификация поставщика данных происходит по сертификату юридического лица, выданному нашей компанией.
Сертификат должен быть использован при установлении SSL соединения (двухсторонняя аутентификация).
Если при обработке данных в Сервисе возникли какие-либо внутренние ошибки, Сервис отвечает откликом с HTTP-статусом 500 Internal Server Error, в таких случаях нужно обратиться к разработчикам Сервиса.

Передача данных

Передача информации о проведенных платежах осуществляется POST-запросом по адресу https://cashbox.octonica.ru/api/externalPayment/send. Формат данных - json. При успешном приеме данных Сервис отвечает пустым откликом с HTTP-статусом 200 OK. Если структура или формат данных запроса не соответствуют требованиям, Сервис отвечает откликом с HTTP-статусом 400 Bad Request. Если при обработке данных в Сервисе возникли какие-либо внутренние ошибки, Сервис отвечает откликом с HTTP-статусом 500 Internal Server Error, в таких случаях нужно обратиться к разработчикам Сервиса.

Замечание

Пакетный API является транзакционным, при возникновении ошибки при обработке хотя бы одной строки пакета, не принимается весь пакет чеков.

Описание структуры данных

Данные передаются в виде массива структур. Каждая структура описывает один проведенный платеж.
Реквизитный состав структуры представлен в таблицах ниже.

Таблица 1 - реквизиты платежа

Наименование реквизита Тип Описание Обязательность заполнения
externalId строка Внутренний идентификатор платежа в системе поставщика информации. Должен обеспечивать уникальность как минимум в рамках получателя платежа. Да
operationDt строка Время совершения платежа в формате ISO 8601 с поддержкой временных зон Да
operation строка Тип операции. Возможные значения:
  • sell - Приход
  • sell_refund - Возврат прихода
  • sell_correction - Коррекция прихода
  • buy - Расход
  • buy_refund - Возврат расхода
  • buy_correction - Коррекция расхода
 Да
companyInn строка ИНН получателя платежа Да
paymentType строка Тип платежа. Возможные значения:
  • cash - наличными
  • cashless - безналичный перевод
  • advance - предоплатой
  • credit - в кредит
  • non_money - встречным представлением
 Да
clientEmail строка Адрес электронной почты плательщика Нет
clientPhone строка Номера сотового телефона плательщика Нет
itemUserData строка Идентификатор плательщика. Может представлять из себя номер лицевого счета, адрес или какой-либо иной идентификатор Да
items массив позиций предмета оплаты см. Таблица 2 Да (как минимум 1 позиция)

Таблица 2 - реквизиты предмета оплаты

Наименование реквизита Тип Описание Обязательность заполнения
itemName строка Наименование товара(услуги) Да
itemPrice целое число Цена в копейках Да
itemQuantity дробное число Количество (объем) Да
itemSum целое число Сумма в копейках Да
measurementUnit строка Единица измерения количества (объема) Нет
paymentMethod строка Вид оплаты. Возможные значения:
  • full_prepayment - Предоплата 100%
  • prepayment - Предоплата
  • advance - Аванс
  • full_payment - Полный расчет
  • partial_payment - Частичный расчет и кредит
  • credit - Передача в кредит
  • credit_payment - Оплата кредита
Да
paymentObject строка Вид предмета оплаты. Типовые значения:
  • job - Работа
  • service - Услуга
См. Таблица 3		 Да
vatType строка НДС. Возможные значения:
  • none - без НДС
  • vat0 - НДС 0%
  • vat10 - НДС 10%
  • vat20 - НДС 20%
  • vat110 - НДС 10/110%
  • vat120 - НДС 20/120%
 Да
supplierName строка Наименование организации - поставщика товара\услуги Нет
supplierInn строка ИНН организации - поставщика товара\услуги Нет
supplierPhone строка Телефон организации - поставщика товара\услуги Нет

Таблица 3 - значения реквизита вид предмета оплаты

Значение Описание
commodity Товар
excise Подакцизный товар
job Работа
service Услуга
gambling_bet Ставка азартной игры
gambling_prize Выигрыш азартной игры
lottery Ставка (билет) лотереи
lottery_prize Выигрыш лотереи
intellectual_activity Предоставление результатов интеллектуальной деятельности
payment Аванс/задаток/предоплата/кредит/взнос/пеня/штраф/вознаграждение/бонус
agent_commission Агентское вознаграждение
composite Составной предмет расчета
another Иной предмет расчёта
property_right Имущественное право
non_operating_gain Внереализационный доход
insurance_premium Страховые взносы
sales_tax Торговый сбор
resort_fee Курортный сбор

Примеры

json-запрос передачи двух платежей

[
  {
    "externalId": "7483949583784",
    "operationDt": "2019-08-20T18:56:11.5603489+05:00",
    "operation": "sell",
    "companyInn": "7419005017",
    "paymentType": "cashless",
    "clientEmail": "noaddress@fake.mail",
    "itemUserData": "ЛС №13245211",
    "items": [
      {
        "itemName": "Услуги ЖКХ",
        "itemSum": 102476,
        "paymentMethod": "full_payment",
        "paymentObject": "service"
      }
    ]
  },
  {
    "externalId": "74812312214124",
    "operationDt": "2019-08-20T18:56:11.561349+05:00",
    "operation": "sell",
    "companyInn": "7419005017",
    "paymentType": "cashless",
    "clientPhone": "+7890123456",
    "itemUserData": "ЛС №333",
    "items": [
      {
        "itemName": "Содержание жилья",
        "itemPrice": 1476,
        "itemQuantity": 98.24,
        "itemSum": 145002,
        "measurementUnit": "кв.м",
        "paymentMethod": "full_payment",
        "paymentObject": "service"
      },
      {
        "itemName": "Холодное водоснабжение",
        "itemPrice": 16000,
        "itemQuantity": 23.24,
        "itemSum": 371840,
        "measurementUnit": "куб.м",
        "paymentMethod": "full_payment",
        "paymentObject": "service"
      },
      {
        "itemName": "Горячее водоснабжение",
        "itemPrice": 16.0,
        "itemQuantity": 2324.0,
        "itemSum": 3718.0,
        "measurementUnit": "куб.м",
        "paymentMethod": "full_payment",
        "paymentObject": "service",
        "vatType": "none",
        "supplierName": "ООО ТеплоСнаб",
        "supplierInn": "7419002367",
        "supplierPhone": "+7890546879"
      }
    ]
  }
]

Получение информации о статусе

Получение информации о статусе фискализации проведенных платежей осуществляется POST-запросом по адресу https://cashbox.octonica.ru/api/externalPayment/report. Формат данных - json. При успешном приеме данных Сервис отвечает откликом с HTTP-статусом 200 OK и телом json с той же структурой. Если структура или формат данных запроса не соответствуют требованиям, Сервис отвечает откликом с HTTP-статусом 400 Bad Request. Если при обработке данных в Сервисе возникли какие-либо внутренние ошибки, Сервис отвечает откликом с HTTP-статусом 500 Internal Server Error , в таких случаях нужно обратиться к разработчикам Сервиса.

Описание структуры данных

Таблица 4 - реквизиты запроса статуса фискализации

Наименование реквизита Тип Описание Обязательность заполнения
date дата Время совершения платежа. Строковое представление даты в формате ISO 8601:2004 Да
companyInn ИНН получателя платежа Время совершения платежа в формате ISO 8601 с поддержкой временных зон Да

Таблица 5 - статусы платежей

Ответ состоит из реквизитов запроса см. Таблица 4, дополненных статусом каждого платежа.

Значение Описание
waiting в очереди на фискализацию
register фискализирован
error фискализация не произведена из-за ошибки
notFound информация о платеже отсутствует в базе данных
unknown статус неизвестен

Примеры

json-запрос статусов платежей

{
  "date": "2020-04-03T00:00:00",
  "companyInn": "7456027298",
  "items": [
    {
      "externalId": "1109471560"
    },
    {
      "externalId": "1109405394"
    },
    {
      "externalId": "1109467800"
    },
    {
      "externalId": "1109714351"
    },
    {
      "externalId": "1109547787"
    },
    {
      "externalId": "1109657269!"
    }
  ]
}

json-ответ статусов платежей

{
  "date": "2020-04-03T00:00:00",
  "companyInn": "7456027298",
  "items": [
    {
      "externalId": "1109405394",
      "status": "register"
    },
    {
      "externalId": "1109467800",
      "status": "register"
    },
    {
      "externalId": "1109471560",
      "status": "register"
    },
    {
      "externalId": "1109547787",
      "status": "register"
    },
    {
      "externalId": "1109714351",
      "status": "register"
    },
    {
      "externalId": "1109657269!",
      "status": "notFound"
    }
  ]
}