Cum vrei să scrii bonul?

Fisco JSON RECOMANDAT

Doar pentru Fisco JSON

Descrii bonul ca obiect, fără să cunoști formatul de linie al casei. Toate valorile sunt numere întregi: sumele în bani, cantitățile în miimi, procentele în sutimi. Numerele întregi evită erorile de reprezentare a zecimalelor. O valoare cu zecimale (9.5) e respinsă, dar un preț întreg scris în lei (10 în loc de 1000) e acceptat ca 0,10 lei: verifică unitatea în program.

Bonul (receipt)

Articol (items[])

Plată (payments[])

amount e în bani și e obligatoriu la fiecare plată.

• Plățile trebuie să facă exact totalul bonului; altfel bonul e respins.
• Restul se dă doar când bonul e plătit numai în numerar. La un total de 1900: cash 5000 → rest 31,00 lei; cash 1950 → rest 0,50 lei. Dacă pe bon e și altă plată (card, tichete…), nu se dă rest: numerarul trebuie să fie exact diferența (card 900 + cash 1000), iar card 900 + cash 2000 e respins.
• Diferențe mici. Dacă plățile diferă de total cu mai puțin de 1 leu, Fisco corectează plata (de preferat pe numerar), ca bonul să se tipărească; o diferență mai mare respinge bonul. Corecția se face doar dacă e bifată „Corectează automat totaluri incorecte cu diferență mai mică de 1 leu” în setările driverului. Din experiență, diferențele vin din reduceri și din prețuri ținute în program fără TVA: casa tipărește prețul cu TVA rotunjit la ban, pe când programul de vânzare îl poate calcula cu trei sau mai multe zecimale.

Cum calculează casa: fiecare articol e price × quantity / 1000, rotunjit la ban, minus reducerea (tot rotunjită). Calculează totalul la fel în program și nu vei avea diferențe de un ban.

Retur

Un articol cu quantity negativă e un retur. Returul nu poate depăși vânzările de pe aceeași cotă de pe bon: nu poți storna 100 de lei pe cota A fără cel puțin 100 de lei vânduți pe A. Un retur pus înaintea vânzării de care are nevoie e mutat automat după ea, iar un bon cu totalul zero e permis (schimbul unui produs). Daisy nu suportă storno: acolo returul se tipărește ca reducere valorică pe articolele de pe aceeași cotă.

Bon nefiscal

{ "syntax": "fisco", "nonfiscal": { "texts": ["Comanda 154", "Masa 20", "2 x Cafea"] } }

Sintaxa simplificată

Doar pentru sintaxa simplificată

O comandă pe linie, câmpurile separate cu ^ (care nu poate apărea în texte). Sumele în bani, cantitățile în miimi, procentele în sutimi, la fel ca în JSON.

Linia de vânzare, retururile și reducerile, pe larg: Vânzări, retururi, reduceri și plăți.

Sintaxa FPrint

Doar pentru sintaxa FPrint

Formatul clasic, păstrat pentru programele care îl generează deja. Fiecare linie începe cu un cod și antetul fix ,1,______,_,__, apoi câmpurile separate cu ;. Sumele și cantitățile se scriu cu punct zecimal: 3.50, 1.000.

Limite

Vânzări, retururi, reduceri și plăți

Pentru sintaxa simplificată și FPrint

Linia de vânzare

Fiecare articol e o linie. Valoarea lui este prețul unitar înmulțit cu cantitatea (3,50 lei × 2 buc = 7,00 lei), rotunjită la ban.

S^Ceai cu miere^350^2000^buc^1^1
S^Branza^4000^350^kg^1^2

S,1,______,_,__;Ceai cu miere;3.50;2.000;1;1;1;0;0;buc
S,1,______,_,__;Branza;40.00;0.350;2;1;1;0;0;kg

Retur (storno)

Un retur e o linie de vânzare cu cantitatea negativă; prețul rămâne pozitiv. Returul scade din bon valoarea lui, pe cota lui.

