Импортер за СУПТО Фактуриел

СУПТО Фактуриел предоставя възможност за импортиране на поръчки/продажби в СУПТО от външни източници (онлайн магазини и др.). Услугата се предлага като допълнителна възможност и служи за автоматизиране на процеса по регистриране на продажби в СУПТО. В момента импортера е в процес на одобрение от НАП. Ако проявявате интерес или въпроси свързани с "СУПТО импортер", моля свържете се с нас, за да научите условията за ползване. Преди да продължите да четете е важно да знаете, че СУПТО Фактуриел работи само с фискални устройства на фирма TREMOL.

Импортер за СУПТО Фактуриел

За кого е предназначен импортера?

Импортерът е създаден в полза на потребителите на СУПТО "Фактуриел", които са собственици на уеб сайт, онлайн магазин или друг софтуер, които обработват плащания с наложен платеж или други начини изискващи издаване на фискален бон и в същия момент нямат възможност да преработят системите си като СУПТО.


Как работи СУПТО импортера?

Когато има направена поръчка например в онлайн магазин, чрез API се изпраща информация за поръчката (продажбата) към СУПТО. Информацията, която се изпраща е общата сума на поръчката, начина на плащане (ако е известен към момента), идентификатор на уеб сайта, оригинален номер на поръчка в онлайн магазина, номер на търговския обект, който ще я обработи (взима се от номенклатурния списък в СУПТО) и номер на работното място (взима се също от СУПТО). Към функцията се подава и масив с описание на поръчаните стоки/услуги. За всеки стока/услуга се изпраща информация за наименование, артикулен номер, количество, мерна единица, продажна цена. Артикулният номер е много важен ако работите с модул "Склад", тъй като чрез него се осъществява разпознаване на стоките

Понеже тази услуга е предназначена за най-различни платформи и уеб сайтове, всеки собственик определя на кое място да сложи програмния код и точно да го преработи и кога и как да го изпълни. СУПТО импортер Фактуриел има грижа да обработва всички данни, които са подадени към него и гарантира, че не се отклоняват поръчки по никакъв начин. API обработва всички постъпило към него като го записва директно в базата с данни.

В момента на записване в базата данни има много неясни фактори отговарящи за генерирането на УНП и затова УНП се генерира винаги от СУПТО Фактуриел. Главните причина са:

  • много е вероятно СУПТО да не работи и няма как да се знае кое фискално устройство ще обработи поръчката;
  • API прави връзка на онлайн магазина с базата данни и няма пряка комуникация със СУПТО;
  • ако не работи СУПТО не може да се провери текущото състояние на фискалното устройство;
  • не се знае кой оператор ще обработи поръчката, за да се запише неговия код.
Кодът на оператора при първоначалното регистриране на продажбата в СУПТО е 0. Този код е нула, тъй като ако със СУПТО работят повече на брой оператори, в момента на импортиране не се знае кой оператор ще обработи поръчката. Когато поръчката е импортирана, тя се появява в СУПТО в списъка „ИМПОРТИРАНИ ПОРЪЧКИ”. Тези поръчки все още нямат УНП и не са присвоени към оператор и фискално устройство.

Продажби очакващи обработка в СУПТО

При първоначалното отваряне в СУПТО (натискането на поръчка от списъка с импортирани поръчки) се правят нужните проверки на фискалното устройство за свързаност. Ако то е изключено или не е в готовност на екрана излиза съобщение със съответната грешка и операцията се прекратява. Ако всичко е наред се генерира УНП по познатия начин и се записва заедно с кода на текущия оператор и кода на фискалното устройство в базата данни. След това поръчката (продажбата) става част от останалите продажби в СУПТО и се обработва по стандартния начин.


Колко струва?

Таксата за ползване на услугата е 96 лв. за година. Тя се заплаща отделно и няма връзка с таксата за СУПТО Фактуриел и модул "Склад".


Инсталация

Връзката се осъществява посредством програмния интерфейс за комуникация RESTful API. Ако софтуерът, който желаете да комуникира със СУПТО Фактуриел е написан на програмния език PHP, съхранете следния код във файл supto-fakturiel.php, който ще включите преди да изпълните функция от API. Ако използвате друг програмен език, можете да използвате показания код и да го пренапишете в зависимост от вашите нужди. В променливите $API_URL, $API_NUMBER и $API_KEY въведете стойностите, които ще получите от фирма "Уеб Арт" ЕООД след заплащане на абонаментна такса.

<?php
$API_URL = 'получава се от фирма УЕБ АРТ ЕООД';
$API_NUMBER = 'получава се от фирма УЕБ АРТ ЕООД';
$API_KEY = 'получава се от фирма УЕБ АРТ ЕООД';

function send_to_api($command, $data){
  global $API_NUMBER;
  global $API_KEY;
  $ch = curl_init();
  try{
    curl_setopt($ch, CURLOPT_URL, $API_URL.$command);
    curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Basic '. base64_encode($API_NUMBER.':'.$API_KEY)));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
    $response = curl_exec($ch);
    return json_decode($response);
  }catch (Exception $ex) {
    echo 'Грешка: '.$ex->getMessage();
  }finally{
    curl_close($ch);
  }
}
?>

