Headless API

The Headless API is a set of HTTP endpoints for managing the FisCool driver programmatically, without using the GUI. It is ideal for integrated environments where the driver runs in the background and is managed entirely by the host application.

All endpoints live under the /manage path on the same server as the HTTP API (default http://127.0.0.1:10123), use the POST method, and accept/return JSON. The same Origin check applies to browser requests. Errors use the standard error body {"status": ..., "error": "..."}.

Device Management

Save Fiscal Device

Adds or updates a fiscal device configuration.

Important: before saving a device, call /manage/get_supported_devices to obtain the valid manufacturer and model values. You must use the exact strings returned by that endpoint.

Note: provide the id field only when editing an existing device. When id is missing (or the nil UUID), a new device is created.

Request Body (DeviceConfig):

{
  "id": "uuid-string",                  // only when editing
  "name": "My Printer",
  "manufacturer": "Datecs",
  "model": "DP25",
  "connection_details": {
    "type": "Serial",
    "details": { "port": "COM3", "baud_rate": 115200 }
  },
  "notes": "Main register",             // optional
  "enabled": true,                      // optional, default true
  "scan_folder": "C:\\FisCool\\INP",    // optional: enables the INP file interface
  "auto_send_card_to_pos": false,       // optional: route card payments to a linked POS
  "linked_pos_device_id": null,         // optional: UUID of the linked POS terminal
  "operator_override": null,            // optional: {"code": 1-30, "password": "8 digits"}
  "include_qr_on_receipt": null         // optional, Datecs only: bon-ID QR on receipts
}

Connection Types & Platform Support

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

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

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

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

Response:

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

Delete Fiscal Device

Removes a fiscal device configuration.

Request Body:

{ "id": "uuid-string" }

Response:

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

Save POS Terminal

Adds or updates a POS terminal configuration. Follows the same connection and id rules as fiscal devices; POS terminals additionally accept a bank field.

Request Body (DeviceConfig):

{
  "id": "uuid-string",                  // only when editing
  "name": "My POS",
  "manufacturer": "PAX",
  "model": "A920 Pro",
  "bank": "BCR",                        // optional
  "connection_details": {
    "type": "Network",
    "details": { "ip_address": "192.168.1.50", "port": 2000 }
  },
  "notes": "Counter 1"
}

Response:

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

Delete POS Terminal

Removes a POS terminal configuration.

Request Body:

{ "id": "uuid-string" }

Response:

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

System & Configuration

Get Available COM Ports

Lists the serial ports available on the system (Windows; returns an empty array on Android).

Response: an array of port objects:

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

Get Supported Devices

Returns the supported manufacturers and models for fiscal devices and POS terminals. Use these exact values when creating devices.

Response (excerpt - the full list depends on the driver version):

{
  "fiscal": {
    "manufacturers": [
      {
        "value": "DATECS",              // use as "manufacturer"
        "label": "DATECS",
        "models": ["DP25", "DP150", "FP700", "WP50", ...],   // use as "model"
        "default_port": 3999,
        "supports_serial": true,
        "supports_network": true
      },
      ...
    ]
  },
  "pos": {
    "banks": ["Banca Transilvania", "BCR", ...],
    "manufacturers": [ ... same structure ... ]
  }
}

Get Notification Config

Reads the current notification settings.

Response (NotificationConfig):

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

Save Notification Config

Updates the notification settings.

Request Body (NotificationConfig):

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

Response:

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

Journal & Updates

Get Journal Entries

Returns the driver's operation journal (most recent first, capped at 5000 entries per call). Useful for auditing and history.

Request Body: both fields optional; Unix timestamps in seconds:

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

Journal Entry Structure

Action Types

Response Example:

[
  {
    "id": 1024,
    "timestamp": "2023-10-27T10:30:00Z",
    "device_name": "Main Printer",
    "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
  }
]

Check for Updates

Checks whether a newer driver version is available.

Response (UpdateCheckResponse):

{
  "has_update": true,
  "latest_version": "1.2.0",
  "versions": [
    {
      "version": "1.2.0",
      "description": "Added support for new Datecs models",
      "date": "2023-10-25",
      "manifest_url": "https://...",
      "is_current": false,
      "is_newer": true
    }
  ]
}

Install Update

Starts the update installation. On desktop, the operator must confirm the update in a dialog shown by the driver; if refused, the response has "success": false.

Request Body:

{ "version": "1.2.0" }

Response:

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

// refused by the operator
{ "success": false, "message": "User denied update" }