• Returul nu poate depăși vânzările de pe aceeași cotă de deasupra lui (după reducerile lor), nici totalul bonului. Egal e permis. Nu poți storna 100 de lei pe cota A dacă pe bon nu sunt vânzări de cel puțin 100 de lei pe cota A, chiar dacă bonul are vânzări pe alte cote.
• Un retur trimis înaintea vânzării de care are nevoie e mutat automat după ea.
• Un bon cu totalul zero e permis (ex. schimbul unui produs: returul egal cu vânzarea).
• O reducere pusă după un retur nu are efect.

S^Televizor^15000^1000^buc^1^1
S^Retur cablu^10000^-1000^buc^1^1
P^1^5000

S,1,______,_,__;Televizor;150.00;1.000;1;1;1;0;0;buc
S,1,______,_,__;Retur cablu;100.00;-1.000;1;1;1;0;0;buc
T,1,______,_,__;0;50.00;;;;

S^Televizor^15000^1000^buc^1^1
S^Retur carte^10000^-1000^buc^2^1
P^1^5000

S,1,______,_,__;Televizor;150.00;1.000;1;1;1;0;0;buc
S,1,______,_,__;Retur carte;100.00;-1.000;1;1;2;0;0;buc
T,1,______,_,__;0;50.00;;;;

Merge și comanda VS^denumire^preț^cant^UM^TVA^dep, cu aceleași câmpuri ca S^ și cantitatea pozitivă: e același retur.

Reduceri și majorări

O reducere sau o majorare se aplică liniei de deasupra ei: unui articol, dacă vine imediat după linia lui, sau întregului bon de până atunci, dacă vine după un subtotal.

Pe articol

• Linia de reducere vine imediat după articol. Procentul se calculează din valoarea articolului și se rotunjește la ban.
• Pune cel mult o reducere sau majorare pe articol: la a doua, rezultatul diferă de la o casă la alta.
• Reducerea nu poate depăși valoarea articolului: Discountul (6.00) este mai mare decât valoarea produsului (5.00).
• Reducerea pusă înaintea primului articol, după un retur sau după plată nu are efect. Bonul se tipărește fără ea, iar dacă ai calculat plata cu reducerea, plata nu mai e egală cu totalul și bonul e respins.

Pe subtotal

• Se aplică pe tot ce e deasupra subtotalului: articole, reducerile lor, retururi.
• Procentul se calculează și se rotunjește pe fiecare cotă TVA, ca la casă. Suma poate diferi cu un ban de procentul din total: 10% din A 1,15 + B 1,15 = 0,12 + 0,12 = 0,24, deci totalul e 2,06, nu 2,07.
• O reducere valorică se împarte pe cote proporțional cu vânzările lor.
• Poți pune mai multe subtotaluri cu reduceri: fiecare se aplică pe totalul de până la el. A 10 + B 10, −10% → 18,00, apoi −2,00 lei → 16,00.
• Reducerea nu poate depăși totalul, iar pe un subtotal zero nu se poate aplica nimic.

S^Ceai^1000^1000^buc^1^1
DP^1000
S^Cafea^2000^1000^buc^1^1
P^1^2900

S,1,______,_,__;Ceai;10.00;1.000;1;1;1;0;0;buc
C,1,______,_,__;1;10.00;;;;
S,1,______,_,__;Cafea;20.00;1.000;1;1;1;0;0;buc
T,1,______,_,__;0;29.00;;;;

S^Ceai^1000^1000^buc^1^1
S^Cafea^2000^1000^buc^1^1
ST^
DP^1000
P^1^2700

S,1,______,_,__;Ceai;10.00;1.000;1;1;1;0;0;buc
S,1,______,_,__;Cafea;20.00;1.000;1;1;1;0;0;buc
T,1,______,_,__;4;;;;;
C,1,______,_,__;1;10.00;;;;
T,1,______,_,__;0;27.00;;;;

S^Articol A^1000^1000^buc^1^1
DP^1000
S^Articol B^500^1000^buc^2^1
DV^100
ST^
DP^500
P^1^1235

S,1,______,_,__;Articol A;10.00;1.000;1;1;1;0;0;buc
C,1,______,_,__;1;10.00;;;;
S,1,______,_,__;Articol B;5.00;1.000;1;1;2;0;0;buc
C,1,______,_,__;3;1.00;;;;
T,1,______,_,__;4;;;;;
C,1,______,_,__;1;5.00;;;;
T,1,______,_,__;0;12.35;;;;

Plata

Plățile vin după articole, la sfârșitul bonului. Poți pune mai multe, de tipuri diferite.

P^2^900
P^1^0

T,1,______,_,__;1;9.00;;;;
T,1,______,_,__;0;;;;;

• Plățile trebuie să facă exact totalul bonului; altfel bonul e respins: Suma produselor este 19.00 dar suma de plată este 10.00.
• Diferențe mici. Dacă plățile diferă de total cu mai puțin de 1 leu, Fisco corectează plata (de preferat pe numerar), ca bonul să se tipărească; o diferență mai mare respinge bonul. Corecția se face doar dacă e bifată „Corectează automat totaluri incorecte cu diferență mai mică de 1 leu” în setările driverului. Din experiență, diferențele vin din reduceri și din prețuri ținute în program fără TVA: casa tipărește prețul cu TVA rotunjit la ban, pe când programul de vânzare îl poate calcula cu trei sau mai multe zecimale.
• Restul se dă doar când bonul e plătit numai în numerar. La un total de 19,00: numerar 50,00 → rest 31,00; numerar 19,50 → rest 0,50. Dacă pe bon e și altă plată (card, tichete…), nu se dă rest: numerarul trebuie să fie exact diferența (card 9,00 + numerar 10,00), iar card 9,00 + numerar 20,00 e respins.
• Cel mult o plată poate fi cu suma 0fără sumă: ea primește suma rămasă de plată. Două astfel de plăți resping bonul.
• Fără nicio plată, tot totalul se încasează în numerar.
• După plată nu mai poți adăuga articole; o reducere pusă după plată nu are efect.

S^Cafea^950^2000^buc^1^1
P^2^1900

S,1,______,_,__;Cafea;9.50;2.000;1;1;1;0;0;buc
T,1,______,_,__;1;19.00;;;;

S^Cafea^950^2000^buc^1^1
P^2^900
P^1^0

S,1,______,_,__;Cafea;9.50;2.000;1;1;1;0;0;buc
T,1,______,_,__;1;9.00;;;;
T,1,______,_,__;0;;;;;

S^Cafea^950^2000^buc^1^1
P^1^5000

S,1,______,_,__;Cafea;9.50;2.000;1;1;1;0;0;buc
T,1,______,_,__;0;50.00;;;;

Text formatat și coduri de bare

Pentru sintaxa simplificată și FPrint (nu pentru Fisco JSON)

Se pot pune în bonuri scrise cu sintaxa simplificată sau FPrint. Nu modifică totalul.

La text, câmpurile de format sunt 1 (da) sau gol (nu), iar alinierea e 0 stânga, 1 centru, 2 dreapta. Formatarea textului se aplică doar pe Datecs. Pe Daisy și Tremol se tipărește textul, fără formatare. Fisco alege singur bonul: un fișier care are doar linii de text (54,, 42,) devine bon nefiscal, iar împreună cu articole ambele se tipăresc pe bonul fiscal.

Tipuri: 1 EAN8 (8 cifre), 2 EAN13 (13 cifre), 3 Code128 (3–31 caractere), 4 QR (3–279 caractere, mărime 3–10, implicit 5), 5 Interleaved 2 of 5 (3–22 cifre).

Ambele forme (84, și CB^) merg în ambele sintaxe, pe bon fiscal sau nefiscal. Un cod greșit (tip necunoscut, lungime sau caractere greșite) e respins pe orice casă, înainte de tipărire. Un cod corect pe care casa nu îl poate tipări nu blochează bonul: în locul lui se tipăresc datele, ca text.

Prin fișiere

Pentru sintaxa simplificată și FPrint (nu pentru Fisco JSON)

Programul scrie un fișier text în folderul scanat, iar Fisco îl preia, îl tipărește și mută rezultatul în subfoldere.

