README

PHP integration for OrangeData service

Актуальная версия библиотеки: 4.0.0

Версия PHP: 5.6.6+

Версия протокола взаимодействия с интернет кассой: 2.29.1 от 15.11.2023

Содержание

Начало работы
- Подключение библиотеки
- Создание клиента
Заказ
Чек коррекции

Начало работы

Подключение библиотеки

Для начала работы необходимо подключить файл класса:

<?php
include_once 'orangedata_client.php';

Создание клиента

<?php
$client = [
  'inn' => '0123456789',
  'api_url' => '2443',
  // 'api_url' => 'https://apip.orangedata.ru:2443', // link access
  'sign_pkey' => dirname(__DIR__) . '/secure_path/private_key.pem',
  'ssl_client_key' => dirname(__DIR__) . '/secure_path/client.key',
  'ssl_client_crt' => dirname(__DIR__) . '/secure_path/client.crt',
  'ssl_ca_cert' => dirname(__DIR__) . '/secure_path/cacert.pem',
  'ssl_client_crt_pass' => 1234,
];

$buyer = new orangedata\orangedata_client($client); // create new client

Cвойства клиента

Имя	Обязательное поле	Описание
inn	Да	ИНН организации (строка от 1 до 64)
api_url	Да	Порт, на который будем отправлять запросы или Адрес API или прокси
sign_pkey	Да	Путь к приватному ключу, который используется для подписи "чека"
ssl_client_key	Да	Путь к приватному ключу используемому для 2ssl взаимодействия
ssl_client_crt	Да	Путь к клиентскому сертификату используемому для 2ssl
ssl_ca_cert	Да	Путь к cacert.pem
ssl_client_crt_pass	Да	Пароль к клиентскому сертификату

Для включения записи логов в файл 'curl.log', прописываем:

<?php
$buyer->is_debug();

Заказ

Создание заказа

После того, как создали клиента, можно приступить к созданию заказа.

<?php
$order = [
  'id' => '23423423434',
  'type' => 1,
  'customerContact' => 'example@example.com',
  'taxationSystem' => 1,
  'key' => '1234567',
  'ffdVersion' => 4
];

$buyer->create_order($order);

Cвойства заказа

Имя	Обязательное поле	Описание
id	Да	Идентификатор документа (строка от 1 до 64)
type	Да	1 - Приход 2 - Возврат прихода 3 - Расход 4 - Возврат расхода
customerContact	Да	Телефон или электронный адрес покупателя (строка от 1 до 64)
taxationSystem	Да	0 - Общая, ОСН 1 - Упрощенная доход, УСН доход 2 - Упрощенная доход минус расход, УСН доход - расход 3 - Единый налог на вмененный доход, ЕНВД 4 - Единый сельскохозяйственный налог, ЕСН 5 - Патентная система налогообложения, Патент
key	Да	Название ключа, который должен быть использован для проверки подпись. Для клиентов используется их ИНН, для партнеров и платежных агентов код с маской 301**, для вендинга 401** (cтрока от 1 до 32 )
group	Да	Группа устройств, с помощью которых будет пробит чек (строка от 1 до 32 символов), по умолчанию 'Main'. Чтобы работать с ФФД1.2 - 'Main_2'
ffdVersion	Нет	Версия ФФД. 2 - ФФД1.05 4 - ФФД1.2 По умолчанию - 2
ignoreItemCodeCheck	Нет	Булево значение, указывающее стоит ли игнорировать проверку КМ. Если флаг не указан, то для формирования чека все КМ должны успешно пройти проверку: в тэге 2106 биты номер 0, 1, 2, 3 имеют состояние «1» Если же флаг не указан и КМ не прошел проверку чек не будет сформирован и запрос статуса будет возвращать статус 422 Unprocessable Entity. По умолчанию - false

Добавление позиции в заказ

