Manualul API-ului Poleo Fiscal

Răspunde chiar și când casa de marcat este deconectată - întrebarea este despre aplicație, nu despre aparat. Pentru starea casei ai /cases/{id}/status.

Dacă ai o singură casă, poți sări peste tot ce ține de identificator: orice operațiune fără câmpul case merge la prima casă activă. Cu două sau mai multe, trimite mereu case - altfel bonul iese pe aparatul greșit. Recomandarea rămâne să individualizezi casa indiferent de câte ai.

• Poți da id-ul sau numele casei - merg amândouă. Ca good practice recomandăm să 'chemi' mereu casele folosind id-ul și nu denumirea alocată acesteia din secțiunea de configurare.
• Casa deconectată nu este o eroare: primești 200 cu "online": false și motivul în message.
• Durează cât durează o interogare pe aparat (unele aparate sunt mai lente sau sunt configurate cu un baud rate mai puțin generos și la toate astea adaugi viteza rețelei și a mediilor care rulează softul - nu va fi mult, dar nu va fi nici instant), de regulă sub două secunde. Nu o chema în buclă strânsă: casa servește un singur client odată.

• Pe hârtie: antetul firmei, „APA PLATA 0.5L 2 BUC × 3.50 = 7.00 A", numărul de articole, TOTAL 7,00, NUMERAR 7,00, defalcarea TVA.
• receipt_no este numărul bonului fiscal tipărit de casă - pune-l în evidența ta.
• Răspunsul vine după ce bonul a ieșit. O cerere care durează 2-3 secunde este normală.

• Reducerile pe articol se tipăresc sub articolul lor, care rămâne la prețul întreg. Așa se vede pe bon ce anume a fost redus, iar baza fiecărei cote de TVA scade exact acolo unde trebuie.
• Reducerea pe bon se tipărește o singură dată, ca reducere de bon, iar casa o împarte pe cotele de TVA. Noi nu o desfacem pe articole: nu știm din ce produse a compus-o programul tău, iar dacă am ghici, TVA-ul de pe hârtie ar arăta altceva decât ai vrut tu.
• Reducerea de bon se aplică pe totalul deja redus de reducerile de articol, nu pe cel brut.

Trei recomandări fiscale, pe care le urmăm și noi în programele proprii:

• Nominalizează reducerea. Când știi cărui produs îi aparține, trimite-o pe articol, nu pe bon. Diferența se vede la control: o reducere de articol spune ce s-a ieftinit, una de bon spune doar cât.
• Ai grijă ce reduci. Garanția SGR și taxele colectate pentru altcineva (ecotaxa, taxa de stațiune) nu sunt banii comerciantului: garanția se restituie integral, taxele se predau în cuantum fix. În programele Poleo le scoatem din baza reducerii. Prin API nu te oprim - trimitem ce ne dai, fiindcă răspunderea pentru conținutul bonului rămâne a programului care l-a compus - dar dacă o reducere ajunge peste ele, ajunge acolo pentru că așa ai cerut.
• Nu amesteca. Dacă ai și reduceri de articol, și una de bon, trimite-le ca atare, fiecare la locul ei. Nu le însuma într-o singură reducere de bon „ca să iasă totalul": totalul iese, dar defalcarea pe cote de pe raportul Z nu mai spune adevărul despre ce s-a vândut.

• Pe bon apar denumirea și CUI-ul cumpărătorului, în corpul fiscal al bonului, nu ca notă de subsol.
• Casele care au comanda de „date cumpărător" o folosesc pe aceea; celelalte le tipăresc ca text fiscal. Rezultatul pe hârtie este același, iar programul tău nu trebuie să știe care model face cum.
• Dacă o casă le refuză pe amândouă, bonul acela iese ANULAT - casa spune că nu poate abia după ce l-a deschis, iar noi nu emitem un bon pe firmă fără CUI pe el. Ținem minte refuzul pe casa aceea, așa că de la al doilea bon încolo primești 422 înainte de hârtie, cu același motiv. Un singur document pierdut, o singură dată.
• Plafonul de numerar se schimbă: 5.000 lei de la o persoană juridică, față de 10.000 de la o persoană fizică. Avertizarea o dăm după numărul de pe bon, nu după intenție - vezi Limite.
• Cu CUI trimis dar fără denumire, iese doar CUI-ul. Este valabil fiscal, dar dacă o ai, trimite-o: bonul se justifică singur în contabilitatea clientului.

