/php-ofd-sdk

Библиотека работает с API операторов фискальных данных (ОФД)

Primary LanguagePHPMIT LicenseMIT

Описание

Библиотека предоставляет унифицированный интерфейс (см. ProviderInterface) работы с различными ОФД (оператор фискальных данных) при получении данных о фискальных документах (чеках).

Основная цель - облегчить интеграцию проекта при работе с разными API операторов. Например, при синхронизации данных о выбитых на кассе чеках и данных ушедших в налоговую.

Scrutinizer Code Quality Build Status

Поддерживаемые ОФД

Установка

Через composer командой: composer require alekciy/php-ofd-sdk

Пример

Ниже приведен пример работы для Такском и Яндекс.ОФД.

<?php

include_once __DIR__ . '/vendor/autoload.php';

use alekciy\ofd\providers\taxcom\Client as TaxcomClient;
use alekciy\ofd\providers\taxcom\Credentials as TaxcomCredentials;
use alekciy\ofd\providers\taxcom\Taxcom;
use alekciy\ofd\providers\yandex\Client as YandexClient;
use alekciy\ofd\providers\yandex\Credentials as YandexCredentials;
use alekciy\ofd\providers\yandex\Yandex;

// ============ Инициализация клиента ============
// У каждого провайдера свои требование при работе через API поэтому инициализация клиента
// зависит от используемого провайдера.

// Инициализируем Такском API клиент
$credentials = new TaxcomCredentials(
	'api-lk-ofd.taxcom.ru',
	'логин',
	'пароль',
	'токен'
);
$agreementNumber = 'Номер договора';
$client = new TaxcomClient($credentials, $agreementNumber);
$taxcom = new Taxcom($client);

// Инициализация Яндекс.ОФД клиент
$credentials = new YandexCredentials(
	'api.ofd.yandex.net',
	'аутентификационный ключ',
	'авторизационный ключ'
);
$client = new YandexClient($credentials);
$yandex = new Yandex($client);

// ============ Получение данных ============
// Получаем список точек продаж с Такском...
$outletList = $taxcom->getOutletList();
$outlet = current($outletList);
// ...список касс с первой точки...
$cashDeskList = $taxcom->getCashDeskList($outlet);
$cashDesk = current($cashDeskList);
// ...и список смен с первой кассы
$shiftList = $taxcom->getShiftList($cashDesk);

// Получение смен через Яндекс.ОФД выглядит точно так же
$outletList = $yandex->getOutletList();
$outlet = current($outletList);
$cashDeskList = $taxcom->getCashDeskList($outlet);
$cashDesk = current($cashDeskList);
$shiftList = $taxcom->getShiftList($cashDesk);

Тесты

В библиотеке используются два вида тестов:

  • юнит для проверки правильности работы самой библиотеки;
  • интеграционные для проверки работы API заданного ОФД.

Юнит тесты

Для запуска тестов нужно:

  1. выполнить командуcomposer test-unit.

Интеграционные тесты

Для запуска тестов нужно:

  1. скопировать файл нужного ОФД (например, taxcom) tests/credentials/ОФД.example.php в файл tests/credentials/ОФД.php;
  2. вписать требуемые реквизиты доступа в tests/credentials/ОФД.php;
  3. выполнить команду composer test-integration-ОФД.

Основные термины

В таблице приведены термины в порядке удобном для понимания.

ОФД Оператор Фискальных Данных Сервис принимающий с кассово аппарата данные о выбитых чеках и передающий их в налоговую службу.
ККТ Контрольно Кассовая Техника Кассовый аппарат выбивающий чеки либо на бумаге, либо в электронном виде.
ККМ Контрольно Кассовая Машина Устаревшее название ККТ.
ФД Фискальный Документ Документ отправляемый в налоговую службу. Кассовый чек является частным случаем ФД. Все типы ФД перечисленые в константах DocumentInterface в виде классов документов.
ФФД Формат Фискальных Данных По сути спецификация описывающая свойства (реквизиты) и их значения, которые могут быть у ФД. Регламентируется приказами ФНС России (на основании 54-ФЗ). Например, приказ № ЕД-7-20/662 По состоянию на 2022 год есть три версии ФФД: 1.0, 1.05, 1.1 и 1.2.
Тег ФД - По сути имя свойства (реквизита) ФД которые передаются в ОФД. Например, в теге 1037 касса передает свой регистрационный номер. Поддерживаемые теги находятся в директории tags.