<?php
$position = [
  'quantity' => '10',
  'price' => 100,
  'tax' => 1,
  'text' => 'some text',
  'paymentMethodType' => 3,
  'paymentSubjectType' => 1,
  'nomenclatureCode' => 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/',
  'supplierInfo' => [
    'phoneNumbers' => ['+79266660011', '+79293456723'],
    'name' => 'PAO Example',
  ],
  'supplierINN' => 1234567890,
  'agentType' => 127,
  'agentInfo' => [
    'paymentTransferOperatorPhoneNumbers' => ['+79266660011', '+79293456723'],
    'paymentAgentOperation' => 'some operartion',
    'paymentAgentPhoneNumbers' => ['+79266660011', '+79293456723'],
    'paymentOperatorPhoneNumbers' => ['+79266660011'],
    'paymentOperatorName' => 'OAO ATLANT',
    'paymentOperatorAddress' => 'Address',
    'paymentOperatorInn' => 1234567890,
  ],
  'unitOfMeasurement' => 'kg',
  'additionalAttribute' => 'attribute',
  'manufacturerCountryCode' => '534',
  'customsDeclarationNumber' => 'AD 11/77 from 01.08.2018',
  'excise' => '12.43',
];

$buyer->add_position_to_order($position);

Cвойства позиции

Имя	Обязательное поле	Описание
quantity	Да	Количество предмета расчета (десятичное число)
price	Да	Цена за единицу предмета расчета с учетом скидок и наценок (десятичное число)
tax	Да	Ставка НДС: 1 - ставка НДС 20% 2 - ставка НДС 10% 3 - ставка НДС расч. 20/120 4 - ставка НДС расч. 10/110 5 - ставка НДС 0% 6 - НДС не облагается
taxSum		Сумма НДС за предмет расчета (Десятичное число) Параметр актуален дляставок НДС 1-4. Для ставок 5 и 6 данный тэг в предмете расчета не передается, переданное значение игнорируется.
text	Да	Наименование предмета расчета (строка до 128 символов)
paymentMethodType	Да	Признак способа расчета: 1 - Предоплата 100% 2 - Частичная предоплата 3 - Аванс 4 - Полный расчет 5 - Частичный расчет и кредит 6 - Передача в кредит 7 - оплата кредита
paymentSubjectType	Да	Признак предмета расчета: 1 - Товар 2 - Подакцизный товар 3 - Работа 4 - Услуга 5 - Ставка азартной игры 6 - Выигрыш азартной игры 7 - Лотерейный билет 8 - Выигрыш лотереи 9 - Предоставление РИД 10 - Платеж 11 - Агентское вознаграждение 12 - Составной предмет расчета 13 - Иной предмет расчета 14 - Имущественное право 15 - Внереализационный доход* 16 - Страховые взносы* 17 - Торговый сбор 18 - Курортный сбор 19 - Залог 20 – Расход 21 – Взносы на обязательное пенсионное страхование ИП 22 – Взносы на обязательное пенсионное страхование 23 – Взносы на обязательное медицинское страхование ИП 24 – Взносы на обязательное медицинское страхование 25 – Взносы на обязательное социальное страхование 26 – Платеж казино 27 – Выдача денежных средств 30 – АТНМ (не имеющем кода маркировки) 31 – АТМ (имеющем код маркировки) 32 – ТНМ 33 – ТМ
nomenclatureCode		Код товарной номенклатуры (строка, содержащая base64 кодированный массив от 1 до 32 байт)
itemCode		Код маркировки (Строка от 1 до 223 символов)
supplierInfo		Данные поставщика (смотреть "Свойства supplierInfo")
supplierINN		ИНН поставщика (строка длиной от 10 до 12 символов)
agentType		Признак агента по предмету расчета (Число от 1 до 127)
agentInfo		Данные агента (смотреть "Свойства agentInfo")
unitOfMeasurement		Единица измерения предмета расчета (строка от 1 до 16)
quantityMeasurementUnit		Мера количества предмета расчета (Число от 0 до 255, если не указан – 0)
additionalAttribute		Дополнительный реквизит предмета расчета (строка от 1 до 64)
manufacturerCountryCode		Код страны происхождения товара (строка длиной от 1 до 3 )
customsDeclarationNumber		Номер таможенной декларации (строка от 1 до 32)
excise		Акциз (десятичное число)
industryAttribute		Отраслевой реквизит чека (смотреть "Свойства industryAttribute")
unitTaxSum		Размер НДС за единицу предмета расчета (десятичное число)
plannedStatus		Планируемый статус (Число от 0 до 256) 1 Штучный товар, подлежащий обязательной маркировке средством идентификации, реализован 2 Мерный товар, подлежащий обязательной маркировке средством идентификации, в стадии реализации, 3 Штучный товар, подлежащий обязательной маркировке средством идентификации, возвращен, 4 Часть товара, подлежащего обязательной маркировке средством идентификации, возвращена, 255 Статус товара, подлежащего обязательной маркировке средством идентификации, не изменился
fractionalQuantity		Дробное количество маркированного товара (смотреть "Свойства fractionalQuantity")
barcodes		Штрих-коды предмета расчета (смотреть "Свойства barcodes")

