HTTP API

The FisCool driver provides a RESTful HTTP API for device operations and system management. This API is stateless, making it simple to integrate with any system that can make HTTP requests.

Base Configuration

Default URL: http://127.0.0.1:10123

Content-Type: application/json for all POST requests

Authentication: None (API runs on localhost by default)

System Information Endpoints

GET /

Description: Health check endpoint to verify API server is running.

Response: Plain text

FisCool API Server running.

GET /devices/fiscal

Description: Retrieves all fiscal devices.

Response:

{
  "fiscal_devices": [
    {
      "config": {
        "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
        "name": "Casa 1 - DATECS FP-2000",
        "manufacturer": "DATECS",
        "model": "FP-2000",
        "connection_details": {
          "type": "Serial",
          "details": {
            "port": "COM3", 
            "baud_rate": 115200
          }
        },
        "notes": "Main cash register",
        "enabled": true,
        "scan_folder": "C:\\FisCool\\InpFiles",
        "auto_send_card_to_pos": true,
        "linked_pos_device_id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e"
      },
      "status": "Connected",
      "status_text": "Conectat",
      "vat_rates": {
        "A": 1900,    // 19.00% in basis points
        "B": 500,     // 5.00%
        "C": 0        // 0.00%
      },
      "connected_device_id": "DT123456"
    }
  ]
}

GET /devices/pos

Description: Retrieves all POS terminals.

Response:

{
  "pos_terminals": [
    {
      "config": {
        "id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e",
        "name": "POS Terminal 1",
        "manufacturer": "PAX",
        "model": "A920 Pro",
        "bank": "BCR",
        "connection_details": {
          "type": "Network",
          "details": {
            "ip_address": "192.168.1.100",
            "port": 8080
          }
        },
        "enabled": true
      },
      "status": "Connected",
      "status_text": "Conectat",
      "connected_device_id": "PAX001"
    }
  ]
}

Device Operations

POST /devices/operation

Description: Executes device operations on fiscal devices or POS terminals. This is the primary endpoint for all device interactions.

Request Headers
HeaderRequiredDescription
Content-TypeYesapplication/json
Idempotency-KeyNoUnique key to prevent duplicate operations
Request Body Structure
{
  "device_id": "UUID",        // Target device UUID
  "operation": {             // Operation object (see Device Operations page)
    "type": "operation_name",
    // ... operation-specific parameters
  }
}
Complete Examples
Example 1: Print Simple Receipt
POST /devices/operation
Content-Type: application/json

{
  "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "operation": {
    "type": "print_receipt",
    "lines": [
      {
        "type": "item",
        "description": "Cafea Espresso",
        "quantity_thousandths": 1000,      // 1.000 pieces
        "unit_price_cents": 850,           // 8.50 RON
        "vat": "19%",
        "um": "buc"
      },
      {
        "type": "text", 
        "text": "Mulțumim pentru cumpărături!"
      }
    ],
    "payments": [
      {
        "method": "cash",
        "amount_cents": 850
      }
    ],
    "flags": {
      "is_invoice": false
    },
    "close_action": "close"
  }
}
Example 2: Print Invoice with Card Payment
POST /devices/operation
Content-Type: application/json

{
  "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "operation": {
    "type": "print_receipt",
    "lines": [
      {
        "type": "item",
        "description": "Servicii Consultanță IT",
        "quantity_thousandths": 1000,
        "unit_price_cents": 120000,        // 1200.00 RON
        "vat": "19%"
      }
    ],
    "payments": [
      {
        "method": "card",
        "amount_cents": 120000
      }
    ],
    "buyer": {
      "vat_number": "RO12345678"
    },
    "flags": {
      "is_invoice": true
    },
    "close_action": "close"
  }
}
Example 3: Print Z Report
POST /devices/operation
Content-Type: application/json

{
  "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "operation": {
    "type": "print_z"
  }
}
Example 4: Cash Operations
POST /devices/operation
Content-Type: application/json

{
  "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "operation": {
    "type": "deposit_cash",
    "amount": 5000                 // 50.00 RON in cents
  }
}
Example 5: POS Sale
POST /devices/operation
Content-Type: application/json