Folderul scanat implicit este <director instalare>\Bonuri, de exemplu C:\Fisco\Bonuri. Se schimbă din Setări driver, unde se aleg și extensiile acceptate (implicit *.bon, *.inp, *.txt).

S^Cafea^950^2000^buc^1^1
S^Apa plata^500^1000^buc^2^1
P^2^2400

S,1,______,_,__;Cafea;9.50;2.000;1;1;1;0;0;buc
S,1,______,_,__;Apa plata;5.00;1.000;1;1;2;0;0;buc
T,1,______,_,__;1;24.00;;;;

Fișierul poate fi UTF-8 (cu sau fără BOM) sau ANSI (Windows-1250).

Înainte de fiecare fișier, Fisco verifică starea casei: conexiunea, hârtia, memoria, raportul Z din ultimele 24 de ore. Dacă ceva nu e în regulă, fișierul rămâne în folder, driverul afișează problema și reia tipărirea după ce problema e rezolvată.

Rezultatul procesării

Faptul că fișierul a dispărut din folder nu înseamnă că s-a tipărit. Caută fișierul cu același nume în BonANSWER (reușit; la un bon, tipărit) sau în BonERR (eroare).

[Answer]
SlipNumber=1959
nZrep=42
nFNum=200
DeviceSerial=DB4100000055

[Answer]
SlipNumber=2826
nZrep=221
nRep=0221
TotEXEPTAT=000000000000
TaxA=000000006050
TaxB=000000000000
TaxC=000000000000
TaxD=000000000000
PayCash=47.00
PayCard=13.50
PayCredit=0.00
PayMealTicket=0.00
PayGiftTicket=0.00
PayVoucher=0.00
PayModern=0.00
PayOther=0.00
TotalSales=60.50
DeviceSerial=1234567890

S,1,______,_,__;;10;1;1;1;1;0;0;Buc
#Linia 1 | S,1,______,_,__;;10;1;1;1;1;0;0;Buc
#Denumirea produsului lipseste.

Totalurile zilei, fără raport X 1.4

Un fișier cu o singură linie, TOTALURI^, cere totalurile zilei curente (de la ultimul Z) pe tipuri de plată. Linia e aceeași în sintaxa simplificată și în FPrint. Fisco doar citește totalurile din casă: nu se tipărește nimic și nu se modifică nimic. Dacă linia e împreună cu alte comenzi sau are ceva după ^, fișierul ajunge în BonERR.

TOTALURI^

[Answer]
CommandName=daily_totals
nZrep=146
Cash=1350.00
PayCash=1200.00
PayCard=1150.50
PayCredit=0.00
PayMealTicket=0.00
PayGiftTicket=0.00
PayVoucher=100.00
PayModern=0.00
PayOther=0.00
TotalSales=2450.50
DeviceSerial=DB4100000055

BONOK=1
NRZ=146
NUMERAR=1200.00
CARD=1150.50
CREDIT=0.00
TICHETE_MASA=0.00
TICHETE_VALORICE=0.00
VOUCHER=100.00
PLATA_MODERNA=0.00
ALTE_METODE=0.00
TOTAL_VANZARI=2450.50
SOLD_NUMERAR=1350.00

Denumirile totalurilor în fiecare format:

În fișiere sumele sunt în lei, cu două zecimale; în API, în bani. După un raport Z, toate totalurile, inclusiv numerarul din casă, pornesc de la zero. Pentru totalurile unui Z, citește răspunsul la raportul Z: are aceleași câmpuri.

Sertarul de bani 1.4

Linia DS^ deschide sertarul de bani, în ambele sintaxe.

• Singură în fișier: deschide sertarul, fără să tipărească nimic.
• Împreună cu un bon: poate fi oriunde în fișier.
• Dacă sertarul nu se deschide, bonul e tipărit oricum și apare în BonANSWER: nu îl retrimite.

S^Ceai cu miere^350^1000^buc^1^1
P^1^500
DS^

S,1,______,_,__;Ceai cu miere;3.50;1.000;1;1;1;0;0;buc
T,1,______,_,__;0;5.00;;;;
DS^

Recomandări

Prin API HTTP

