> Source: https://fiscal.link/integrators/docs/local
> Rutele REST ale aplicației FiscalLink: bon fiscal dintr-un singur apel, bon nefiscal, rapoarte X și Z, cote TVA, articole (PLU), afișaj client. Aceleași rute pentru Datecs, Tremol și Daisy.

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

1.  Afli adresa: `GET /get-secure-api-address`.
2.  Trimiți bonul întreg dintr-un singur apel: `POST /print-fiscal-receipt`.
3.  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.
4.  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ță:

-   [API local](https://fiscal.link/integrators/docs/reference/local)
    -   [Adresa API-ului](https://fiscal.link/integrators/docs/reference/local/service)
    -   [Bonuri](https://fiscal.link/integrators/docs/reference/local/receipts)
    -   [Rapoarte](https://fiscal.link/integrators/docs/reference/local/reports)
    -   [Numerar și sertar](https://fiscal.link/integrators/docs/reference/local/cash)
    -   [Cote TVA](https://fiscal.link/integrators/docs/reference/local/vat-rates)
    -   [Articole (PLU)](https://fiscal.link/integrators/docs/reference/local/articles)
    -   [Afișaj client](https://fiscal.link/integrators/docs/reference/local/display)
    -   [Coduri de bare și linii](https://fiscal.link/integrators/docs/reference/local/barcodes)
-   [Toate obiectele](https://fiscal.link/integrators/docs/reference)