Параметры nomenclatureCode, unitOfMeasurement используются для ФФД 1.05
Параметры itemCode, quantityMeasurementUnit, industryAttribute, plannedStatus, fractionalQuantity, barcodes используются для ФФД 1.2

Cвойства supplierInfo

Имя	Обязательное поле	Описание
phoneNumbers		Номера телефонов поставщика (массив строк длиной от 1 до 19 символов)
name		Наименование поставщика (строка до 239 символов)

Cвойства agentInfo

Имя	Обязательное поле	Описание
paymentTransferOperatorPhoneNumbers		Телефон оператора перевода (массив строк длиной от 1 до 19 символов)
paymentAgentOperation		Операция платежного агента (строка до 24 символов)
paymentAgentPhoneNumbers		Телефон платежного агента (массив строк длиной от 1 до 19 символов)
paymentOperatorPhoneNumbers		Телефон оператора по приему платежей (массив строк длиной от 1 до 19 символов)
paymentOperatorName		Наименование оператора перевода (строка до 64 символов)
paymentOperatorAddress		Адрес оператора перевода (строка до 243 символов)
paymentOperatorINN		ИНН оператора перевода (cтрока длиной от 10 до 12 символов)

Cвойства industryAttribute

Имя	Обязательное поле	Описание
foivId		Идентификатор ФОИВ
causeDocumentDate		Дата документа основания
causeDocumentNumber		Номер документа основания
value		Значение отраслевого реквизита

Cвойства fractionalQuantity

Имя	Обязательное поле	Описание
Numerator		Числитель (Целое беззнаковое число)
Denominator		Знаменатель (Целое беззнаковое число)

Cвойства barcodes

Имя	Обязательное поле	Описание
ean8		КТ EAN-8 (Строка 8 символов)
ean13		КТ EAN-13 (Строка 13 символов)
itf14		КТ ITF-14 (Строка 14 символов)
gs1		КТ GS1.0 (Строка от 1 до 38 символов)
mi		КТ МИ (Строка 20 символов)
egais20		КТ ЕГАИС-2.0 (Строка 23 символов)
egais30		КТ ЕГАИС-3.0 (Строка 14 символов)
f1		КТ Ф.1 (Строка от 1 до 32 символов)
f2		КТ Ф.2 (Строка от 1 до 32 символов)
f3		КТ Ф.3 (Строка от 1 до 32 символов)
f4		КТ Ф.4 (Строка от 1 до 32 символов)
f5		КТ Ф.5 (Строка от 1 до 32 символов)
f6		КТ Ф.6 (Строка от 1 до 32 символов)

Добавление оплаты в заказ

