Импортер за СУПТО Фактуриел
СУПТО Фактуриел предоставя възможност за импортиране на поръчки/продажби в СУПТО от външни източници (онлайн магазини и др.). Услугата се предлага като допълнителна възможност и служи за автоматизиране на процеса по регистриране на продажби в СУПТО. Този импортер е одобрен от НАП като допълнителен модул към ФАКТУРИЕЛ. Ако проявявате интерес или въпроси свързани с "СУПТО импортер", моля свържете се с нас, за да научите условията за ползване.
ВАЖНО!
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":0,"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
|
3. Списък с последно издадени документи чрез API
Функция/команда: | document_list |
Предназначение: | Използва се за получаване на списък с последно издадените фактури на клиент |
Параметри: |
1.type - тип документи (1 /по подразбиране/ - фактура, 2 - проформа, 3 - стокова разписка, 4 - протокол, 5 - доставки)2. client_number - ЕИК (може да се пропусне)3. limit - брой резултатите (ако се пропусне по подразбиране се връщат последните 5 документа) |
Postman пример: | https://fakturiel.com/api/v1/document_list?type=1&client_number=203772991 |
Резултат: |
{
- error - Код на грешка *- documents - масив с намерените документи представени съдържащ обекти със следните полета:- id - ID- doc_number - Номер на документа- doc_kind - Вид на документа /0 - фактура, 1 - кредитно известие, 2 - дебитно известие/- doc_date - Дата на документа във формат YYYY-MM-DD- total - Сума- payment_method_id - Код на начин на плащане *- client_name - Име на клиент- client_number ЕИК на клиент- client_id - ID на клиент- paid - Платен /0 - неплатен, 1 - платен, 2 - частично платен/- anul - Анулиран /0 - активен, 1 - анулиран/- sent_to_client - Изпратен на клиент /показва колко пъти е изпратен/- payment_note - Пояснения |
Възможни грешки: |
- Невалиден вид на документ. Използвайте 1 за фактура/и, 2 за проформа/и, 3 за стокови разписка/и или 4 за протокол/и. (3) |
Примерен PHP код: |
include('supto-fakturiel.php'); // кодът е публикуван в раздел "Инсталация" |
4. Получаване на информация за документ чрез API
Функция/команда: | document_retrieve |
Предназначение: | Получаване на информация за документ |
Параметри: | 1. type - Вид на документ (1 - фактура, 2 - проформа, 3 - стокова разписка, 4 - протокол)2. id - Код на документ |
Postman пример: | https://fakturiel.com/api/v1/document_retrieve?type=1&id=2 |
Резултат: |
{ - error - Код на грешка *- document - обект със следните полета:- numbers_id - Код на търговски обект - 0 - основен, 1- втори и т.н.- number - Номер на документ- kind - Подтип на фактура - 0 - фактура, 1 - кр. известие, 2 - деб. известие- date - Дата на документ- proforma_number - Номер на проформа - ако фактурата е създадена от проформа- proforma_date - Дата на проформа - ако фактурата е създадена от проформа- event_date - Дата на данъчно събитие- place - Място на сделката- cl_id - ID на клиент- cl_name - Име на клиента- cl_place - Място на клиент- cl_address - Адрес на клиент- cl_eik - ЕИК на клиент- cl_dds - ИН по ДДС на клиент- cl_face - МОЛ на клиент- cl_phone - Телефон на клиент- face - МОЛ на доставчика- reason - Основание за промяна при известие- tax_base - Данъчна основа- dds_percent - ДДС процент- dds - ДДС сума- total - Обща сума- retail_tax_base - Данъчна основа за Invoice- retail_dds - ДДС сума за Invoice- retail_total - Обща сума за Invoice- invoice_currency_id - ID на валута за Invoice- currency_fixing - Фиксинг на Invoice валута спрямо BGN- payment_method_id - Начин на плащане- payment_note - Допълнителни бележки- account_id - ID на банкова сметка- receiver - Получател- creator - Съставител- iban - IBAN - ако плащането е по банка- bank - Име на банка- bic - BIC на банка- pay_until - ID на плащане до - 0 - без срок, 1 - 1 ден, 2 - 2 дни, 3 - 3 дни, 4 - 1 седмица, 5 - 2 седмици, 6 - 1 месец, 7 - 45 дни, 8 - 2 месеца, 9 - 3 месеца- pay_until_str - Срок на плащане (текст)- anul - Анулиран документ - 0 - активен, 1 - анулиран- null_value - Основание за нулева ставка или неначисляване на ДДС- added - Дата на създаване на документ- paid - Платен - 0 - неплатен, 1 - платен- sent_to_client - Изпратен до клиент - брой изпращания- sent_to_accountant - Изпратен до счетоводство - брой изпращания- rows Редове на документа - масив от обекти със следните полета:1. row_index - Индекс на ред2. article_name - Име на стока/услуга3. measure_id - ID на мерна единица - за повече информация, вижте тук.4. quantity - Количество5. price - Ед. цена6. discount - Търговска отстъпка |
Възможни грешки: |
- Невалиден вид на документ. (3) - Не е посочен ID номер на документ. (581) - Документът не е открит. (582) |
Примерен PHP код: |
include('supto-fakturiel.php'); // кодът е публикуван в раздел "Инсталация" |
Таблица с използвани начини на плащане
Код | Начин на плащане |
---|---|
1 | В брой |
2 | По банка |
3 | POS/карта |
4 | Epay.BG |
5 | Частично в брой |
6 | Насрещно прихващане |
7 | Наложен платеж |
8 | Пощенски паричен превод |
Таблица с кодове на грешки
Код | Грешка |
---|---|
0 | Функцията е изпълнена успешно. |
1 | Неразпознато име на функция. |
3 | Невалиден вид на документ. Използвайте 1 за фактура/и, 2 за проформа/и, 3 за стокови разписка/и или 4 за протокол/и. |
4 | Грешка при изпълнение на заявка. |
10 | Не сте се идентифицирали с ЕИК и ключ. |
51 | Не е въведен ЕИК за достъп. |
52 | Не е въведен API ключ за достъп. |
53 | Грешка при осъществяване на достъп или изтекъл абонамент. Моля свържете се с нас за повече подробности |
54 | Грешен ключ за достъп. |
55 | Вече сте осъществили връзка. Моля използвайте някоя функция от FAPI. |
56 | Изтекъл лиценз. |
57 | Изтекъл абонамент за API функционалност. |
104 | С този ЕИК вече съществува клиент в базата данни. |
111 | Не е въведен ЕИК или ID. |
112 | Клиентът не е открит. |
121 | Не е посочен ID номер на клиент. |
122 | Не е изпратен обект като втори параметър на функцията. |
123 | Информацията за клиенти, за които е въведено 000000000, 111111111 или 999999999 за ЕИК номер, може да бъде обновявана само чрез ID. |
124 | Не е изпратена информация за обновяване. |
125 | Има повече от един клиент с този ЕИК/ID. |
131 | Клиенти, за които е въведено 000000000, 111111111 или 999999999 за ЕИК номер могат да бъдат изтривани само чрез ID. |
141 | Не e въведен текст за търсене. Въведете част от името или телефонен номер. |
142 | Не са открити съвпадения. |
151 | Нямате въведени клиенти. |
204 | С този артикулен номер вече съществува запис в базата данни. |
211 | Не е въведен артикулен номер или ID. |
212 | Стоката не е открита. |
225 | Има повече от един артикул с този номер/ID. |
241 | Не e въведен текст за търсене. Въведете част от името или артикулния номер. |
242 | Не са открити съвпадения. |
501 | Не е въведен ЕИК. Можете да използвате 000000000, 111111111 или 999999999 ако не знаете ЕИК на клиента! |
502 | Не е подаден последния параметър с детайлите на документа и редовете! |
503 | Клиент с този ЕИК не е открит. Моля, въведете го в базата данни преди да продължите. |
551 | След този документ има издадени други и затова не може да бъде изтрит! |
571 | Не e въведен текст за търсене. |
572 | Не e въведен тип за търсене. |
581 | Не е посочен ID номер на документ. |
582 | Документът не е открит. |
591 | Невалидна година! Въведете число за година - напр. 2020. |
592 | Невалиден начин на плащане! Въведете цифра от 1 до 5 или 0 за всички. |
601 | Клиентът няма въведен email адрес. |
602 | Документът не е асоцииран с клиент. |
801 | Не е посочен артикулен номер. |
802 | Не е открит продукт с този артикулен номер. |
2001 | Не е подаден номер на поръчка/продажба. |
2002 | Не е открита продажба с това ID в СУПТО. |
2003 | Не е подаден параметър с детайлите на продажбата. |
2004 | Сумата на поръчката/продажбата е 0. |
2005 | Неразпознат начин на плащане. |
2006 | Не са подадени редове на поръчка/продажба. |
Забележка: При възникване на грешка ни пишете, за да получите повече информация. |