Toate casele clienților tăi, de la distanță.

Organizația de integrator

• O creezi în FiscalLink Cloud, ca organizație de integrator; în dashboard tipul ei se numește „Integrare”. Taxa e 100 lei pe an +TVA, doar anual, plătită prin Stripe. Organizația apare abia după plată; dacă abandonezi plata, nu rămâne nimic în urmă.
• E un produs separat de organizațiile obișnuite: are clienți și case, fără locații, fără date fiscale și fără licențe proprii.
• În dashboard ai: panoul principal, clienți, coduri de activare, case, comenzi, sandbox și setări.
• Drepturile echipei sunt separate pe acțiuni: vizualizare; clienți (adăugare, modificare, ștergere); case (adăugare, conectare, ștergere, comenzi); documentație; sandbox. Dreptul de a administra casele nu include dreptul de a le trimite comenzi.

Clienți și coduri de activare

• Clientul e magazinul pe care îl deservești. Trebuie să existe înainte să activezi o casă pentru el. Numele e unic în organizația ta. Un client care mai are case nefinalizate (care nu sunt Removed) nu poate fi șters.
• Codul de activare se creează odată cu clientul: un singur cod pentru toate casele clientului, refolosibil. E un GUID cu majuscule, în 8 grupe de câte 4 caractere; liniuțele, spațiile și literele mici nu contează când îl introduce clientul.
• Linkul de activare poartă codul după #code=, în fragmentul adresei, deci codul nu ajunge la niciun server. Linkul deschide aplicația FiscalLink.
• Cod nou. Poți genera oricând un cod nou: cel vechi nu mai merge imediat, iar casele deja activate rămân conectate.
• Cum apar casele. De obicei, singure: clientul folosește codul în aplicația FiscalLink pe fiecare casă, aplicația îi arată numele tău și al clientului și îl întreabă dacă acceptă. Pașii clientului sunt în documentația aplicației (/app/docs).
• Ce nu poate face un cod. Codul unui client nu poate lua casa altui client de-al tău. O casă deja asociată cu o organizație FiscalLink Cloud nu își pierde legătura din cauza codului tău.

Acordul casei

• Când clientul folosește codul tău, acordul e dat: casa începe să primească comenzi.
• Când activezi tu o casă după serie, prin API-ul de administrare, înregistrarea e Active, dar cu awaitingClientConsent true: casa nu primește comenzi până nu acceptă în aplicația FiscalLink. Interoghează „Citește o casă” până când awaitingClientConsent e false.
• Aplicația întreabă casa: Conectează sau Refuză. Închiderea dialogului nu e un refuz; întrebarea revine după o pauză.
• Dacă acel client refuză, seria se șterge din înregistrare, care trece în AwaitingSerial. Poți lega altă serie cu „Leagă o serie”.

Stările unei case

Chei API

• Cheile de comenzi și cele de administrare încep amândouă cu fsk_: prefixul singur nu le deosebește. O cheie de administrare nu e niciodată cheie de sandbox.
• O cheie de administrare cere un drept separat, pentru că ce creează poate șterge un client sau poate costa bani.
• Cheia completă apare o singură dată, la creare. Salveaz-o atunci; după aceea se vede doar prefixul.
• Expirare: niciodată, 30 de zile, 90 de zile, un an sau o dată aleasă (cel puțin de mâine). Primești un avertisment cu 14 zile înainte. O cheie revocată rămâne revocată; o cheie rotită își păstrează data de expirare.

Adresă și autentificare

• Adresa API-ului: https://cloud-api.fiscallink.ro.
• tenantId din rute e id-ul organizației tale; îl vezi în adresa paginii din Cloud Dashboard: /org/ID/….
• Fiecare cerere poartă cheia în antetul X-Api-Key. Merge și Authorization: Bearer fsk_….
• {tenantId} din cale trebuie să fie organizația care a creat cheia; altă valoare răspunde 403.
• Apelează API-ul de pe serverul tău. Browserele de pe alte site-uri sunt blocate (CORS), iar o cheie pusă într-o pagină web o poate citi oricine.
• Convenții: JSON în camelCase; proprietățile nule vin ca null; datele sunt ISO 8601 în UTC, cu Z. În răspunsuri, enumerările vin ca nume (Active, Succeeded); în corpul comenzilor le trimiți ca numere.
• Listele sunt paginate cu page (de la 1) și pageSize (implicit 20, între 1 și 100; o valoare din afară e ajustată, nu refuzată).
• API-ul nu are limită de apeluri pe aceste rute.