<?php
$payment = [
  'type' => 16,
  'amount' => 131.23,
];

$buyer->add_payment_to_order($payment);

Cвойства оплаты

Имя	Обязательное поле	Описание
type	Да	Тип оплаты: 1 - сумма по чеку наличными, 1031 2 - сумма по чеку безналичными, 1081 14 - сумма по чеку предоплатой (зачетом аванса и (или) предыдущих платежей), 1215 15 - сумма по чеку постоплатой (в кредит), 1216 16 - сумма по чеку (БСО) встречным предоставлением, 1217
amount	Да	Сумма оплаты (десятичное число)

Добавление агента в заказ

Не поддерживается для ФФД1.2

<?php
$agent = [
  'agentType' => 127,
  'paymentTransferOperatorPhoneNumbers' => ['+79998887766', '+76667778899'],
  'paymentAgentOperation' => 'Operation',
  'paymentAgentPhoneNumbers' => ['+79998887766'],
  'paymentOperatorPhoneNumbers' => ['+79998887766'],
  'paymentOperatorName' => 'Name',
  'paymentOperatorAddress' => 'ulitsa Adress, dom 7',
  'paymentOperatorINN' => '3123011520',
  'supplierPhoneNumbers' => ['+79998887766', '+76667778899'],
];

$buyer->add_agent_to_order($agent);

Cвойства агента

Имя	Обязательное поле	Описание
agentType		Признак агента по предмету расчета (число от 1 до 127)
paymentTransferOperatorPhoneNumbers		Телефон оператора перевода (массив строк длиной от 1 до 19 символов)
paymentAgentOperation		Операция платежного агента (строка до 24 символов)
paymentAgentPhoneNumbers		Телефон платежного агента (массив строк длиной от 1 до 19 символов)
paymentOperatorPhoneNumbers		Телефон оператора по приему платежей (массив строк длиной от 1 до 19 символов)
paymentOperatorName		Наименование оператора перевода (строка до 64 символов)
paymentOperatorAddress		Адрес оператора перевода (строка до 243 символов)
paymentOperatorINN		ИНН оператора перевода (cтрока длиной от 10 до 12 символов)
supplierPhoneNumbers		Телефон поставщика (массив строк длиной от 1 до 19 символов)

Добавление дополнительного реквизита пользователя

<?php
$userAttribute = [
  'name' => 'Like',
  'value' => 'Example',
];

$buyer->add_user_attribute($userAttribute);

Cвойства дополнительного реквизита пользователя

Имя	Обязательное поле	Описание
name		Наименование дополнительного реквизита пользователя (строка от 1 до 64 символов)
value		Значение дополнительного реквизита пользователя (строка от 1 до 234 символов)

Добавление дополнительных полей

<?php
$additional = [
  'additionalAttribute' => 'Attribute',
  'customer' => 'Ivanov Ivan',
  'customerINN' => '0987654321',
];

$buyer->add_additional_attributes($additional);

Cвойства дополнительных полей

Имя	Обязательное поле	Описание
additionalAttribute		Дополнительный реквизит чека(БСО) (строка от 1 до 16 символов)
customer		Покупатель (клиент) (строка от 1 до 243 символов)
customerINN		ИНН покупателя (клиента) (Строка длиной от 10 до 12 символов)
customerInfo		Сведения о покупателе (смотреть "Свойства customerInfo")
senderEmail		Адрес электронной почты отправителя чека (Строка от 1 до 64 символов)
operationalAttribute		Операционный реквизит чека (смотреть "Свойства operationalAttribute")
industryAttribute		Отраслевой реквизит чека (смотреть "Свойства industryAttribute")
totalSum		Сумма расчета, указанного в чеке (БСО) (десятичное число) Форматы Фискальных Документов допускают в данном поле округление в нижнюю сторону. Дословно требование ФФД звучит так: «Значение в рублях, без учета копеек, должно быть равно значению суммы всех реквизитов «стоимость предмета расчета с учетом скидок и наценок» (тег 1043) в рублях, без учета копеек». Во избежание нестыковок рекомендуем использовать точное значение без округлений.
vat1Sum		Сумма НДС чека по ставке 20% (десятичное число)
vat2Sum		Сумма НДС чека по ставке 10% (десятичное число)
vat3Sum		Сумма расчета по чеку с НДС по ставке 0% (десятичное число)
vat4Sum		Сумма расчета по чеку без НДС (десятичное число)
vat5Sum		Сумма НДС чека по расч. ставке 20/120 (десятичное число)
vat6Sum		Сумма НДС чека по расч. ставке 10/110 (десятичное число)