Функции

1. Импортиране на поръчка/продажба в СУПТО

Функция/команда:sale_create
Предназначение:Използва се за импортиране на поръчки/продажби от външни източници (онлайн магазини и други) в СУПТО Фактуриел
Параметри: - sale - обект , който съдържа полета за:
  -order_id - код на поръчка от онлайн магазин или друг външен източник
  -payment_method_id - начин на плащане - 1 - в брой, 2 - по банка, 3 - POS/карта, 4 - Epay.BG, 5 - частично в брой, 6 - насрещно прихващане, 7 - наложен платеж, 8 - пощенски паричен превод
  -total - обща сума на поръчката в лева с ДДС
  -vat_percent - ДДС % - въведете 0, 9 или 20. Ако параметърът се пропусне се използва 0% ДДС по подразбиране
  -source_id код на източник - Задава се източника на поръчката. 1 - за първи онлай магазин, 2 - за втори и т.н.
  -object_id - код на търговски обект. Взима се от списъка в настройките на търг. обекти в СУПТО
  -station_id - код на работно място. Взима се от списъка в настройките на работните места в СУПТО
  -add_to_catalog - добавяне на стоката в номенклатурния списък със стоки. Въведете 1 ако желаете да добавите стоката в списъка с номенклатурния списък. Използва се главно за модул "Склад"
  -autoload_measure - използване на мерната единица от номенлатурния списък в СУПТО - 1 автоматично извличане, 0 - взима се от measure_id
  - rows - масив от обекти (редове на поръчка/продажба) със следните полета:
     -name - наименование на стока или услуга
     -quantity - количество на стока/услуга
     -measure_id - код на мерна единица - 70 за брой. Всички налични мерни единици можете да разгледате тук
     -price - продажна цена на стока/услуга в лева с ДДС
     -discount_percent - Процент търговска отстъпка, напр. 10
     -code - артикулен номер. Използва се ако се ползва модул "Склад"
Postman пример: https://fakturiel.com/api/v1/sale_create?sale={"client_number":"000000000", "order_id":123, "payment_method_id":7, "source_id":1, "object_id":1,"station_id":2, "add_to_catalog":1,"rows":[{"name":"ябълки", "quantity":4, "measure_id":70, "price":10, "discount_percent":50}, {"name":"круши", "quantity":1, "measure_id":90, "price":15}],"total":35,"vat_percent":20}
Резултат: {
    "error": 0,
    "sale": {
       "id": "428"
   }
}
JSON обект със следните полета:
- error - Код на грешка. Код 0 - означава, че всичко е наред.
- error_message - Описание на грешката (ако $result->error е различен от 0)
- sale - обект с поле id, което съдържа ID на продажбата в СУПТО. Важно е да се запише към съответната поръчка за следващите проверки чрез get_sale_status
Възможни грешки: - Не е подаден параметър с детайлите на поръчката! (502)
- Не е подаден номер на поръчка/продажба. (2001)
Примерен PHP код: <?php
include('supto-fakturiel.php'); // кодът е публикуван в раздел "Инсталация"

$sale = new StdClass();

$sale->client_number = '000000000'; // ЕИК на клиента, 000000000 - ако е частно лице
$sale->order_id = 123; // уникален номер на поръчка/продажба от външния източник
$sale->payment_method_id = 7; // наложен платеж
$sale->source_id = 1; // ако имате един онлайн магазин, въведете 1
$sale->object_id = 1; // взима се от списъка в настройките на търг. обекти в СУПТО
$sale->station_id = 1; // взима се от списъка в настройките на работните места в СУПТО
$sale->add_to_catalog = 1; // въведете 1 ако желаете да добавите стоката в списъка с номенклатурния списък

$sale->rows = array();

// Стока 1
$row = new StdClass();
$row->name = 'Стока 1';
$row->quantity = 4;
$row->measure_id = 70;
$row->price = 10.00;
$row->discount_percent = 50;
$sale->rows[] = $row;

// Стока 2
$row = new StdClass();
$row->name = 'Стока 2';
$row->quantity = 1;
$row->measure_id = 90;
$row->price = 15.00;
$sale->rows[] = $row;

$sale->total = 35.00; // обща сума с ДДС
$sale->vat_percent = 20; // ДДС процент

$command = 'sale_create';
$data = array('sale'=>json_encode($sale));

$result = send_to_api($command, $data);

if($result->error == 0){
echo 'Поръчката е импортирана в СУПТО с код: '.$result->sale->id; }else{
  echo $result->error_message;
}
?>

2. Получаване на статус и информация за продажба