Comun pentru toate sintaxele

Fisco pornește un server HTTP local. Trimiți bonul cu POST; cu ?wait= primești rezultatul tipăririi în același răspuns.

http://127.0.0.1:4040/api/v1

Din browser: răspunsurile au Access-Control-Allow-Origin: * și Access-Control-Allow-Private-Network: true, deci o pagină web poate apela API-ul direct din JavaScript.

Specificația OpenAPI 3 e la GET /api/v1/openapi.json. O poți importa în Postman, Insomnia sau într-un generator de clienți.

Flux recomandat

r = POST /api/v1/print?wait=30   { bonul }

if !r.ok                          → respins, nu a intrat în coadă: arată r.error.message
else if r.status == "printed"     → salvează r.result.SlipNumber
else if r.status == "failed"      → arată r.error.message; bonul NU e tipărit
else                              → "queued" / "processing": nu s-a terminat în 30 s;
                                    păstrează r.job_id și întreabă /status?job_id=…

job = POST /api/v1/print   { bonul }
repeat
    s = GET /api/v1/status?job_id={job.job_id}
until s.status in ("printed", "failed") or timeout

Răspuns pierdut

Dacă răspunsul HTTP se pierde (rețea, timeout), nu știi dacă bonul a intrat în coadă, iar o cerere retrimisă ar putea tipări bonul de două ori. Pune în corp un idempotency_key unic pentru fiecare bon (un UUID sau numărul comenzii cu data, max. 128 de caractere) și retrimite cererea cu aceeași cheie: în 24 de ore, aceeași cheie nu mai tipărește, ci întoarce jobul existent, cu starea lui ("duplicate": true). Aceeași cheie cu alt bon primește 409 IDEMPOTENCY_KEY_REUSED.

{ "syntax": "fisco", "idempotency_key": "comanda-2026-10-24-0042",
  "receipt": { "items": [{ "name": "Paine", "price": 250, "vat": "A" }] } }

Joburile se pot întreba cu /status?job_id=… cât timp fișierele lor sunt în BonOK / BonERR; fără job_id, /status?limit=10 dă ultimele joburi.

Exemple de cod

Doar pentru Fisco JSON

Un bon cu 2 cafele, plătit cu cardul, trimis prin API cu așteptarea rezultatului.

curl -X POST "http://127.0.0.1:4040/api/v1/print?wait=30" \
  -H "Content-Type: application/json" \
  -d '{"syntax":"fisco","receipt":{"items":[{"name":"Cafea","price":950,"quantity":2000,"vat":"A"}],"payments":[{"type":"card","amount":1900}]}}'

const API = 'http://127.0.0.1:4040/api/v1';
const bani  = lei => Math.round(lei * 100);   // 9.5 -> 950
const miimi = q   => Math.round(q * 1000);    // 0.35 -> 350

async function printReceipt(receipt) {
  const r = await fetch(`${API}/print?wait=30`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ syntax: 'fisco', receipt })
  });
  const job = await r.json();
  if (!job.ok || job.status === 'failed') throw new Error(job.error.message);
  if (job.status !== 'printed') throw new Error('Inca se tipareste, verifica /status?job_id=' + job.job_id);
  return job.result.SlipNumber;
}

printReceipt({
  items: [{ name: 'Cafea', price: bani(9.5), quantity: miimi(2), vat: 'A' }],
  payments: [{ type: 'card', amount: bani(19) }]
}).then(n => console.log('Bon', n), e => console.error(e.message));

using var http = new HttpClient { BaseAddress = new Uri("http://127.0.0.1:4040/api/v1/") };
var body = new {
    syntax = "fisco",
    receipt = new {
        items = new[] { new { name = "Cafea", price = 950, quantity = 2000, vat = "A" } },
        payments = new[] { new { type = "card", amount = 1900 } }
    }
};
var resp = await http.PostAsJsonAsync("print?wait=30", body);
var json = await resp.Content.ReadFromJsonAsync<JsonElement>();
if (!json.GetProperty("ok").GetBoolean() || json.GetProperty("status").GetString() == "failed")
    Console.WriteLine(json.GetProperty("error").GetProperty("message").GetString());