Cвойства customerInfo

Имя	Обязательное поле	Описание
name		Покупатель (Строка от 1 до 239 символов)
inn		ИНН покупателя (Строка длиной от 10 до 12 символов, формат ЦЦЦЦЦЦЦЦЦЦ)
birthDate		Дата рождения покупателя (Строка 10 символов, формат ДД.ММ.ГГГГ)
citizenship		Гражданство (Строка длиной от 1 до 3 символов, формат ЦЦЦ. Сервис автоматически дополнит строку до 3 символов пробелами)
identityDocumentCode		Код вида документа, удостоверяющего личность (Строка длиной 2 символа, формат ЦЦ)
identityDocumentData		Данные документа, удостоверяющего личность (Строка до 64 символов)
address		Адрес покупателя (Строка от 1 до 239 символов)

Cвойства operationalAttribute

Имя	Обязательное поле	Описание
date		Дата, время операции (Время в виде строки в формате ISO8601)
id		Идентификатор операции (Число от 0 до 255)
value		Данные операции (Строка от 1 до 64 символов)

Cвойства industryAttribute

Имя	Обязательное поле	Описание
foivId		Идентификатор ФОИВ
causeDocumentDate		Дата документа основания
causeDocumentNumber		Номер документа основания
value		Значение отраслевого реквизита

Для ФФД1.2 Параметры Customer и customerINN изменяется на один параметр customerInfo.

Добавление вендинга в заказ

<?php
$vending = [
  'automatNumber' => '21321321123',
  'settlementAddress' => 'Address',
  'settlementPlace' => 'Place',
];

$buyer->add_vending_to_order($vending);

Cвойства вендинга

Имя	Обязательное поле	Описание
automatNumber		Номер автомата (строка от 1 до 20 символов)
settlementAddress		Адрес расчетов (строка от 1 до 243 символов)
settlementPlace		Место расчетов (Строка длиной от 10 до 12 символов)

Добавление курьера в заказ

<?php
$courier = [
  'settlementAddress' => 'Address',
  'settlementPlace' => 'Place',
  'cashier' => 'Test'
  'cashierINN' => '123456789012'
];

$buyer->add_courier_to_order($courier);

Cвойства курьера

Имя	Обязательное поле	Описание
settlementAddress		Адрес расчетов (строка от 1 до 243 символов)
settlementPlace		Место расчетов (Строка длиной от 10 до 12 символов)
cashier		Кассир (Строка длиной от 1 до 64 символов)
cashierINN		ИНН кассира (Строка длиной 12 символов)

Отправка заказа

После того, как заполнены все поля заказа и добавлены все параметры, можно отправлять заказ на обработку:

<?php
$result = $buyer->send_order();
var_dump($result);

Проверка статуса заказа

<?php
$order_status = $buyer->get_order_status(23423423434);
var_dump($order_status);

Чек коррекции

Создание чека коррекции ФФД1.05

