Водич за програмери низ API за фискализација

API за фискализација овозможуваат деловниот софтвер да разговара директно со даночната управа. Кога трговецот издава фактура, апликацијата ја испраќа до државата и добива одговор за неколку секунди. Накратко, хартиената трага сега е жив проток на податоци.

Многу земји тргнаа по овој пат во последните десет години. Државите бараат податоци во живо, помалку измами и побрзи проверки. Како резултат, обврските на развојниот тим се проширија. Даночните правила веќе не се задача за задната канцеларија. Напротив, тие седат во кодот на секоја продажба.

Поврзано: Го градите ова во сопствениот производ? Прочитајте го нашиот водич за API за фискализација и што бара едно поставување во живо.

Што прават API за фискализација

Едно API е врата меѓу два системи. API за фискализација ја насочуваат таа врата кон даночната управа. Апликацијата ја пакува фактурата, ја потпишува и ја испраќа. Потоа државата ја проверува пресметката, даночната стапка и бројот на фактурата. Ако сѐ е во ред, враќа фискален идентификатор.

Тој идентификатор е дел од законската евиденција. Вашата апликација мора да го зачува и да го отпечати на сметката. Ако проверката падне, API враќа код за грешка. Добриот софтвер го претвора тој код во јасни зборови за касиерот.

Од каса, текот изгледа едноставно. Под него, сепак, многу работи мора да тргнат како треба. На пример, апликацијата мора да ја прочита точната даночна стапка, да го обликува товарот според спецификацијата, да се автентицира и внимателно да го протолкува секој одговор.

Зошто ова е важно за софтверските тимови

Некои тимови сѐ уште ја третираат даночната работа како сметководствена ситница. Всушност, API за фискализација денес се на критичната патека на приходот. Неуспешен повик може да сопре продажба. Слично, истечен сертификат може да го запре фактурирањето на цела локација.

Поради тоа, планирајте ја фискалната работа додека ја цртате архитектурата. Закачувањето подоцна води кон кршлив код. Барањата исто така се менуваат. Државите додаваат полиња, ги затегнуваат спецификациите и ја креваат летвата за криптографија. Значи, кодот мора да се прилагоди без пишување одново.

Како фактурата поминува низ API

Прво, корисникот ја креира фактурата во апликацијата. Ставките, цените, даночните категории и податоците за купувачот доаѓаат од базата.

Второ, апликацијата сама ги проверува тие податоци. Недостасувачки даночен број или погрешен збир треба да се видат пред да излезе повикот. Раната проверка намалува залудни барања и му помага на операторот брзо да ги поправи грешките.

Потоа апликацијата го обликува товарот. Постарите државни портали очекуваат XML. Поновите примаат и JSON. Структурата мора да одговара на објавената спецификација, бидејќи мал пропуст значи одбивање.

Следува доказот за идентитет. Зависно од земјата, тоа може да биде клуч за API, токен, потпишан сертификат или взаемен TLS. OAuth 2.0 е основата за многу токен текови.

На крај, даночната управа ја врши својата проверка и одговара. Успехот дава фискален идентификатор. Неуспехот дава код за грешка што мора да го запишете и да го прикажете.

Технологиите што ќе ги сретнете

REST е норма кај поновите API за фискализација. Се потпира на обични HTTP глаголи, затоа добро легнува на облачна и мобилна работа. XML сепак е чест, бидејќи многу даночни портали излегоа пред JSON да победи.

Криптографијата е подеднакво важна. Некои системи бараат потпишан отпечаток на секое барање, што докажува дека датотеката не се сменила на патот. Освен тоа, целиот сообраќај треба да оди преку HTTPS со тековна верзија на TLS.

Никогаш не чувајте пристапни податоци во кодот или во споделена конфигурациска датотека. Користете управуван менаџер на тајни. Тоа ја олеснува ротацијата на клучеви и го држи радиусот на штетата мал. OWASP Top Ten ги опишува овие ризици подетално.

Грешки и повторни обиди

Ниту едно API не работи цело време, а API за фискализација не се исклучок. Даночните портали имаат прозорци за одржување. Врските паѓаат. Лоши податоци поминуваат. Добриот софтвер планира за сите три случаи.

Прво, поделете ги падовите во две групи. Истек на време или 503 е краткотраен, затоа повторен обид со чекање е исправен. Одбиен даночен број не е, бидејќи само операторот може да го поправи.

Второ, запишувајте доволно за да го обновите целиот повик. Идентификатор на барањето, време, статусен код и број на обиди се доволни. Сепак, држете ги податоците за купувачите надвор од тие записи.

Трето, известете човек кога падовите се повторуваат. Раното предупредување спречува мал дефект да прерасне во изгубен работен ден.

Запрете ги двојните фактури

Замислете го овој случај. Апликацијата испраќа фактура. Државата ја регистрира. Потоа врската паѓа пред да стигне одговорот. Без заштита, апликацијата ќе ја испрати истата фактура двапати.

Многу API за фискализација токму затоа примаат клуч за идемпотентност. Истиот клуч дава еден запис, колку и пати да повикате. Спецификацијата на HTTP одредува кои методи се безбедни за повторување.

