# 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);
```