Функция/команда:sale_get_status
Предназначение:Използва се за извличане на УНП и детайли на продажба след импортиране на поръчка в СУПТО Фактуриел
Параметри: sale_id - Код на продажбата от СУПТО, която се получава след регистриране на поръчка в СУПТО чрез sale_create
Postman пример: https://fakturiel.com/api/v1/sale_get_status?sale_id=428
Резултат: {
    "error": 0,
    "sale": {
       "number": "",
       "anul": "0",
       "completed": "0",
       "device_id": "0",
       "operator_id": "0",
       "object_id": "1",
       "station_id": "2",
       "import_date": "2019-07-03 22:23:51",
       "added": "",
       "finished": "",
       "client_id": "0",
       "total": "35.00",
       "anul_date": null,
       "anul_operator_id": "0",
       "source_id": "1",
       "rows": [
          {
             "id": "555",
             "item_id": "4662",
             "name": "ябълки",
             "quantity": "4",
             "measure_id": "70",
             "price": "10",
             "discount_percent": "50",
             "row_total": "20.00",
             "code": ""
         },
          {
             "id": "556",
             "item_id": "4663",
             "name": "круши",
             "quantity": "1",
             "measure_id": "90",
             "price": "15",
             "discount_percent": "0",
             "row_total": "15.00",
             "code": ""
         }
      ]
   }
}
JSON обект със следните полета:
-error - Код на грешка. Код 0 - означава, че всичко е наред.
-error_message - Описание на грешката (ако $result->error е различен от 0)
-sale - обект със следните полета:
   -import_date - Време на импортиране в СУПТО във формат YYYY-MM-DD hh:mm:ss.
   -added - Време на отваряне на продажбата в СУПТО (генериране на УНП) във формат YYYY-MM-DD hh:mm:ss. Полето е празно ако не е обработена
   -finished - Време на приключване на продажбата в СУПТО във формат YYYY-MM-DD hh:mm:ss. Полето е празно ако не е приключена
   -number съдържа УНП на продажбата от СУПТО
   -anul - 1 ако продажбата е анулирана в СУПТО
   -anul_date - Дата на анулиране във формат YYYY-MM-DD hh:mm:ss. 0000-00-00 00:00:00 - Ако не е е анулирана
   -anul_operator_id - Код на оператор анулирал продажбата
   -completed - 1 ако продажбата е обработена и приключила.
   -device_id - Код на фискално устройство, което е използвано за УНП.
   -operator_id - Код на оператор, който е отворил продажбата в СУПТО.
   -object_id - Код на търговски обект, в който е импортирана продажбата.
   -station_id - Код на работно място, на който е импортирана продажбата.
   -client_id - Код на клиент
   -total - Обща сума
   -source_id - Код на външен източник на продажба. 0 ако е регистрирана в СУПТО
   - rows - масив от обекти (Редове на продажба) със следните полета:
     -id - Уникален код
     -item_id - Уникален код на стока/услуга
     -name - Име на стока/услуга
     -quantity - Количество
     -measure_id - Код на мерна единица (70 за брой). Всички налични мерни единици можете да разгледате тук
     -price - Продажна цена на стока/услуга в лева
     -discount_percent - Процент търговска отстъпка
     -row_total - Обща сума за реда
     -code - Артикулен номер
Примерен PHP код: <?php
include('supto-fakturiel.php'); // кодът е публикуван в раздел "Инсталация"

$command = 'sale_get_status';
$data = array('sale_id'=>386);

$result = send_to_api($command, $data);

if($result->error == 0){
  $sale = $result->sale;
  echo 'Време на импортиране в СУПТО: '.$sale->import_date;
  echo 'Време на отваряне: '.$sale->added;
  echo 'Време на приключване: '.$sale->finished;
  echo 'УНП: '.$sale->number;
  echo 'Анулирана: '.$sale->anul;
  echo 'Дата на анулиране: '.$sale->anul_date;
  echo 'Код на оператор анулирал продажбата: '.$sale->anul_operator_id;
  echo 'Приключена: '.$sale->completed;
  echo 'Код на фискално устройство :'.$sale->device_id;
  echo 'Код на оператор: '.$sale->operator_id;
  echo 'Код на търговски обект: '.$sale->object_id;
  echo 'Код на работно място: '.$sale->station_id;
  echo 'Код на клиент: '.$sale->client_id;
  echo 'Обща сума: '.$sale->total;
  echo 'Код на външен източник: '.$sale->source_id;

  if(isset($sale->rows)){
    for($i = 0; $i < count($sale->rows); $i++){
      echo 'Код на ред: '.$sale->rows[$i]->id;
      echo 'Код на стока/услуга: '.$sale->rows[$i]->item_id;
      echo 'Име на стока/услуга: '.$sale->rows[$i]->name;
      echo 'Количество: '.$sale->rows[$i]->quantity;
      echo 'Код на мярка: '.$sale->rows[$i]->measure_id;
      echo 'Продажна цена: '.$sale->rows[$i]->price;
      echo 'Процент отстъпка: '.$sale->rows[$i]->discount_percent;
      echo 'Обща сума за реда: '.$sale->rows[$i]->row_total;
      echo 'Артикулен номер: '.$sale->rows[$i]->code;
    }
  }
}else{
  echo $result->error_message;
}
?>
"Фактуриел" е за всеки

Регистриран в НАП съобразно Наредба Н-18, онлайн платформата е подходяща за търговска дейност от всякакъв тип.