curl -X POST "https://cloud-api.fiscallink.ro/api/v2/tenants/{tenantId}/integrator/cash-registers/DT000001/commands/print-report-x" \
  -H "X-Api-Key: fsk_..."

{
  "page": 1,
  "pageSize": 20,
  "total": 1,
  "items": []
}

Comenzi permise

Un integrator poate trimite: raport Z, raport X, bon fiscal, bon nefiscal și citirea cotelor TVA.

O comandă trimisă către o casă care nu e a ta, nu e Active, n-a dat încă acordul sau al cărei abonament nu dă acces primește același 404, care nu confirmă dacă seria există.

Ciclul unei comenzi

1. Trimiți comanda. Răspunsul e imediat 202 cu un commandId, fie că e casa conectată, fie că nu.
2. Interoghezi „Starea unei comenzi” la fiecare 1–2 secunde până când status e final.
3. Rezultatul casei e în body, iar codul ei în statusCode.

• Casă offline. Comanda rămâne Pending și nu expiră: pleacă atunci când casa se reconectează. Un raport Z sau un bon din coadă se poate tipări și după câteva zile.
• O comandă pe rând. Comenzile pentru aceeași casă rulează strict una după alta; case diferite lucrează în paralel.
• Fără hârtie. Pe o casă live, bonul fiscal și cel nefiscal se retrimit automat la fiecare 60 de secunde, cu un commandId nou. Continuă să interoghezi ID-ul inițial: răspunsul e reîncercarea, cu propriul commandId și cu retryOfCommandId egal cu ID-ul tău.
• Aceeași comandă nu rulează de două ori. Dacă aceeași comandă ajunge din nou la casă, aplicația răspunde cu rezultatul salvat și nu mai trimite nimic la casă. O trimitere nouă e însă o comandă nouă.

Reîncercări și Idempotency-Key

Un timeout sau o conexiune căzută te lasă fără răspuns: comanda poate fi în coadă sau nu. Trimite un antet Idempotency-Key cu fiecare comandă pe care o creezi și reîncearcă cu aceeași cheie. API-ul pune comanda în coadă o singură dată și răspunde la fiecare repetare cu primul commandId, așa că o reîncercare nu tipărește niciodată un al doilea bon.

• Creează un GUID nou pentru fiecare vânzare sau comandă și salvează-l împreună cu vânzarea înainte de primul apel, ca aplicația ta să reîncerce cu aceeași cheie chiar și după o repornire.
• Reîncearcă aceeași cerere cu aceeași cheie până primești un răspuns. Orice scriere a unui GUID este acceptată; API-ul îl păstrează cu litere mici și îl ține minte 30 de zile, după care cheia este o cerere nouă.
• O vânzare nouă primește o cheie nouă, chiar dacă are aceleași produse. O cheie care revine cu o altă cerere este refuzată cu 409 și nu se pune nimic în coadă.
• Fără antet nu se schimbă nimic: fiecare cerere este o comandă nouă. Antetul este acceptat de rutele care creează comenzi și de perechile lor /sandbox.

Ce răspunde API-ul

• 202: Prima cerere cu o cheie: intră în coadă ca de obicei.
• 202: Aceeași cerere din nou, cu aceeași cheie: din nou primul răspuns, inclusiv commandId, cu antetul Idempotent-Replayed: true. Nu se pune nimic nou în coadă.
• 409: Cheia a fost deja folosită pentru o altă cerere: altă casă, altă comandă sau alt corp.
• 400: Antetul nu este un singur GUID sau este trimis de două ori.
• 500: Comanda nu a putut fi salvată. Nu s-a pus nimic în coadă; reîncearcă cu aceeași cheie.

„Starea unei comenzi” și listele de comenzi arată cheia în requestId.

Pe casă

Cheia ajunge, împreună cu bonul fiscal, și la aplicația FiscalLink de pe casă. Dacă un bon cu aceeași cheie este deja pe hârtie — după o reîncercare din cauza lipsei de hârtie sau o retrimitere din panou — aplicația răspunde cu acel bon în loc să-l tipărească din nou, iar rezultatul conține replayedFromCommandId.

