API Headless

API-ul Headless este un set de endpoint-uri HTTP pentru administrarea programatică a driverului FisCool, fără a folosi interfața grafică. Este ideal pentru mediile integrate în care driverul rulează în fundal și este administrat integral de aplicația gazdă.

Toate endpoint-urile se află sub calea /manage, pe același server ca API-ul HTTP (implicit http://127.0.0.1:10123), folosesc metoda POST și acceptă/returnează JSON. Aceeași verificare de Origin se aplică cererilor din browser. Erorile folosesc corpul standard {"status": ..., "error": "..."}.

Administrarea Dispozitivelor

Salvare Dispozitiv Fiscal

Adaugă sau actualizează configurarea unui dispozitiv fiscal.

Important: înainte de a salva un dispozitiv, apelați /manage/get_supported_devices pentru a obține valorile valide de manufacturer și model. Trebuie folosite exact șirurile returnate de acel endpoint.

Notă: furnizați câmpul id doar când editați un dispozitiv existent. Când id lipsește (sau este UUID-ul nul), se creează un dispozitiv nou.

Corpul Cererii (DeviceConfig):

{
  "id": "uuid-string",                  // doar la editare
  "name": "Imprimanta Mea",
  "manufacturer": "Datecs",
  "model": "DP25",
  "connection_details": {
    "type": "Serial",
    "details": { "port": "COM3", "baud_rate": 115200 }
  },
  "notes": "Casa principală",           // opțional
  "enabled": true,                      // opțional, implicit true
  "scan_folder": "C:\\FisCool\\INP",    // opțional: activează interfața de fișiere INP
  "auto_send_card_to_pos": false,       // opțional: trimite plățile card către un POS asociat
  "linked_pos_device_id": null,         // opțional: UUID-ul terminalului POS asociat
  "operator_override": null,            // opțional: {"code": 1-30, "password": "8 cifre"}
  "include_qr_on_receipt": null         // opțional, doar Datecs: QR cu bon-ID pe bonuri
}

Tipuri de Conexiune și Suport pe Platforme

{
  "port": "COMx",
  "baud_rate": 115200
}

{
  "ip_address": "192.168.1.100",
  "port": 9100
}

{
  "device_selector": "vid:pid",
  "baud_rate": 115200
}

{
  "name": "Nume dispozitiv",
  "address": "AA:BB:CC:DD:EE:FF"
}

Răspuns:

{
  "success": true,
  "message": "Fiscal device saved successfully"
}

Ștergere Dispozitiv Fiscal

Elimină configurarea unui dispozitiv fiscal.

Corpul Cererii:

{ "id": "uuid-string" }

Răspuns:

{
  "success": true,
  "message": "Fiscal device deleted successfully"
}

Salvare Terminal POS

Adaugă sau actualizează configurarea unui terminal POS. Urmează aceleași reguli de conexiune și de id ca dispozitivele fiscale; terminalele POS acceptă în plus câmpul bank.

Corpul Cererii (DeviceConfig):

{
  "id": "uuid-string",                  // doar la editare
  "name": "POS-ul Meu",
  "manufacturer": "PAX",
  "model": "A920 Pro",
  "bank": "BCR",                        // opțional
  "connection_details": {
    "type": "Network",
    "details": { "ip_address": "192.168.1.50", "port": 2000 }
  },
  "notes": "Casa 1"
}

Răspuns:

{
  "success": true,
  "message": "POS terminal saved successfully"
}

Ștergere Terminal POS

Elimină configurarea unui terminal POS.

Corpul Cererii:

{ "id": "uuid-string" }

Răspuns:

{
  "success": true,
  "message": "POS terminal deleted successfully"
}

Sistem și Configurare

Obținere Porturi COM Disponibile

Listează porturile seriale disponibile pe sistem (Windows; pe Android returnează un array gol).

Răspuns: un array de obiecte port:

[
  {
    "port_name": "COM3",
    "port_type": "USB",
    "description": "USB Device (VID: 0403, PID: 6001, Manufacturer: FTDI)"
  },
  {
    "port_name": "COM1",
    "port_type": "PCI",
    "description": null
  }
]

Obținere Dispozitive Suportate

Returnează producătorii și modelele suportate pentru dispozitive fiscale și terminale POS. Folosiți exact aceste valori la crearea dispozitivelor.

Răspuns (extras - lista completă depinde de versiunea driverului):

{
  "fiscal": {
    "manufacturers": [
      {
        "value": "DATECS",              // se folosește ca "manufacturer"
        "label": "DATECS",
        "models": ["DP25", "DP150", "FP700", "WP50", ...],   // se folosește ca "model"
        "default_port": 3999,
        "supports_serial": true,
        "supports_network": true
      },
      ...
    ]
  },
  "pos": {
    "banks": ["Banca Transilvania", "BCR", ...],
    "manufacturers": [ ... aceeași structură ... ]
  }
}

Obținere Configurare Notificări

Citește setările curente de notificare.

Răspuns (NotificationConfig):

{
  "email_list": ["admin@example.com", "support@magazin.ro"],
  "send_z_report_email": true
}

Salvare Configurare Notificări

Actualizează setările de notificare.

Corpul Cererii (NotificationConfig):

{
  "email_list": ["admin@example.com", "manager@example.com"],
  "send_z_report_email": true
}

Răspuns:

{
  "success": true,
  "message": "Notification config saved successfully"
}

Jurnal și Actualizări

Obținere Intrări Jurnal

Returnează jurnalul de operațiuni al driverului (cele mai recente primele, maximum 5000 de intrări per apel). Util pentru audit și istoric.

Corpul Cererii: ambele câmpuri opționale; timestamp-uri Unix în secunde:

{
  "start_time": 1672531200,
  "end_time": 1672617600
}

Structura unei Intrări de Jurnal

Tipuri de Acțiuni

Exemplu de Răspuns:

[
  {
    "id": 1024,
    "timestamp": "2023-10-27T10:30:00Z",
    "device_name": "Casa Principală",
    "device_id": "uuid-string",
    "action_type": "PrintReceipt",
    "description": "Bon fiscal",
    "success": true,
    "error_message": null,
    "receipt_data": { "lines": [ ... ], "payments": [ ... ] },
    "amount_cents": 1500,
    "full_text": null,
    "transaction_id": null,
    "authorization_code": null,
    "voided": false,
    "bon_id": null
  }
]

Verificare Actualizări

Verifică dacă este disponibilă o versiune mai nouă a driverului.

Răspuns (UpdateCheckResponse):

{
  "has_update": true,
  "latest_version": "1.2.0",
  "versions": [
    {
      "version": "1.2.0",
      "description": "Suport adăugat pentru noi modele Datecs",
      "date": "2023-10-25",
      "manifest_url": "https://...",
      "is_current": false,
      "is_newer": true
    }
  ]
}

Instalare Actualizare

Pornește instalarea actualizării. Pe desktop, operatorul trebuie să confirme actualizarea într-un dialog afișat de driver; dacă refuză, răspunsul are "success": false.

Corpul Cererii:

{ "version": "1.2.0" }

Răspuns:

// confirmat
{ "success": true,  "message": "Update installation started" }

// refuzat de operator
{ "success": false, "message": "User denied update" }