else if (json.GetProperty("status").GetString() == "printed")
    Console.WriteLine(json.GetProperty("result").GetProperty("SlipNumber").GetString());
else
    Console.WriteLine("Inca se tipareste: " + json.GetProperty("job_id").GetString());

$bon = [
  'syntax'  => 'fisco',
  'receipt' => [
    'items'    => [['name' => 'Cafea', 'price' => 950, 'quantity' => 2000, 'vat' => 'A']],
    'payments' => [['type' => 'card', 'amount' => 1900]],
  ],
];
$ch = curl_init('http://127.0.0.1:4040/api/v1/print?wait=30');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode($bon),
  CURLOPT_RETURNTRANSFER => true,
]);
$job = json_decode(curl_exec($ch), true);
if (!$job['ok'] || $job['status'] === 'failed') echo $job['error']['message'];
elseif ($job['status'] === 'printed') echo $job['result']['SlipNumber'];
else echo 'Inca se tipareste: ' . $job['job_id'];

import requests

bon = {
    "syntax": "fisco",
    "receipt": {
        "items": [{"name": "Cafea", "price": 950, "quantity": 2000, "vat": "A"}],
        "payments": [{"type": "card", "amount": 1900}],
    },
}
job = requests.post("http://127.0.0.1:4040/api/v1/print", params={"wait": 30}, json=bon, timeout=40).json()
if not job["ok"] or job["status"] == "failed":
    print(job["error"]["message"])
elif job["status"] == "printed":
    print(job["result"]["SlipNumber"])
else:
    print("Inca se tipareste:", job["job_id"])

uses System.Net.HttpClient, System.Classes, System.SysUtils;

var
  Http: THTTPClient;
  Body: TStringStream;
begin
  Http := THTTPClient.Create;
  Body := TStringStream.Create(
    '{"syntax":"fisco","receipt":{"items":[{"name":"Cafea","price":950,"vat":"A"}]}}', TEncoding.UTF8);
  try
    Http.ContentType := 'application/json';
    Writeln(Http.Post('http://127.0.0.1:4040/api/v1/print?wait=30', Body).ContentAsString(TEncoding.UTF8));
  finally
    Body.Free;
    Http.Free;
  end;
end.

Endpoint-uri API

Comun pentru toate sintaxele

Toate căile pornesc de la http://127.0.0.1:4040. Fiecare răspuns are ok.

{ "syntax": "simplu", "commands": ["S^Paine^250^1000^buc^1^1", "P^1^250"] }

{ "ok": true, "server": "running", "printer": { "ready": false, "status": "not_ready", "error": "Lipsa hartie" } }

{ "pulse_duration_ms": 200 }

{ "ok": true, "z_number": 146, "total_sales": 245050,
  "payments": { "cash": 120000, "card": 115050, "credit": 0, "meal_ticket": 0,
                "gift_ticket": 0, "voucher": 10000, "modern": 0, "other": 0 },
  "cash_drawer": 135000 }

Erori

Comun pentru toate sintaxele

{ "ok": false, "error": { "code": "CONVERSION_ERROR", "message": "items[0]: price must be an integer >= 0, in bani (250 = 2.50 lei)" } }

Un bon refuzat la tipărire nu e o cerere respinsă: răspunsul are ok: true, status: "failed" și error.code = PRINT_FAILED, cu mesajul casei.

POS bancar 1.2

Comun pentru toate sintaxele

Încasezi cu cardul pe terminalul bancar legat de calculator, apoi trimiți bonul cu plata card. Necesită licența Fisco POSBancar (14 zile de probă).

{ "terminal": 1, "amount": 2400 }

{ "ok": true, "approved": true, "amount": 2400, "auth_code": "C1HH0Z",
  "rrn": "412138851873", "card_number": "454793XXXXXX0683", "text": "…" }

GET /api/v1/card/terminals listează terminalele configurate. Programele care apelau FiscoCard pe portul 40123 (?operation=sale&value=1050) merg fără schimbări.

Istoric versiuni

Comun pentru toate sintaxele