Dacă o încercare este întreruptă înainte ca casa să confirme bonul (răspunsul la închidere s-a pierdut sau aplicația s-a oprit în timpul bonului), aplicația nu poate ști dacă s-a tipărit. Acea încercare eșuează cu propria eroare și code: receipt_close_unconfirmed; o încercare ulterioară a aceleiași vânzări eșuează cu 424 și code: receipt_outcome_unknown, în loc să riște un al doilea bon. Verifică ultimul bon de pe casă; dacă vânzarea nu este pe el, trimite-o ca o comandă nouă, cu o cheie nouă.

O aplicație FiscalLink mai veche decât această funcție ignoră cheia pe casă; verificarea proprie a API-ului se aplică în continuare. Rutele /sandbox acceptă același antet și răspund la fel, dar simulatorul nu modelează partea casei.

Paginare

Listele se paginează cu page și pageSize și răspund cu același înveliș. page începe de la 1 (implicit 1). pageSize are implicit 20 și se ajustează la 1–100: o valoare în afara intervalului se corectează, nu se refuză.

Convenții

• Datele sunt ISO 8601, în UTC, cu Z, de exemplu 2026-09-25T09:15:01Z. Pot apărea și fracțiuni de secundă.
• Enumerările vin ca nume în răspunsuri (Active, Succeeded). În corpul comenzilor, trimite-le ca numerele documentate aici.
• Proprietățile JSON sunt camelCase. Proprietățile nule se trimit ca null, nu lipsesc.
• API-ul nu are limită de apeluri pe aceste rute.

Trimitere către mai multe case

Din dashboard, la Comenzi, poți trimite o comandă către până la 100 de case odată. Răspunsul are un rezultat pentru fiecare casă, iar casele duplicate se numără o singură dată. Cu o cheie API trimiți câte o comandă pe casă, cu rutele de mai jos.

Datele fiscale

Trimiți comenzi, nu citești datele clientului. Vezi doar comenzile tale și rezultatul lor, niciodată bonurile, rapoartele sau analizele clientului. Clientul vede documentele fiscale pe care le produc comenzile tale, dar nu și rândurile tale de comenzi. Cadrele trimise efectiv la casă le văd doar administratorii platformei: câmpul trace e mereu null pentru cheile API.

Facturare

• Organizația: 100 lei pe an +TVA.
• Casele: le adaugi gratuit, oricâte. Prima comandă reușită pe o casă deschide o fereastră plătită de o lună, din acel moment; toate comenzile din fereastră sunt incluse, iar suma se facturează când fereastra se încheie, pe factura lunii în care s-a încheiat. Comenzile eșuate nu se facturează. Lunile deja folosite rămân facturate și după ce scoți casa.
• Prețul pe casă depinde de câte case folosești în luna respectivă; toate casele plătesc treapta în care cade totalul:

• Sumele le calculează API-ul. Le vezi cu „Utilizarea lunii” (GET /api/tenants/{tenantId}/integrator/usage). O estimare găsești la Prețuri pentru integratori (/integrators/pricing).
• Pentru comenzile tale, clientul nu are nevoie de licență proprie: plătești tu casa pe care o folosești. O casă aflată pe o înregistrare activă de integrator nu mai poate cumpăra licență proprie; o casă care avea deja licență poate fi preluată și de un integrator.

Daisy și vânzarea liberă

O casă Daisy nu poate vinde un produs care nu e programat în ea. Când organizația ta pornește „Vânzare liberă pe casele Daisy” (Cloud Dashboard → Setări → Date companie), FiscalLink vinde fiecare linie liberă pe o casă Daisy ca articol programat și îl programează întâi dacă lipsește. Setarea se aplică tuturor bonurilor de pe casele tale Daisy, inclusiv celor care nu trec prin Cloud (Shopify, casa însăși). Nu trimiți nimic în plus în cereri. Doar proprietarii și administratorii o pot schimba. Cu setarea oprită, decide aplicația FiscalLink de pe fiecare casă.

În referință

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

• API Cloud: comenzi
  • Bonuri
  • Rapoarte
  • Cote TVA
  • Numerar și sertar
  • Comenzi
• API Cloud: administrare
  • Clienți
  • Coduri de activare
  • Case
  • Utilizare
• Toate obiectele