mirror of
https://github.com/anthonyaxenov/atol-online.git
synced 2024-11-22 01:04:33 +00:00
Правки по документации
Актуализирована часть про `Vat`, пересобрал README, мелочи
This commit is contained in:
parent
a7205ff754
commit
bce21f9658
111
README.md
111
README.md
@ -2,11 +2,8 @@
|
||||
|
||||
---
|
||||
|
||||
**В этой ветке проводится глубокий рефакторинг и активная подготовка к `v1.0.0`.**
|
||||
|
||||
**Актуальность документации -- околонулевая.**
|
||||
|
||||
**Общая работоспособность -- нулевая.**
|
||||
**В этой ветке проводится глубокий рефакторинг, стабилизация и активная подготовка к `v1.0.0`. Документация
|
||||
актуализируется постепенно.**
|
||||
|
||||
---
|
||||
|
||||
@ -15,29 +12,48 @@
|
||||
|
||||
Библиотека для фискализации чеков по 54-ФЗ через [облачную ККТ АТОЛ](https://online.atol.ru/).
|
||||
|
||||
Текущая поддерживаемая версия API: **5.1**
|
||||
|
||||
**[Документация](/docs/readme.md)**
|
||||
|
||||
Текущие поддерживаемые версии:
|
||||
|
||||
| Протокол | API | ФФД | Статус |
|
||||
|----------|-----|------|-------------|
|
||||
| v4 | 5.7 | 1.05 | Рефакторинг |
|
||||
| v5 | 2.0 | 1.2 | В планах |
|
||||
|
||||
## Плюшечки
|
||||
|
||||
* Мониторинг ККТ и ФН
|
||||
* Фискализация докумнетов на облачной ККТ
|
||||
* Валидация данных до отправки документа на ККТ (насколько это возможно, согласно схеме)
|
||||
* Расчёты денег в копейках
|
||||
* Фактически полное покрытие тестами
|
||||
* PSR-4 автозагрузка
|
||||
|
||||
## Системные требования
|
||||
|
||||
* PHP 7.4+
|
||||
* composer
|
||||
* php-json
|
||||
* php8.0+
|
||||
* [composer](https://getcomposer.org/)
|
||||
* расширения php (скорее всего, устанавливать их отдельно не придётся):
|
||||
* `php-json`
|
||||
* `php-curl`
|
||||
* `php-mbstring`
|
||||
* `php-tokenizer`
|
||||
|
||||
## Начало работы
|
||||
|
||||
### Подключение библиотеки
|
||||
|
||||
1. Подключить пакет к вашему проекту:
|
||||
1. Установить библиотеку пакет к проекту:
|
||||
```bash
|
||||
composer require axenov/atol-online
|
||||
```
|
||||
2. В нужном месте проекта объявить параметры, используя константы, и подключить **composer**, если это не сделано ранее:
|
||||
2. В нужном месте проекта подключить автозагрузчик composer-зависимостей, если это не сделано ранее:
|
||||
```php
|
||||
require($project_root . '/vendor/autoload.php');
|
||||
```
|
||||
где `$project_root` — абсолютный путь к корневой директории вашего проекта.
|
||||
> При использовании фреймворков это обычно не требуется.
|
||||
|
||||
### Тестирование кода библиотеки
|
||||
|
||||
@ -46,80 +62,29 @@
|
||||
Для запуска тестов необходимо перейти в корень вашего проекта и выполнить команду:
|
||||
|
||||
```bash
|
||||
./vendor/bin/phpunit
|
||||
composer test
|
||||
```
|
||||
|
||||
## Настройка ККТ
|
||||
|
||||
Для работы с облачной ККТ необходимы следующие параметры:
|
||||
* логин;
|
||||
* пароль;
|
||||
* код группы.
|
||||
|
||||
Чтоб получить их, нужно:
|
||||
1. авторизоваться на [online.atol.ru](https://online.atol.ru/lk/Account/Login);
|
||||
2. на странице [Мои компании](https://online.atol.ru/lk/Company/List) нажать кнопку **Настройки интегратора**.
|
||||
Скачается XML-файл с нужными настройками.
|
||||
|
||||
Также для работы потребуются:
|
||||
* ИНН продавца;
|
||||
* URL места расчёта (ссылка на ваш интернет-сервис).
|
||||
|
||||
## Использование библиотеки
|
||||
|
||||
### Доступные методы и классы
|
||||
|
||||
Весь исходный код находится в директории [`/src`](/src).
|
||||
|
||||
**Комментарии phpDoc есть буквально к каждому классу, методу или полю.
|
||||
Прокомментировано вообще всё.**
|
||||
**Комментарии phpdoc есть буквально везде. Прокомментировано вообще всё.**
|
||||
|
||||
1. Обращайтесь к [документации](/docs).
|
||||
1. Обращайтесь к [документации библиотеки](/docs).
|
||||
2. Обращайтесь к [исходному коду](/src).
|
||||
3. Обращайтесь к [тестам](/test).
|
||||
4. **Используйте подсказки вашей IDE.**
|
||||
3. Обращайтесь к [тестам](/tests).
|
||||
4. Используйте подсказки вашей IDE.
|
||||
|
||||
Тогда у вас не возникнет затруднений.
|
||||
|
||||
Для тех, кто решил подробно разобраться в работе библиотеки, отдельно отмечу нюансы, которые могут ускользнуть от внимания:
|
||||
1. Класс `AtolOnline\Api\Kkt` унаследован от `GuzzleHttp\Client` со всеми вытекающими;
|
||||
2. Все классы, унаследованные от `AtolOnline\Entities\AtolEntity` приводятся к JSON-строке.
|
||||
|
||||
### Общий алгоритм
|
||||
|
||||
1. Задать настройки ККТ
|
||||
2. Собрать данные о покупателе
|
||||
3. Собрать данные о продавце
|
||||
4. Собрать данные о предметах расчёта (товары, услуги и пр.)
|
||||
5. Создать документ, добавив в него покупателя, продавца и предметы расчёта
|
||||
6. Отправить документ на регистрацию:
|
||||
6.1. *Необязательно:* задать `callback_url`, на который АТОЛ отправит HTTP POST о состоянии документа.
|
||||
7. Запомнить `uuid` из пришедшего ответа, поскольку он пригодится для последующей проверки статуса фискализации.
|
||||
> Если с документом был передан `callback_url`, то ответ придёт на этот самый URL.
|
||||
Если с документом **НЕ** был передан `callback_url` **либо** callback от АТОЛа не пришёл в течение 300 секунд (5 минут), нужно запрашивать вручную по `uuid`, пришедшему от АТОЛа в ответ на регистрацию документа.
|
||||
8. Проверить состояние документа (нет необходимости, если передавался `callback_url`):
|
||||
8.1. взять `uuid` ответа, полученного на запрос фискализации;
|
||||
8.2. отправить его в запросе состояния документа.
|
||||
> Данные о документе можно получить только в течение 32 суток после успешной фискализации.
|
||||
|
||||
## Об отправке электронного чека покупателю
|
||||
|
||||
После успешной фискализации документа покупатель автоматически получит уведомление **от ОФД**, который используется в связке с вашей ККТ:
|
||||
* **по email**, если в документе указан email клиента;
|
||||
* **по смс**:
|
||||
* если в документе указан номер телефона клиента;
|
||||
* если на стороне ОФД необходима и подключена услуга СМС-информирования (уточняйте подробности о своего ОФД).
|
||||
|
||||
> Если заданы email и телефон, то отдаётся приоритет email.
|
||||
|
||||
## Дополнительные ресурсы
|
||||
|
||||
Функционал, находящийся в разработке: [ROADMAP.md](ROADMAP.md)
|
||||
|
||||
Официальные ресурсы АТОЛ Онлайн:
|
||||
* **[Вся документация](https://online.atol.ru/lib/)**
|
||||
* Telegram-канал: [@atolonline](https://t.me/atolonline)
|
||||
* [Документация АТОЛ](https://online.atol.ru/lib/)
|
||||
**[Документация к библиотеке](/docs/readme.md)**
|
||||
* Telegram-канал: [@atolonline_php](https://t.me/atolonline_php)
|
||||
* Функционал, находящийся в разработке: [ROADMAP.md](ROADMAP.md)
|
||||
|
||||
## Лицензия
|
||||
|
||||
Вы имеете право использовать код из этого репозитория только на условиях **[лицензии MIT](LICENSE)**.
|
||||
Вы имеете право использовать и распространят код из этого репозитория на условиях **[лицензии MIT](LICENSE)**.
|
||||
|
||||
21
docs/kkt.md
21
docs/kkt.md
@ -4,6 +4,27 @@
|
||||
|
||||
---
|
||||
|
||||
## Доступ к ККТ
|
||||
|
||||
Для работы с облачной ККТ необходимы следующие параметры:
|
||||
|
||||
* логин;
|
||||
* пароль;
|
||||
* код группы.
|
||||
|
||||
Чтоы получить их, нужно:
|
||||
|
||||
1. авторизоваться в личном кабинете [online.atol.ru](https://online.atol.ru/lk/Account/Login);
|
||||
2. на странице [Мои компании](https://online.atol.ru/lk/Company/List) нажать кнопку **Настройки интегратора**.
|
||||
Скачается XML-файл с нужными настройками.
|
||||
|
||||
Также для работы потребуются:
|
||||
|
||||
* ИНН продавца;
|
||||
* URL места расчёта (ссылка на ваш интернет-сервис).
|
||||
|
||||
## Использование
|
||||
|
||||
Объект ККТ инициализируется следующим образом:
|
||||
|
||||
```php
|
||||
|
||||
@ -1,6 +1,39 @@
|
||||
# Документация к библиотеке
|
||||
|
||||
Содержание:
|
||||
## Общий алгоритм
|
||||
|
||||
1. Задать настройки ККТ
|
||||
2. Собрать данные о покупателе
|
||||
3. Собрать данные о продавце
|
||||
4. Собрать данные о предметах расчёта (товары, услуги и пр.)
|
||||
5. Создать документ, добавив в него покупателя, продавца и предметы расчёта
|
||||
6. Отправить документ на регистрацию:
|
||||
6.1. *Необязательно:* задать `callback_url`, на который АТОЛ отправит HTTP POST о состоянии документа.
|
||||
7. Запомнить `uuid` из пришедшего ответа, поскольку он пригодится для последующей проверки статуса фискализации.
|
||||
> Если с документом был передан `callback_url`, то ответ придёт на этот самый URL.
|
||||
Если с документом **НЕ** был передан `callback_url` **либо** callback от АТОЛа не пришёл в течение 300 секунд (5 минут), нужно запрашивать вручную по `uuid`, пришедшему от АТОЛа в ответ на регистрацию документа.
|
||||
8. Проверить состояние документа:
|
||||
8.1. взять `uuid` ответа, полученного на запрос фискализации;
|
||||
8.2. отправить его в запросе состояния документа.
|
||||
> Данные о документе можно получить только в течение 32 суток после успешной фискализации.
|
||||
|
||||
В зависимости от специфики бизнеса, в документах можно/нужно передавать также и другую информацию. Подробности в
|
||||
документациях и исходниках.
|
||||
|
||||
### Об отправке электронного чека покупателю
|
||||
|
||||
После успешной фискализации документа покупатель автоматически получит уведомление **от ОФД**, который используется в
|
||||
связке с вашей ККТ:
|
||||
|
||||
* **по email**, если в документе указан email клиента;
|
||||
* **по смс**:
|
||||
* если в документе указан номер телефона клиента;
|
||||
* если на стороне ОФД необходима и подключена услуга СМС-информирования (уточняйте подробности о своего ОФД).
|
||||
|
||||
> Если заданы email и телефон, то ОФД отдаёт приоритет email.
|
||||
|
||||
## Подготовка документа
|
||||
|
||||
1. [Работа с клиентами (покупателями)](client.md)
|
||||
2. [Работа с компанией (продавцом)](company.md)
|
||||
3. [Работа с оплатами](payments.md)
|
||||
|
||||
104
docs/vats.md
104
docs/vats.md
@ -9,113 +9,47 @@
|
||||
Объект ставки НДС инициализируется следующим образом:
|
||||
|
||||
```php
|
||||
$vat = new AtolOnline\Entities\Vat();
|
||||
```
|
||||
use AtolOnline\Entities\Vat;
|
||||
use AtolOnline\Enums\VatTypes;
|
||||
|
||||
У объекта ставки должны быть указаны все следующие атрибуты:
|
||||
* тип ставки (теги ФФД: 1199 для предмета расчёта; 1105, 1104, 1103, 1102, 1107, 1106 для чека) - все типы перечислены в классе `AtolOnline\Constants\VatTypes` (по умолчанию `NONE`)
|
||||
* размер налога (теги ФФД: 1200 для предмета расчёта; 1105, 1104, 1103, 1102, 1107, 1106 для чека)
|
||||
|
||||
> Все эти атрибуты являются **обязательными**.
|
||||
|
||||
Установить тип ставки НДС можно следующими способами:
|
||||
|
||||
```php
|
||||
// 1 способ - через конструктор
|
||||
$vat = new AtolOnline\Entities\Vat(
|
||||
AtolOnline\Constants\VatTypes::VAT20 // тип ставки
|
||||
$vat = new Vat(
|
||||
VatTypes::VAT10, // тип ставки
|
||||
123.45 // сумма в рублях, от которой считать ставку
|
||||
);
|
||||
|
||||
// 2 способ - через сеттер
|
||||
$vat = (new AtolOnline\Entities\Vat())
|
||||
->setType(AtolOnline\Constants\VatTypes::VAT20); // тип ставки
|
||||
```
|
||||
|
||||
Размер налога высчитывается автоматически из общей суммы.
|
||||
Сумму, от которой нужно расчитать размер налога, можно передать следующими способами:
|
||||
Для типа и суммы имеются отдельные сеттеры:
|
||||
|
||||
```php
|
||||
// 1 способ - через конструктор
|
||||
$vat = new AtolOnline\Entities\Vat(
|
||||
AtolOnline\Constants\VatTypes::VAT10, // тип ставки
|
||||
1234.56 // общая сумма в рублях
|
||||
);
|
||||
|
||||
// 2 способ - через сеттер
|
||||
$vat = (new AtolOnline\Entities\Vat())
|
||||
->setType(AtolOnline\Constants\VatTypes::VAT10) // тип ставки
|
||||
->setSum(150); // общая сумма в рублях
|
||||
$vat->setType(VatTypes::VAT20)
|
||||
->setSum(100.15); // 123.45 заменится на 100.15
|
||||
```
|
||||
|
||||
Сумму можно установить и до установки типа ставки.
|
||||
Объект её запомнит и пересчитает итоговый размер налога при смене типа ставки:
|
||||
Общую сумму, из которой расчитывается размер налога, можно увеличить, используя метод `addSum()`. Указанная в рублях
|
||||
сумма увеличится на указанные рубли. Для уменьшения суммы следует передать отрицательное число.
|
||||
|
||||
```php
|
||||
$vat = (new AtolOnline\Entities\Vat())
|
||||
->setSum(150) // общая сумма в рублях
|
||||
->setType(AtolOnline\Constants\VatTypes::VAT10); // тип ставки
|
||||
$vat->addSum(40) // 100.15 + 40 = 140.15р
|
||||
->addSum(-15); // 140.15 - 15 = 125.15р
|
||||
```
|
||||
|
||||
Получить установленную расчётную сумму в рублях можно через геттер `getSum()`:
|
||||
Получить установленную сумму можно через геттер `getSum()`:
|
||||
|
||||
```php
|
||||
var_dump($vat->getSum());
|
||||
// double(150)
|
||||
$vat->getSum(); // 125.15р
|
||||
```
|
||||
|
||||
Получить расчитанный размер налога в рублях можно через геттер `getFinalSum()`:
|
||||
Размер налога по ставке высчитывается из этой общей суммы. Не смотря на то, что геттер и сеттер работают с рублями, **
|
||||
расчёты производятся в копейках**. Сделать это можно через `getCalculated()`:
|
||||
|
||||
```php
|
||||
var_dump($vat->getFinalSum());
|
||||
// double(15): для примера выше это 10% от 150р = 15р
|
||||
$vat->getCalculated();
|
||||
// для примера выше это 20% от 125.15р = 25.03р
|
||||
```
|
||||
|
||||
Общую сумму, из которой расчитывается размер налога, можно увеличить, используя метод `addSum()`.
|
||||
Указанная в рублях сумма увеличится и итоговый размер налога пересчитается.
|
||||
Для уменьшения суммы следует передать отрицательное число.
|
||||
|
||||
Разберём комплексный пример изменения типа ставки и расчётной суммы:
|
||||
|
||||
```php
|
||||
use AtolOnline\{Entities\Vat, Constants\VatTypes};
|
||||
|
||||
$vat = new Vat(VatTypes::VAT20, 120);
|
||||
echo "НДС20 от 120р: ";
|
||||
var_dump($vat->getFinalSum());
|
||||
|
||||
echo "НДС10 от 120р: ";
|
||||
$vat->setType(VatTypes::VAT10);
|
||||
var_dump($vat->getFinalSum());
|
||||
|
||||
$vat->addSum(40);
|
||||
echo "НДС10 от {$vat->getSum()}р: ";
|
||||
var_dump($vat->getFinalSum());
|
||||
|
||||
$vat->setType(VatTypes::VAT20)->addSum(-20);
|
||||
echo "НДС20 от {$vat->getSum()}р: ";
|
||||
var_dump($vat->getFinalSum());
|
||||
|
||||
$vat->setType(VatTypes::VAT120);
|
||||
echo "НДС20/120 от {$vat->getSum()}р: ";
|
||||
var_dump($vat->getFinalSum());
|
||||
```
|
||||
|
||||
Результат будет следующим:
|
||||
|
||||
```
|
||||
НДС20 от 120р:
|
||||
double(24)
|
||||
НДС10 от 120р:
|
||||
double(12)
|
||||
НДС10 от 160р:
|
||||
double(16)
|
||||
НДС20 от 140р:
|
||||
double(28)
|
||||
НДС20/120 от 140р:
|
||||
double(23.33)
|
||||
```
|
||||
|
||||
Объект класса приводится к JSON-строке автоматически или принудительным приведением к `string`:
|
||||
Объект класса приводится к JSON-строке автоматически или принудительно:
|
||||
|
||||
```php
|
||||
echo $vat;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user