434 lines
27 KiB
Markdown
434 lines
27 KiB
Markdown
# PHPOrangeData
|
||
|
||
PHP integration for OrangeData service
|
||
|
||
Актуальная версия библиотеки: 3.0.0
|
||
|
||
Версия PHP: 5.6.6+
|
||
|
||
Версия протокола взаимодействия с интернет кассой: 2.22.0 от 28.04.2019
|
||
|
||
# Содержание
|
||
|
||
<ul>
|
||
<li>
|
||
<a href="#начало-работы">Начало работы</a>
|
||
<ul>
|
||
<li><a href="#подключение-библиотеки">Подключение библиотеки</a></li>
|
||
<li><a href="#создание-клиента">Создание клиента</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href="#заказ">Заказ</a>
|
||
<ul>
|
||
<li>
|
||
<a href="#создание-заказа">Создание заказа</a>
|
||
<ul>
|
||
<li><a href="#добавление-позиции-в-заказ">Добавление позиции в заказ</a></li>
|
||
<li><a href="#добавление-оплаты-в-заказ">Добавление оплаты в заказ</a></li>
|
||
<li><a href="#добавление-агента-в-заказ">Добавление агента в заказ</a></li>
|
||
<li><a href="#добавление-дополнительного-реквизита-пользователя">Добавление дополнительного реквизита пользователя</a></li>
|
||
<li><a href="#добавление-дополнительных-полей">Добавление дополнительных полей</a></li>
|
||
<li><a href="#добавление-вендинга-в-заказ">Добавление вендинга в заказ</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#отправка-заказа">Отправка заказа</a></li>
|
||
<li><a href="#проверка-статуса-заказа">Проверка статуса заказа</a></li>
|
||
</ul>
|
||
</li>
|
||
<li>
|
||
<a href="#чек-коррекции">Чек коррекции</a>
|
||
<ul>
|
||
<li>
|
||
<a href="#создание-чека-коррекции">Создание чека коррекции</a>
|
||
<ul>
|
||
<li><a href="#добавление-вендинга-в-чек-коррекции">Добавление вендинга в чек коррекции</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a href="#отправка-чека-коррекции">Отправка чека коррекции</a></li>
|
||
<li><a href="#проверка-статуса-чека-коррекции">Проверка статуса чека коррекции</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
# Начало работы
|
||
|
||
## Подключение библиотеки
|
||
|
||
Для начала работы необходимо подключить файл класса:
|
||
|
||
```php
|
||
<?php
|
||
include_once 'orangedata_client.php';
|
||
```
|
||
|
||
## Создание клиента
|
||
|
||
```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
|
||
<?php
|
||
$buyer->is_debug();
|
||
```
|
||
|
||
# Заказ
|
||
|
||
## Создание заказа
|
||
|
||
После того, как создали клиента, можно приступить к созданию заказа.
|
||
|
||
```php
|
||
<?php
|
||
$order = [
|
||
'id' => '23423423434',
|
||
'type' => 1,
|
||
'customerContact' => 'example@example.com',
|
||
'taxationSystem' => 1,
|
||
'key' => '1234567',
|
||
];
|
||
|
||
$buyer->create_order($order);
|
||
```
|
||
|
||
**Cвойства заказа**
|
||
|
||
| Имя | Обязательное поле | Описание |
|
||
| ------------------- | -------------------- | ------------------------------------------------------------------ |
|
||
| id | Да | Идентификатор документа (строка от 1 до 64) |
|
||
| type | Да | 1 - Приход<br/>2 - Возврат прихода<br/>3 - Расход<br/>4 - Возврат расхода |
|
||
| customerContact | Да | Телефон или электронный адрес покупателя (строка от 1 до 64) |
|
||
| taxationSystem | Да | 0 - Общая, ОСН<br/>1 - Упрощенная доход, УСН доход<br/>2 - Упрощенная доход минус расход, УСН доход - расход<br/>3 - Единый налог на вмененный доход, ЕНВД<br/>4 - Единый сельскохозяйственный налог, ЕСН<br/>5 - Патентная система налогообложения, Патент |
|
||
| key | Да | Название ключа, который должен быть использован для проверки подпись. Для клиентов используется их ИНН, для партнеров и платежных агентов код с маской 301****, для вендинга 401**** (cтрока от 1 до 32 ) |
|
||
| group | Да | Группа устройств, с помощью которых будет пробит чек (строка от 1 до 32 символов), по умолчанию 'Main' |
|
||
|
||
### Добавление позиции в заказ
|
||
|
||
```php
|
||
<?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 | Да | Ставка НДС:<br/>1 - ставка НДС 20%<br/>2 - ставка НДС 10%<br/>3 - ставка НДС расч. 20/120<br/>4 - ставка НДС расч. 10/110<br/>5 - ставка НДС 0%<br/>6 - НДС не облагается |
|
||
| text | Да | Наименование предмета расчета (строка до 128 символов) |
|
||
| paymentMethodType | Да | Признак способа расчета:<br/>1 - Предоплата 100%<br/>2 - Частичная предоплата<br/>3 - Аванс<br/>4 - Полный расчет<br/>5 - Частичный расчет и кредит<br/>6 - Передача в кредит<br/>7 - оплата кредита |
|
||
| paymentSubjectType | Да | Признак предмета расчета:<br/>1 - Товар<br/>2 - Подакцизный товар<br/>3 - Работа<br/>4 - Услуга<br/>5 - Ставка азартной игры<br/>6 - Выигрыш азартной игры<br/>7 - Лотерейный билет<br/>8 - Выигрыш лотереи<br/>9 - Предоставление РИД<br/>10 - Платеж<br/>11 - Агентское вознаграждение<br/>12 - Составной предмет расчета<br/>13 - Иной предмет расчета<br/>14 - Имущественное право<br/>15 - Внереализационный доход*<br/>16 - Страховые взносы*<br/>17 - Торговый сбор<br/>18 - Курортный сбор<br/>19 - Залог |
|
||
| nomenclatureCode | | Код товарной номенклатуры (строка, содержащая base64 кодированный массив от 1 до 32 байт) |
|
||
| supplierInfo | | Данные поставщика (смотреть "Свойства supplierInfo") |
|
||
| supplierINN | | ИНН поставщика (строка длиной от 10 до 12 символов) |
|
||
| agentType | | Признак агента по предмету расчета (Число от 1 до 127) |
|
||
| agentInfo | | Данные агента (смотреть "Свойства agentInfo") |
|
||
| unitOfMeasurement | | Единица измерения предмета расчета (строка от 1 до 16) |
|
||
| additionalAttribute | | Дополнительный реквизит предмета расчета (строка от 1 до 64) |
|
||
| manufacturerCountryCode | | Код страны происхождения товара (строка длиной от 1 до 3 ) |
|
||
| customsDeclarationNumber | | Номер таможенной декларации (строка от 1 до 32) |
|
||
| excise | | Акциз (десятичное число) |
|
||
|
||
**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 символов) |
|
||
|
||
### Добавление оплаты в заказ
|
||
|
||
```php
|
||
<?php
|
||
$payment = [
|
||
'type' => 16,
|
||
'amount' => 131.23,
|
||
];
|
||
|
||
$buyer->add_payment_to_order($payment);
|
||
```
|
||
|
||
**Cвойства оплаты**
|
||
|
||
| Имя | Обязательное поле | Описание |
|
||
| ------------------- | -------------------- | ------------------------------------------------------------------ |
|
||
| type | Да | Тип оплаты:<br/>1 - сумма по чеку наличными, 1031<br/>2 - сумма по чеку безналичными, 1081<br/>14 - сумма по чеку предоплатой (зачетом аванса и (или) предыдущих платежей), 1215<br/>15 - сумма по чеку постоплатой (в кредит), 1216<br/>16 - сумма по чеку (БСО) встречным предоставлением, 1217 |
|
||
| amount | Да | Сумма оплаты (десятичное число) |
|
||
|
||
### Добавление агента в заказ
|
||
|
||
```php
|
||
<?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
|
||
<?php
|
||
$userAttribute = [
|
||
'name' => 'Like',
|
||
'value' => 'Example',
|
||
];
|
||
|
||
$buyer->add_user_attribute($userAttribute);
|
||
```
|
||
|
||
**Cвойства дополнительного реквизита пользователя**
|
||
|
||
| Имя | Обязательное поле | Описание |
|
||
| ----------------------------------- | -------------------- | ------------------------------------------------------------------ |
|
||
| name | | Наименование дополнительного реквизита пользователя (строка от 1 до 64 символов) |
|
||
| value | | Значение дополнительного реквизита пользователя (строка от 1 до 234 символов) |
|
||
|
||
### Добавление дополнительных полей
|
||
|
||
```php
|
||
<?php
|
||
$additional = [
|
||
'additionalAttribute' => 'Attribute',
|
||
'customer' => 'Ivanov Ivan',
|
||
'customerINN' => '0987654321',
|
||
];
|
||
|
||
$buyer->add_additional_attributes($additional);
|
||
```
|
||
|
||
**Cвойства дополнительных полей**
|
||
|
||
| Имя | Обязательное поле | Описание |
|
||
| ----------------------------------- | -------------------- | ------------------------------------------------------------------ |
|
||
| additionalAttribute | | Дополнительный реквизит чека(БСО) (строка от 1 до 16 символов) |
|
||
| customer | | Покупатель (клиент) (строка от 1 до 243 символов) |
|
||
| customerINN | | ИНН покупателя (клиента) (Строка длиной от 10 до 12 символов) |
|
||
|
||
### Добавление вендинга в заказ
|
||
|
||
```php
|
||
<?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
|
||
<?php
|
||
$result = $buyer->send_order();
|
||
var_dump($result);
|
||
```
|
||
|
||
## Проверка статуса заказа
|
||
|
||
```php
|
||
<?php
|
||
$order_status = $buyer->get_order_status(23423423434);
|
||
var_dump($order_status);
|
||
```
|
||
|
||
# Чек коррекции
|
||
|
||
## Создание чека коррекции
|
||
|
||
```php
|
||
<?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:<br/>0. Самостоятельно<br/>1. По предписанию |
|
||
| type | Да | Признак расчета, 1054:<br/>1. Приход<br/>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:<br/>0. Общая<br/>1. Упрощенная доход<br/>2. Упрощенная доход минус расход<br/>3. Единый налог на вмененный доход<br/>4. Единый сельскохозяйственный налог<br/>5. Патентная система налогообложения |
|
||
|
||
### Добавление вендинга в чек коррекции
|
||
|
||
```php
|
||
<?php
|
||
$correctionVending = [
|
||
'automatNumber' => '21321321123',
|
||
'settlementAddress' => 'Address',
|
||
'settlementPlace' => 'Place',
|
||
];
|
||
|
||
$buyer->add_vending_to_correction($correctionVending);
|
||
```
|
||
|
||
**Cвойства вендинга**
|
||
|
||
| Имя | Обязательное поле | Описание |
|
||
| ----------------------------------- | -------------------- | ------------------------------------------------------------------ |
|
||
| automatNumber | | Номер автомата (строка от 1 до 20 символов) |
|
||
| settlementAddress | | Адрес расчетов (строка от 1 до 243 символов) |
|
||
| settlementPlace | | Место расчетов (Строка длиной от 10 до 12 символов) |
|
||
|
||
## Отправка чека коррекции
|
||
|
||
```php
|
||
<?php
|
||
$result = $buyer->post_correction();
|
||
var_dump($result);
|
||
```
|
||
|
||
## Проверка статуса чека коррекции
|
||
|
||
```php
|
||
<?php
|
||
$cor_status = $buyer->get_correction_status('23423423');
|
||
var_dump($cor_status);
|
||
```
|