• Rândurile ies în ordinea în care le-ai scris, după articole și înainte de total - în subsolul corpului bonului.
• Un cod de bare care nu respectă regula tipului lui este refuzat înainte de hârtie, cu 400 și cu regula scrisă în mesaj: „Codul de bare EAN13 cere exact 13 cifre; am primit «123» (3 caractere)". Trimis mai departe, ar fi însemnat bon anulat.
• Textul simplu (șir, nu obiect) merge exact ca până acum - nu trebuie să schimbi nimic la integrările existente.
• Dacă aparatul refuză un rând suplimentar, îl notăm în jurnal și bonul se termină normal. Un rând publicitar nu are voie să strice un bon fiscal.

• "kind": "X" - raport de control. Nu schimbă nimic (nu "pune casa pe 0" ca un raport Z), se poate cere oricând.
• "kind": "D" sau "DEPARTAMENTE", "G" sau "GRUPE", "OPERATORI", "PLU" - rapoartele de nomenclator: ce este programat în casă. Nu ating ziua fiscală, nu ocupă loc în memorie și nu se pot desface, fiindcă nu schimbă nimic.
• "kind": "Z" - închide ziua fiscală. Nu ai undo, consumi zile fiscale din memoria casei, vei avea niște justificări de dat în situația, dar fără a se limita la cea a unui control ANAF care va vedea diferențe de sertar vs raport X, în contabilitate vei trimite doua documente și lista poate continua așa că este necesar să faci cuvenita distincție între cele două metode. receipt_no este numărul raportului Z.
• Orice altceva la kind întoarce 400, fără să atingă casa.

• Nu se închide nicio zi și nu se șterge niciun registru. Sunt citiri tipărite, atât.
• Registrele operatorilor nu se golesc. Comanda casei permite și varianta „cu ștergere"; noi trimitem întotdeauna varianta care nu șterge. Golirea lor este o decizie fiscală, nu efectul secundar al unei citiri - se face de la casă, de cine și-o asumă.
• La fel, raportul de articole cu ștergere este refuzat: ar zeroa rulajele articolelor dintr-o simplă cerere de raport.
• Modelele care nu au raportul cerut prin protocol o spun limpede - „se poate scoate de la tastatura casei" - în loc să răspundă „ok" fără să iasă nimic pe hârtie.

• "in" = depunere, "out" = retragere. Altceva → 400.
• Suma trebuie să fie mai mare ca zero; reason este opțional, dar ajunge în evidență și te ajută peste o lună.
• Casa tipărește un document nefiscal cu operațiunea, iar soldul din sertar se schimbă.

200 și sertarul se deschide. Dacă nu este conectat niciun sertar, casa poate răspunde tot cu 200 - comanda a fost primită, doar că n-are ce deschide. Unele case nu pot gestiona sertarul constructiv, altele îl au dezactivat din soft. Deși nu oferim suport pentru setarea casei de marcat, te putem îndruma către colaboratorul nostru, QRetail având convigerea că vei găsi răspuns la orice întrebare tehnică legată -și- de aparatele fiscale.

Iese o copie a ultimului bon, marcată ca atare de casă. Nu este un bon fiscal nou și nu afectează totalurile zilei. Unele modele permit o singură copie per bon.

Anulează bonul rămas deschis pe casă - situația în care o vânzare a început și nu s-a încheiat. Iese pe hârtie un bon marcat ANULAT, care se păstrează pentru evidență. Dacă nu este niciun bon deschis, primești 422 cu explicația casei.

• Declarația se poate cere prin API: POST /declarations. Documentul iese la fel, iar gestionarul îl semnează la fel.
• Ce poți face prin API: citești registrul la GET /declarations și descarci PDF-ul fiecărei declarații. Suficient ca să ții evidența ta la zi și să atașezi documentul unde trebuie.
• Dacă greșeala se prinde înainte de închiderea bonului, nu ai nevoie de nimic din toate astea: POST /void, și vânzarea se reia curat.

• acknowledged: true este obligatoriu. Nu este o formalitate: înseamnă că un om a văzut ce se întâmplă și își asumă documentul pe care îl va semna. Fără el primești 400.
• receipt este id-ul bonului din evidență (îl ai din /receipts), nu numărul fiscal.
• reasons se ia din GET /api/v1/declaration-reasons - trimiți cheile, nu textele. Cel puțin una.
• cash_out: true înseamnă că banii se scot din sertar (retragere pe casă). Trimite-l doar dacă banii chiar se dau înapoi.
• Răspunsul conține numărul din registru și calea PDF-ului. Documentul se tipărește și se semnează; se păstrează la casierie împreună cu bonul greșit.

