Импортер за СУПТО Фактуриел
СУПТО Фактуриел предоставя възможност за импортиране на поръчки/продажби в СУПТО от външни източници (онлайн магазини и др.). Услугата се предлага като допълнителна възможност и служи за автоматизиране на процеса по регистриране на продажби в СУПТО. Този импортер е одобрен от НАП като допълнителен модул към ФАКТУРИЕЛ. Ако проявявате интерес или въпроси свързани с "СУПТО импортер", моля свържете се с нас, за да научите условията за ползване.
ВАЖНО!
1. Към момента такъв начин на комуникация не е описан нито в ЗДДС, нито в Наредба Н-18 или друг закон или наредба. Този тип комуникация е описана само в схемите публикувани в уеб сайта на НАП.
2. Фискалните бонове не се печатат автоматично при постъпване на информация в СУПТО. Продажбите се преглеждат и приключват ръчно от оператор в СУПТО. При приключване на продажба се печата фискален бон. За повече информация прочетете по-надолу.
За кого е предназначен импортера?
Импортерът е създаден в полза на потребителите на СУПТО "Фактуриел", които са собственици на уеб сайт, онлайн магазин или друг софтуер, които обработват плащания с наложен платеж или други начини изискващи издаване на фискален бон и в същия момент нямат възможност да преработят системите си като СУПТО.
Как работи СУПТО импортера?
Когато има направена поръчка например в онлайн магазин, чрез API се изпраща информация за поръчката (продажбата) към СУПТО. Информацията, която се изпраща е общата сума на поръчката, начина на плащане (ако е известен към момента), идентификатор на уеб сайта, оригинален номер на поръчка в онлайн магазина, номер на търговския обект, който ще я обработи (взима се от номенклатурния списък в СУПТО) и номер на работното място (взима се също от СУПТО). Към функцията се подава и масив с описание на поръчаните стоки/услуги. За всеки стока/услуга се изпраща информация за наименование, артикулен номер, количество, мерна единица, продажна цена. Артикулният номер е много важен ако работите с модул "Склад", тъй като чрез него се осъществява разпознаване на стоките.
Тази услуга е предназначена за най-различни платформи и уеб сайтове и поради тази причина всеки собственик определя на кое място да сложи програмния код и кога да го изпълни. СУПТО импортер Фактуриел има грижа да обработва и записва директно в базата данни всички данни, които са подадени и гарантира, че не се отклоняват поръчки по никакъв начин.
В момента на записване в базата данни има много неясни фактори отговарящи за генерирането на УНП и затова УНП се генерира винаги от СУПТО Фактуриел. Главните причина са:
- много е вероятно СУПТО да не работи и няма как да се знае кое фискално устройство ще обработи поръчката;
- API прави връзка на онлайн магазина с базата данни и няма пряка комуникация със СУПТО;
- ако не работи СУПТО не може да се провери текущото състояние на фискалното устройство;
- не се знае кой оператор ще обработи поръчката, за да се запише неговия код в УНП.
При първоначалното отваряне в СУПТО (натискането на поръчка от списъка с импортирани поръчки) се правят нужните проверки на фискалното устройство за свързаност. Ако то е изключено или не е в готовност на екрана излиза съобщение със съответната грешка и операцията се прекратява. Ако всичко е наред се генерира УНП по познатия начин и се записва заедно с кода на текущия оператор и кода на фискалното устройство в базата данни. След това поръчката (продажбата) става част от останалите продажби в СУПТО и се обработва по стандартния начин.
Колко струва?
Таксата за ползване на услугата е 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 - обект , който съдържа полета за:» client_number - ЕИК на клиент. Използва се 000000000 ако е частно лице» 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} |
Резултат: |
{ JSON обект със следните полета: » error - код на грешка. Код 0 - означава, че всичко е наред.» error_message - описание на грешката (ако $result->error е различен от 0)» sale - обект с поле id , което съдържа ID на продажбата в СУПТО. Важно е да се запише към съответната поръчка за следващите проверки чрез get_sale_status |
Възможни грешки: |
- Не е подаден параметър с детайлите на поръчката! (502) - Не е подаден номер на поръчка/продажба. (2001) |
Примерен PHP код: |
<?php
|
2. Получаване на статус и информация за продажба
Функция/команда: | sale_get_status |
Предназначение: | Използва се за извличане на УНП и детайли на продажба след импортиране на поръчка в СУПТО Фактуриел |
Параметри: |
sale_id - код на продажбата от СУПТО, която се получава след регистриране на поръчка в СУПТО чрез sale_create |
Postman пример: | https://fakturiel.com/api/v1/sale_get_status?sale_id=428 |
Резултат: |
{ 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
|