{
  "device_id": "b2c3d4e5-f6a7-5b8c-9d0e-1f2a3b4c5d6e",
  "operation": {
    "type": "sale",
    "amount": 2500                 // 25.00 RON in cents
  }
}
Example 6: Generate JE Report
POST /devices/operation
Content-Type: application/json

{
  "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "operation": {
    "type": "je_report",
    "range": {
      "type": "date",
      "start": "2024-01-01",
      "end": "2024-01-31"
    },
    "doc_type": "fiscal_receipts",
    "output_mode": "read_line_by_line"
  }
}
Response Format
Success Response (HTTP 200)
{
  "status": 0,
  "msg": "Receipt printed",
  "slip_number": 1234            // Operation-specific data
}
Device Error Response (HTTP 200)

When the API call is valid but the device operation fails:

{
  "status": -500,
  "error": "Lipsă hârtie în imprimantă"
}
API Error Response (HTTP 4xx/5xx)

When the API request itself is invalid:

// HTTP 400 Bad Request
{
  "status": 400,
  "error": "Invalid device_id format"
}

// HTTP 404 Not Found  
{
  "status": 404,
  "error": "Device not found: a1b2c3d4-..."
}
Idempotency

For critical operations like receipt printing, use the Idempotency-Key header to prevent duplicate executions:

POST /devices/operation
Content-Type: application/json
Idempotency-Key: receipt-2024-01-15-001

{
  "device_id": "...",
  "operation": { ... }
}

If the same key is used multiple times, the original result is returned without re-executing the operation.

Error Handling

The API uses standard HTTP status codes and returns detailed error information in JSON format.

HTTP StatusDescriptionBody Format
200Request successful, check status in bodyDevice operation result
400Bad request (invalid JSON, missing fields)Error description
404Device not foundError description
500Internal server errorError description

Configuration

The HTTP API server configuration can be modified through the application settings:

  • Host: Default 127.0.0.1 (localhost only)
  • Port: Default 10123
  • Enabled: Can be disabled if not needed

Integration Examples

cURL Examples

# Print a simple receipt
curl -X POST http://127.0.0.1:10123/devices/operation \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "operation": {
      "type": "print_receipt",
      "lines": [{"type": "item", "description": "Test", "quantity_thousandths": 1000, "unit_price_cents": 100, "vat": "19%"}],
      "payments": [{"method": "cash", "amount_cents": 100}],
      "flags": {"is_invoice": false},
      "close_action": "close"
    }
  }'

# Get system status
curl http://127.0.0.1:10123/devices/fiscal

JavaScript/Node.js Example

const axios = require('axios');

async function printReceipt(deviceId, items, payments) {
  try {
    const response = await axios.post('http://127.0.0.1:10123/devices/operation', {
      device_id: deviceId,
      operation: {
        type: 'print_receipt',
        lines: items,
        payments: payments,
        flags: { is_invoice: false },
        close_action: 'close'
      }
    });
    
    if (response.data.status === 0) {
      console.log('Receipt printed successfully:', response.data.slip_number);
    } else {
      console.error('Device error:', response.data.error);
    }
  } catch (error) {
    console.error('API error:', error.response?.data || error.message);
  }
}

Python Example

import requests
import json

def print_receipt(device_id, items, payments):
    url = "http://127.0.0.1:10123/devices/operation"
    payload = {
        "device_id": device_id,
        "operation": {
            "type": "print_receipt",
            "lines": items,
            "payments": payments,
            "flags": {"is_invoice": False},
            "close_action": "close"
        }
    }
    
    try:
        response = requests.post(url, json=payload)
        response.raise_for_status()
        
        result = response.json()
        if result.get("status") == 0:
            print(f"Receipt printed: {result.get('slip_number')}")
        else:
            print(f"Device error: {result.get('error')}")
            
    except requests.exceptions.RequestException as e:
        print(f"API error: {e}")

# Example usage
items = [{
    "type": "item",
    "description": "Coffee",
    "quantity_thousandths": 1000,
    "unit_price_cents": 250,
    "vat": "19%"
}]
payments = [{"method": "cash", "amount_cents": 250}]
print_receipt("a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d", items, payments)