Исто така, запишете локален запис пред секој повик. Тогаш апликацијата може да се праша дали веќе ја испратила таа фактура. Внимателното водење на состојбата ги штеди и трговецот и неговите купувачи од забуна.

Брзина и обем

Продавница со дваесет фактури дневно нема многу грижи. Синџир со илјадници на час е сосема друг случај.

Не блокирајте ја касата на далечински повик ако прописите дозволуваат подоцнежно пријавување. Наместо тоа, ставете ја секоја фактура во редица со пораки. Позадинските работници потоа ги обработуваат повиците независно.

Ова ја држи апликацијата брза и ја смирува под оптоварување. Освен тоа, ако порталот падне, редицата ја чува работата додека тој не се врати. Додавањето работници е поевтино од преправка.

Следете ги и времињата на одговор. Растечкото задоцнување ве предупредува за проблем долго пред корисникот.

ERP и системи за продажно место

Еден ERP веќе го држи најголемиот дел од тоа што го бара даночната управа. Записите за купувачите, цените, ДДВ категориите и условите живеат таму. Затоа фискалниот чекор треба да ги чита тие податоци, наместо да ги дуплира.

Застарените податоци се вообичаена причина за одбивање. На пример, држете ги даночните стапки и записите за купувачите усогласени меѓу модулите. Дизајн воден од настани помага тука, бидејќи апликацијата реагира кога ќе се појави фактура наместо да ја бара.

Трговците бараат брзина на касата. Работата без врска исто така е важна, каде што локалните прописи дозволуваат. Покажете им на вработените кои продажби поминале и кои сѐ уште чекаат. Потоа усогласете ја редицата штом врската се врати.

Правилата се разликуваат по земја

Една интеграција нема да го покрие секој пазар, бидејќи API за фискализација се национални творби. Некои земји ја одобруваат фактурата пред купувачот да ја види. Други ја земаат по продажбата, во зададен рок за пријавување.

Нумерирањето на фактурите исто така се разликува. Една земја сака една непрекината низа. Друга дозволува низа по продавница или по терминал. Пресметката на данокот исто така се разликува, па држете ги стапките и правилата за заокружување во конфигурација, никогаш во кодот.

Над сѐ, држете ја логиката по земја во сопствен модул. Тогаш нов пазар значи нов модул, наместо преправка на јадрото.

Тестирајте пред да излезете во живо

Повеќето даночни тела водат песочник што ја отсликува живата услуга. Користете го агресивно. Чиста фактура е само еден случај.

Тестирајте и погрешни даночни броеви, истечени сертификати, двојни повици, истек на време и прекинати врски. Автоматските тестови потоа го штитат тоа однесување на секое издание. Освен тоа, покриеноста со регресиони тестови станува поважна како што расте апликацијата.

Како може да помогне Square Software

Square Software гради деловен софтвер по нарачка и презема работа на фискална интеграција во Албанија. Надвор од Албанија продаваме општа софтверска работа: веб, мобилни, ERP и системи за продажно место, како и поддршка за тимови.

Дизајнираме за долг рок. Во пракса тоа значи чисти граници меѓу модулите, внимателно ракување со пристапни податоци, редица таму каде што оптоварувањето бара, и тестови што ја држат фискалната патека исправна додека правилата се менуваат.

Сакате втор пар очи на вашиот фискален тек? Разговарајте со тимот, или прочитајте како ги вградуваме фискалните правила во софтвер по нарачка.

Што следува

Пријавувањето во живо продолжува да се шири, затоа API за фискализација ќе стигнат до повеќе пазари. Државите ја сакаат брзината и чистата ревизорска трага. Слично, фирмите ја сакаат помалата рачна работа.

Облачните платформи ќе носат поголем дел од товарот. Освен тоа, попаметната проверка може да фати чудни фактури пред воопшто да стигнат до државата. Со време, фактурирањето, залихите и даночното пријавување ќе седат во еден поврзан тек.

Тимовите што денес градат флексибилен софтвер најдобро ќе се снајдат со утрешните правила. Мали модули, дисциплинирана безбедност и солидна работа со API остануваат темел.

Чести прашања

Што се API за фискализација? Тоа се интерфејси што му дозволуваат на деловниот софтвер да пријавува фактури до даночната управа и да добие законски одговор.

Кому му требаат? На продавници, ресторани, хотели, клиники и на секоја фирма со ERP или систем за продажно место на пазар со даночно пријавување во живо.

Дали API за фискализација се исти во секоја земја? Не. Секоја земја си поставува своја спецификација, свои правила за идентитет и свој формат на фактура. Затоа секогаш читајте ја локалната документација.

Зошто безбедноста е толку важна? Бидејќи фактурите носат пари и податоци за купувачите. Слаби пристапни податоци или незаштитен сообраќај ги изложуваат обете.

Дали API за фискализација се вклопуваат во ERP? Да. Повеќето ERP, сметководствени и системи за продажно место денес ги поврзуваат за да ја намалат рачната работа.

Ви треба помош со фискална градба во Албанија? Square гради и одржува API за фискализација за продажни места, ERP и SaaS производи во Албанија. Погледнете што опфаќа таа работа или разговарајте со тимот.