• acknowledged: true și reason sunt obligatorii. Un retur scoate bani din sertar fără să iasă marfă pe ușă - este cea mai la îndemână metodă de furt mărunt, deci nu se face din reflex și nu se face fără motiv scris.
• line_no este poziția liniei în bon, de la 0 - aceeași ordine din GET /receipts/{id}.
• Nu se poate returna de două ori același lucru: se ține socoteala pe bon și pe linie. Ce s-a returnat deja este scăzut, iar peste rest primești 400 cu suma rămasă.
• Numerar: se face o retragere pe casă, cu explicația legată de bonul inițial. Sertarul și evidența rămân corecte.
• Card: se încearcă virarea prin terminal. Dacă terminalul nu știe operațiunea, returul rămâne approved („de reglat") - restituirea se face pe altă cale și contabilitatea o reglează. Nu inventăm nimic.
• Află dinainte dacă terminalul poate vira înapoi: GET /terminals îți dă, pentru fiecare terminal, can: {refund, void, settlement}. Citește-l înainte de a-i spune clientului că își primește banii pe card - altfel afli abia după ce a predat marfa. Astăzi, dintre terminalele pe care le știm, niciunul nu are retur; nu este o lipsă a noastră, este ce oferă driverele și contractele.
• Dacă restituirea eșuează (casa refuză retragerea), returul rămâne failed, fără document, și primești 422. Un proces-verbal de restituire pentru bani care nu au plecat ar fi o hârtie mincinoasă.
• Documentul se semnează de gestionar și de client. Ca să iasă complet, are nevoie de datele firmei - vezi /company.
• Tot ce s-a returnat într-o zi pleacă a doua zi dimineață, într-un email către contabilitate.

• done - banii s-au dat înapoi, documentul există.
• approved - „de reglat": terminalul nu a putut vira pe card, restituirea se face pe altă cale.
• failed - nu s-a întâmplat nimic; aparatul a refuzat. Se reia.
• rejected - respins.

• Se aplică tot ce e bun și se raportează tot ce nu e - nu ne oprim la prima greșeală. Altfel, un program care trimite zece setări și greșește una nu ar mai ști care dintre celelalte nouă au intrat.
• 200 doar dacă a intrat ceva. Dacă nimic nu a trecut, primești 400 cu aceleași două liste în details - un 200 gol ar trece nevăzut prin codul tău.
• Tipurile: bifa (acceptă true/false, 1/0, "on"), numar (cu interval), lista (cu options în răspuns), text (cu lungime maximă).
• Cheile blocate răspund cu reason. Sunt doar cele patru ale serviciului API; se schimbă din fereastra aplicației, de un om.
• SFTP-ul se poate porni și configura de aici (sftp.*): e al doilea drum prin care intră bonuri în casă - fișierele coboară în folderul monitorizat și trec prin aceleași verificări ca cele locale. Parola se scrie, dar nu se citește înapoi, și se păstrează cifrată pe stație; mai bine folosește sftp.key, calea către cheia privată, și atunci nu mai stă nicio parolă acolo.
• Tipul ora vrea "HH:MM" și se normalizează („8:30" devine „08:30").
• Raportul Z automat (rap.auto_z) se poate porni de aici. Ține minte ce înseamnă: închide ziua fiscală la ora stabilită, iar o zi închisă nu se poate desface.
• Fereastra de Setări deschisă în acel moment nu se reîmprospătează singură; valoarea e deja schimbată, dar se vede la următoarea deschidere a paginii.

• GET îți dă și lista câmpurilor acceptate (fields) și pe cele care lipsesc (missing).
• Trimiți doar câmpurile pe care le schimbi; restul rămân cum erau.
• Cu case (NUI-ul casei) scrii datele doar pentru casa aceea. Același calculator poate deservi case ale unor firme diferite, iar un document ieșit cu firma greșită este o problemă reală, nu una de interfață.

• Returul scoate bani reali din contul comerciantului. Nu-l porni dintr-un automatism - pune o decizie de om în fața lui.
• Nu este totuna cu anularea. Returul merge oricând, inclusiv după închiderea borderoului; anularea merge doar cât timp plata este în borderoul curent.
• Pune-i Idempotency-Key. Un retur trimis de două ori dintr-un timeout de rețea înseamnă bani dați de două ori.
• Returul pe card nu emite niciun bon pe casă - și nici nu ai cum să ceri unul: bonul de storno (cantități negative) nu există în Poleo Fiscal, fiindcă nu există nici pe casele de marcat din România. Restituirea pe un bon deja emis se face cu /returns, care scoate banii și întocmește procesul-verbal.

• stan este numărul tranzacției din terminal, primit în răspunsul plății. Păstrează-l la fiecare încasare - fără el nu mai ai cu ce anula.
• Se cere și suma exactă. Terminalele o cer tocmai ca să nu anulezi altă tranzacție decât cea la care te gândeai.
• După închiderea de zi a terminalului, anularea nu mai este posibilă - de acolo încolo se face retur.

• Nu are nicio legătură cu raportul Z al casei de marcat. Sunt două zile diferite: una a terminalului bancar, alta a aparatului fiscal. Poți închide una fără cealaltă.
• Nu o facem noi automat. Are efect asupra decontării banilor, deci o cere omul - aceeași regulă ca la Z.
• Cheia de operațiune care conține ziua o face repetabilă în siguranță.

• 422 înseamnă „acum nu se poate" - hârtie terminată, casă ocupată, zi fiscală deschisă. Astea trec, deci merită reîncercate.
• 501 înseamnă „aparatul ăsta nu are operațiunea". Nu reîncerca niciodată. Arată omului mesajul: soluția este alt terminal, alt model, sau alt contract cu banca - nu o buclă de retry.
• details spune exact ce aparat a refuzat, ca să știi ce înlocuiești.
• Ca să nu ajungi aici prin surprindere, cere /methods la pornire și vezi ce știe stația.

• Fișierul se scrie în folderul de export al casei; message spune unde.
• Poți da out_dir ca să alegi tu folderul.
• Casa citește din memoria fiscală - pe intervale mari poate dura zeci de secunde (chiar minute întregi dacă acel punct de vânzare are multe tranzacții -chiar valori mici, dar flux ridicat-). Pune un timeout generos în clientul tău.

Bonurile vin de la cel mai nou spre cel mai vechi. status: "pending" înseamnă că bonul a fost primit, dar încă n-a ieșit - casa era ocupată sau deconectată; se tipărește singur când revine.

Pe lângă antet (număr fiscal, total, TVA, oră) primești și content - liniile exact cum au plecat spre casă. E util când vrei să lămurești, peste o săptămână, ce anume s-a trimis, nu ce credeai că se trimite.

Aici sunt rapoartele deja tipărite, cu totalurile lor. Ca să tipărești unul nou, folosești POST /reports. Filtrele sunt aceleași ca la bonuri, plus kind=X sau kind=Z. Nu uita ce am zis despre sancțiunea emiterii greșite a rapoartelor Z.

Cifrele sunt din evidența noastră, adunate din bonurile ieșite azi - bune pentru un tablou de bord. Pentru cifra oficială a zilei, raportul X al casei rămâne sursa (sau Z dacă totul este confirmat și situația permite tipărirea acestuia).

• active = ce nu s-a rezolvat încă. recent = și cele închise.
• severity: warn (in aplicație este un mesaj pe fond galben, se poate lucra) sau alert(in aplicație este un mesaj pe fond roșu, ceva a "crăpat").
• kind este stabil și se poate verifica în cod: paper_end, cover_open, fm_full, queue, op_error…

• O salvare nu este un fișier, ci o vizită la casă: aducem fișierele zilelor fiscale care lipseau din folderul casei. files spune câte a adus atunci.
• ok: false înseamnă că vizita a eșuat, iar message spune de ce (casa era ocupată, ziua nu avea niciun Z, aparatul este la alt calculator).
• Fișierele se cer separat, pe id - vezi mai jos.

• Lista este a folderului casei, nu a salvării: fișierele nu se pot împărți pe vizite, fiindcă aceeași zi fiscală poate fi adusă de mai multe salvări. Numele conține data, CUI-ul și numărul raportului Z, deci se citește ușor cu ochiul.
• Fișierele .p7b sunt semnate de casa de marcat. Noi doar le descărcăm și le păstrăm; nu le atingem, nu le semnăm și nu le putem reface dacă lipsesc.
• Dacă acea casă nu are încă folder (nicio salvare reușită), primești 404 cu not_found.

• Conținutul vine în flux, oricât ar fi de mare - nu îl ținem în memorie și nu există prag peste care să refuzăm.
• Numele fișierului vine în Content-Disposition, deci un browser sau un client HTTP îl salvează cu numele corect, fără să-l ghicești.
• Dacă programul tău preferă JSON, adaugă ?as=base64: primești { "name", "size", "encoding": "base64", "content" }. Aici există un prag - 8 MB - fiindcă base64 se construiește întreg în memorie. Peste el, cere fișierul normal.
• Numele se ia din listă, nu se compune. Orice încercare de a ieși din folderul casei (../, cale absolută) este refuzată.

• seq_no este numărul din registru - același care apare pe PDF. Numerotarea este continuă și nu se reia.
• cash_out spune dacă s-a făcut și retragerea de numerar corespunzătoare pe casă.
• PDF-ul se descarcă la /api/v1/declarations/{id}/file, la fel ca fișierele de jurnal (același Content-Disposition, același ?as=base64).

• device.vat sunt cotele programate în casă, pe grupe. Ele sunt adevărul după care tipărește ea - dacă vrei să trimiți vat_group, de aici îl iei, nu din presupuneri.
• device.payments sunt sloturile de încasare, cu numele pe care li l-a dat tehnicianul la fiscalizare. De aici afli pe ce index stă cardul la aparatul ăsta.
• pay_dialect spune cum se citesc numerele pe care le trimiți tu în index: casa = chiar sloturile de mai sus; standard = convenția clasică a integratorilor.
• Citirea interoghează aparatul, deci durează cât o comandă pe casă și o ține ocupată. Nu o chema într-o buclă de tablou de bord - cere-o o dată, la pornirea integrării, și ține minte răspunsul.
• Dacă aparatul nu răspunde, primești tot 200, cu device.read_ok: false și motivul în device.message - restul configurării, cea de la noi, este oricum acolo.

• Licența se dă pe NUI, nu pe calculator: o stație cu două case are două licențe, care pot expira în zile diferite.
• status: trial, active, expired, blocked sau error. Pe ok: false casa nu mai tipărește - este singura stare care oprește vânzarea.
• În probă, bons_left spune câte bonuri mai are. Nu întrebăm serverul la fiecare bon: numărătoarea este locală, iar verificarea online se face rar.
• offline_days_left = de câte zile mai poate lucra fără internet. Dacă este null, nu este o licență cu termen offline.
• Bun de pus într-un tablou de bord: cine ține 30 de magazine află de aici că unul expiră săptămâna viitoare, în loc să afle din telefonul casierului în dimineața în care casa nu mai tipărește.

• routing spune ce se întâmplă dacă nu alegi terminalul: dupa_casa = cel de lângă casa care tipărește, fix = mereu același, ales de comerciant, intreb = îl alege operatorul pe ecran.
• enabled: false înseamnă că plata cu cardul nu este activată în aplicație - orice cerere la /pos va fi refuzată până se bifează în Setări.
• can spune ce operațiuni are terminalul: refund (retur), void (anularea din borderoul curent), settlement (închiderea de zi). Citește-l înainte de a promite ceva clientului. Nu costă nimic - se citește din driver, nu de pe fir - și te scutește de situația în care afli că nu se poate abia după ce clientul a predat marfa.
• Ce nu apare aici nu se reîncearcă: dacă refund: false, operațiunea va răspunde 501 cu error: "unsupported" oricând ai încerca. Soluția este alt terminal sau alt contract cu banca, nu o reîncercare.

• Întâi banii, apoi bonul. Ceri plata, și doar dacă banca aprobă tipărești bonul cu "method": "card". Invers, ai un bon fiscal emis pentru o plată refuzată - și el nu se mai retrage.
• Fără terminal, plata merge unde spune routing. Cu el, merge exact acolo - util când vrei încasarea pe banca cu comisionul mai mic, sau pe terminalul casieriei de la care s-a făcut vânzarea.
• Păstrează auth și rrn: cu ele reconciliezi cu extrasul băncii și cu ele se lămurește o dispută.
• Plata incertă este cazul care contează: terminalul a primit comanda, dar răspunsul nu a ajuns înapoi. Cardul poate să fi fost debitat. Nu relua plata automat - se verifică pe terminal întâi. Aplicația ține evidența acestor plăți și le semnalează separat.

• Amprenta nu are legătură cu licența și nu se schimbă singură - nici la actualizare, nici dacă se schimbă portul, IP-ul sau casa. O înregistrezi o dată.
• Se poate roti, dar numai dacă omul din magazin o cere din Setări → API. Atunci legăturile trebuie aprobate din nou - este parolă de aplicație, nu identitate.
• location este numele din Setări → „Denumirea locului de muncă". După el rutezi comenzile: casele se schimbă, locul rămâne.

Aceeași listă o vede și omul în aplicație, în Setări → API - amândouă vin din același loc din program, deci nu se pot despărți una de alta.

• Iese pe hârtie raportul pe intervalul cerut, citit din memoria fiscală a casei.
• detailed: false cere varianta sumară, unde modelul o are.
• Pe intervale mari poate dura zeci de secunde: casa citește înregistrare cu înregistrare. Pune un timeout generos.
• Nu schimbă nimic și nu închide ziua - este o citire, nu un Z.