<?php
$correction = [
  'id' => '23423423',
  'key' => '1234567',
  'correctionType' => 0,
  'type' => 1,
  'description' => 'cashier error',
  'causeDocumentDate' => new \DateTime(),
  'causeDocumentNumber' => '56ce',
  'totalSum' => 567.9,
  'cashSum' => 567,
  'eCashSum' => 0.9,
  'prepaymentSum' => 0,
  'postpaymentSum' => 0,
  'otherPaymentTypeSum' => 0,
  'tax1Sum' => 0,
  'tax2Sum' => 0,
  'tax3Sum' => 0,
  'tax4Sum' => 0,
  'tax5Sum' => 0,
  'tax6Sum' => 0,
  'taxationSystem' => 2,
];

$buyer->create_correction($correction);

Cвойства чека коррекции

Имя	Обязательное поле	Описание
id	Да	Идентификатор документа (строка от 1 до 64 символов)
group	Да	Группа устройств, с помощью которых будет пробит чек (строка от 1 до 32 символов), по умолчанию 'Main'
key	Да	Название ключа, который должен быть использован для проверки подписи (строка от 1 до 32 символов)
correctionType	Да	Тип коррекции 1173: 0. Самостоятельно 1. По предписанию
type	Да	Признак расчета, 1054: 1. Приход 3. Расход
description	Да	Описание коррекции (cтрока от 1 до 243 символов. )
causeDocumentDate	Да	Дата документа основания для коррекции (время в виде строки в формате ISO8601)
causeDocumentNumber	Да	Номер документа основания для коррекции (строка от 1 до 32 символов)
totalSum	Да	Сумма расчета, указанного в чеке (десятичное число)
cashSum		Сумма по чеку (БСО) наличными (десятичное число)
eCashSum		Сумма по чеку (БСО) безналичными (десятичное число)
prepaymentSum		Сумма по чеку (БСО) предоплатой (зачетом аванса и (или) предыдущих платежей) (десятичное число)
postpaymentSum		Сумма по чеку (БСО) постоплатой (в кредит) (десятичное число)
otherPaymentTypeSum		Сумма по чеку (БСО) встречным предоставлением (десятичное число)
tax1Sum		Сумма НДС чека по ставке 20% (десятичное число)
tax2Sum		Сумма НДС чека по ставке 10% (десятичное число)
tax3Sum		Сумма расчета по чеку с НДС по ставке 0% (десятичное число)
tax4Sum		Сумма расчета по чеку без НДС (десятичное число)
tax5Sum		Сумма НДС чека по расч. ставке 20/120 (десятичное число)
tax6Sum		Сумма НДС чека по расч. ставке 10/110 (десятичное число)
taxationSystem		Применяемая система налогообложения, 1055: 0. Общая 1. Упрощенная доход 2. Упрощенная доход минус расход 3. Единый налог на вмененный доход 4. Единый сельскохозяйственный налог 5. Патентная система налогообложения
ignoreItemCodeCheck		Булево значение, указывающее стоит ли игнорировать проверку КМ. Если флаг не указан, то для формирования чека все КМ должны успешно пройти проверку: в тэге 2106 биты номер 0, 1, 2, 3 имеют состояние «1» Если же флаг не указан и КМ не прошел проверку чек не будет сформирован и запрос статуса будет возвращать статус 422 Unprocessable Entity. По умолчанию - false

Отправка чека коррекции ФФД1.05

<?php
$result = $buyer->post_correction();
var_dump($result);

Создание чека коррекции ФФД1.2

<?php
  $correction = [
      'ffdVersion' => 4,
      'id' => '23423423',
      'inn' => '7725327863',
      'key' => '1234567',
      'correctionType' => 0,
      'type' => 1,
      'group' => 'main_2',
      'causeDocumentDate' => new \DateTime(),
      'causeDocumentNumber' => '56ce',
      'totalSum' => 0,
      'customerContact' => 'liza@ya.ru',
      'vat1Sum' => 0,
      'vat2Sum' => 0,
      'vat3Sum' => 0,
      'vat4Sum' => 0,
      'vat5Sum' => 0,
      'vat6Sum' => 0,
  ];

$buyer->create_correction12($correction);