API local

Programul tău vorbește cu casa de marcat, prin aplicația FiscalLink.

Aplicația FiscalLink servește un API REST pe calculatorul sau telefonul de lângă casă. Trimiți JSON, aplicația comandă casa și îți întoarce rezultatul. Aceleași rute pentru Datecs, Tremol și Daisy; diferențele dintre mărci le tratează aplicația.

Adresa API-ului

Aplicația ascultă pe două porturi fixe. Toate rutele încep cu /api/v2.

Mod	Adresă	Note
Securizat (HTTPS)	`https://localhost.fiscallink.ro:65401/api/v2`	Adresa recomandată. Numele se rezolvă la `127.0.0.1`, adică același calculator.
Local (HTTP)	`http://{ip-local}:65400/api/v2`	În rețeaua locală, fără TLS.

Porturile nu se configurează. Ca să afli adresa exactă când rulezi, întreabă aplicația: cele două rute de mai jos merg mereu, chiar și fără licență.

Acces și securitate

Fără cheie, fără token. Nu trimiți nicio credențială pe cerere. O cerere e refuzată doar dacă:
- casa conectată nu are licență: 401 (rutele Shopify cer licența Commerce: 403);
- nu e nicio casă conectată sau casa nu răspunde: 424.
Licența. Orice licență (Essential sau Commerce) deschide API-ul local. Fără internet, aplicația folosește licența salvată pe dispozitiv cât timp e valabilă; fără ea, casa e tratată ca nelicențiată.
CORS. Doar serverul HTTPS trimite antete CORS și permite orice origine (*). Serverul HTTP nu trimite niciunul, deci o pagină web din browser poate apela doar adresa HTTPS. Niciunul nu verifică antetele Origin sau Host.
O comandă pe rând. O casă execută o singură comandă odată, indiferent dacă vine din API-ul local, din Cloud sau din Shopify POS. Trimite apelurile unui bon în ordine și așteaptă fiecare răspuns.
Tot ce tipărești se vede în Cloud. Bonurile, rapoartele X și Z, citirile de cote TVA și lucrul cu articole făcute prin API-ul local sunt raportate organizației FiscalLink Cloud a casei, cât timp casa e asociată.

Formatul răspunsului

Toate rutele, în afară de /api/Receipt, răspund în același plic. La succes primești statusCode și data. La eroare primești statusCode și message, niciodată o pagină HTML. Unde un singur cod de stare acoperă două refuzuri, corpul are și un câmp code, un identificator stabil. Textul din message e în limba aplicației: ramifică după cod, nu după text.

data e textul de răspuns al casei la majoritatea rutelor; la rapoarte, cote TVA și articole e un obiect.

json

{
  "statusCode": 200,
  "data": "Receipt printed successfully."
}

json

{
  "statusCode": 424,
  "message": "Serial communication service not started. Please connect to a device."
}

Fluxul recomandat

Afli adresa: GET /get-secure-api-address.
Trimiți bonul întreg dintr-un singur apel: POST /print-fiscal-receipt.
Citești răspunsul. 200: bonul e tipărit. 400: cererea sau casa a refuzat bonul și niciun bon nu a rămas deschis. 424 sau 500: citește „Înainte să retrimiți” din „Erori și coduri” înainte să trimiți din nou.
La sfârșitul zilei: POST /report-z.

Aplicația verifică bonul înainte să-l deschidă pe casă. Dacă ceva eșuează după deschidere, aplicația anulează bonul, iar mesajul se termină cu | Receipt cancelled successfully.

Diferențe între mărci

Comportament	Datecs	Daisy	Tremol
Vânzare liberă (`freeSale`)	Da	Doar cu „Vânzare liberă pe Daisy”, ca articol programat	Da; nume de cel mult 138 de caractere, 30 pe linia de vânzare
Grupe TVA pe vânzare (`taxCode`)	1–7	Grupa alege departamentul	1–6
Operator la bonul fiscal	Obligatoriu dacă trimiți antetul	Obligatoriu dacă trimiți antetul	Opțional; lipsă, e citit de pe casă
Parola operatorului	—	—	Exact 4 caractere
Factură (`invoice`)	Bon „CIF Client”	Ignorat	Ignorat
Formatarea textului	Da	Doar textul	Doar textul, maximum 33 de caractere
Plăți	—	—	Se pot face mai multe plăți; bonul se închide când ultima plată acoperă suma de plată
Subtotal fără tipărire, cu reducere	Da	Da	Doar fără reducere sau majorare
Afișaj client	—	—	Exact 20 de caractere pe linie
Conexiune în rețea	Da	Nu	Da

Coduri de plată (`paymentMode`)

Cod	Tremol	Datecs	Daisy
0	Numerar	Numerar	refuzat
1	Card	Card	Card
2	refuzat (eroarea 4)	Tichete de masă	nu există
3	Tichete	Tichete valorice	Numerar
4	Bonuri	Voucher	Tichete masă
5	Voucher	Credit	Bonuri / tichete valorice
6	Credit	Metode moderne	Voucher
7	Moderne	Avans în numerar	Credit
8	Alte	Alte metode	Metode moderne
9	EUR, refuzat (eroarea casei 2)	Alte monede	Alte metode

Sunt denumirile implicite ale fiecărei mărci și se pot reprograma. Pe un Tremol S25, codurile 2 (eroarea 4) și 9 (eroarea casei 2) sunt refuzate ca plată simplă. Pe Daisy, codul 0 e refuzat, codul 2 nu există, iar codurile sunt valorile implicite ale unui singur aparat.

paymentMode de pe bon e codul casei; plățile dintr-un raport sunt pe poziții. Pe fiecare marcă, poziția e codul + 1: method1 … method10. Numerarul pe Tremol și Datecs, codul 0, e poziția 1; cardul, codul 1, e poziția 2; valuta pe Datecs, codul 9, e poziția 10. Excepția Daisy: numerarul are codul 3, dar apare în poziția 1, din câmpul lui propriu, iar poziția 4 arată mereu 0.00 și nu poartă nicio cifră, ca numerarul să nu fie numărat de două ori; celelalte coduri Daisy urmează regula. Poziția 10 pe Datecs e în valută, nu în lei. Pozițiile Daisy nu sunt încă dovedite pe o casă reală.

Rutele Shopify

GET /get-shopify-order/{orderId} și POST /print-shopify-order/{orderId} aparțin integrării FiscalLink pentru Shopify POS. Cer licența Commerce și tokenul de sesiune Shopify în Authorization: Bearer. Integrarea Shopify POS e descrisă în documentația ei (/shopify-pos/docs).

În referință

Rutele, cu parametrii și exemplele lor, și obiectele sunt în referință: