API Mode Reference-Guide
API Mode Reference-Guide
                                                                                    2
        ADDON.Launch .........................................................................................................................................35
    ESPF SERVICE ................................................................................................................................................ 36
        ESPF.GetParam ........................................................................................................................................ 36
        ESPF.SetParam ..........................................................................................................................................37
    SCANNER SERVICE ..................................................................................................................................... 38
        SCAN.Version.............................................................................................................................................. 38
        SCAN.Acquire ............................................................................................................................................. 39
        SCAN.GetSession ...................................................................................................................................... 41
        SCAN.Begin ................................................................................................................................................. 42
        SCAN.End ..................................................................................................................................................... 43
        SCAN.GetImages ..................................................................................................................................... 44
        SCAN.SendCommand .......................................................................................................................... 45
APPENDIX ............................................................................................................................................................. 47
    ESPF SERVER CONFIGURATION ........................................................................................................ 47
        Configuration file available settings: ............................................................................................ 48
    RETURNED ERRORS .................................................................................................................................. 50
        Major state.....................................................................................................................................................55
        Minor state ....................................................................................................................................................55
Disclaimer.............................................................................................................................................................. 60
                                                                                    3
Evolis Services Provider Framework Concept
The Evolis Services Provider Framework and Evolis Services Provider Framework 2
(based on Evolis Premium Suite 2) is a server and the gateway to the Evolis Suite
(Evolis, Edikio, Badgy Premium Suite) features (supervision or standard mode)
using requests.
The request process is based on the JSON-RPC protocol, which eases the
enablement of clients as described in the next sections.
                                         4
        Quick Description of the services
        Request model
        The request model used between the clients and the ESPF service leverages JSON-
        RPC v2.0, a light-weight and stateless RPC (Remote Procedure Call) protocol using
        the JSON format.
        Notification and Batch concepts of JSON-RPC v2.0 are not supported for the ESPF.
        The protocol is used in compliance with the following specifications:
                                                   5
Pay attention than the application software development made with Premium
SDK are fully compliant with Primacy 2 model but could require modifications in
case of new Primacy2 features (scan, rewrite…).
To send a request, client (software) sends a Requests object and receives a reply
from the server in the form of a Response object
 REQUEST OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "method": "CMD.SendCommand",
     "params": {
           "command": "Rfv",
           "timeout": "5000",
          "device": "Evolis Primacy"
     }
 }
 RESPONSE OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "result": "1943"
 }
                                       6
This implementation, at the communication protocol level, must be carried out as
shown below:
(1)
(2)
(3)
     (1) During the connection, the IP address, server port, or Named pipe are
         identified according to the IPC communication protocol used.
     (2) Request is sent through a call on a full buffer(no data sent while buffer is
         sliced)
     (3) Response to the request is expected to b a single reply
When sending a request, if the reception of the request takes longer that a
configurable timeout (3,000 ms by default), the server will shut the communication
channel with the client (support for « half-open connections » issues).
                                         7
    Services – Technical description
    CMD SERVICE
    •       Sends commands in text or binary format
    •       Receives statuses in binary format
    •       Reset communication
REQUEST OBJECT
{
        "id": "1",
        "jsonrpc": "2.0",
        "method": "CMD.SendCommand",
        "params": {
              "command": "Rfv",
              "timeout": "5000",
              "device": "Evolis Primacy"
        }
}
RESPONSE OBJECT
{
        "id": "1",
        "jsonrpc": "2.0",
        "result": "1943"
}
                                                   8
    To send a binary command, data must be base64-encoded. The command
    parameter is made up of the encoded data complemented by the "base64:" prefix
REQUEST OBJECT
{
    {
         "id": "1",
         "jsonrpc": "2.0",
         "method": "CMD.SendCommand",
         "params": {
               "device":      "Evolis     Primacy",
               "command":       "base64:G1Jmdg0=",
               "timeout": "3000"
         }
     }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "1943"
}
    If the response timeout is exceeded, the returned response will be an error with
    related error code.
    If the timeout setting is not indicated, default value will be affected. This value is
    3000 ms for the service. This parameter is not effective for a networked printer
    (Ethernet or WIFI).
                                              9
CMD.GetStatus                    Retrieve
                                  Retrievethe
                                           the binary statusofofa adevice
                                               binary status        device
device                           Device name
Result                           Binary status of the device
error                            Error code
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "CMD.GetStatus",
    "params": {
        "device": "Evolis Primacy"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "88D02420204000000000000000000000800C2000000000000000000000000000:32005 "
}
    This method can be called even if the printer is printing a job or processing a
    command.
                                              10
CMD.ResetCom                                        Reset communication with a device
Timeout                                             Timeout in milliseconds
Device                                              Device name
Result                                              Ok if successful
Error                                               Error code
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0", "method":
    "CMD.ResetCom", "params":
    {
          "timeout": "30000",
          "device": "Evolis Primacy"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "OK"
}
    When response timeout is exceeded, returned response will be an error with related
    error code.
    If the time out setting is not indicated, a default value will be provided. This value is
    of 3000 ms for the service. This parameter is not considered when the device is
    networked.
                                               11
PRINT SERVICE
                                   12
PRINT.Begin                                  Initiates the printing session
Device                                       device name
Session                                      optional : to set in case the automatic job
                                             ID is not adapted to your use-case
Result                                       Job ID is successful
Error                                        Error code in case of fail
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "PRINT.Begin",
    "params": {
          "device": "Evolis Primacy"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0", "result":
    "JOB000002"
}
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "PRINT.Begin",
    "params": {
          "device": "Evolis Primacy",
          "session": "CUSTOMJOBID"
    }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0", "result":
"CUSTOMJOBID"
}
                                        13
    Printing session: a timeframe during which a printer is assigned to one or several
    printing jobs specified in the following format if generated automatically:
    JOBXXXXXX.
    The service can manage only one printing session (job) at a time per printer
    instance.
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method": "PRINT.Set",
     "params": {
           "session": "JOB000002",
           "data": "FColorBrightness=VAL12;GRibbonType=RC_YMCKO"
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "OK"
}
    The settings.xml file describes all printing parameters and their possible values for
    eachprinter model. This file is available from:
                                             14
PRIMACY 2 : Available settings for Evolis Premium Suite release
above to version 7.0.0.0
To get the available settings and their possible values with newest Evolis Premium
Suite, use the following command line :
or
Replace "Evolis Primacy 2" by the correct name as in printer and devices.
Evosettings utility has different options that are described when you run the
command.
                                        15
PRINT.SetBitmap                                  Defines the graphics data to be printed
Session                                          JOB ID
Face                                             front or back
Panel                                            color, resin or varnish
Data                                             Image data (bitmap) encoded in base64
Result                                           OK
Error                                            error code and related message
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method": "PRINT.SetBitmap",
     "params": {
           "session": "JOB000002",
           "face": "front",
           "panel": "color",
           "data": "base64:Qk12Ix4AAAAAADYAAAAo...
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "OK"
}
    Method will be called only once per card side and panel type. Color panel type
    includes graphical data required for the three YMC panels.
    If the method is called twice or three times for a side, color panel will be the primary
    source, while the black, and/or overlay panel will be set as optional.
    For the YMCKOO ribbon (available only for Evolis Primacy 2 printer), set the panel
    property to varnish to use the second overlay.
                                              16
PRINT.Print                                        Run a print job
Session                                            JOB ID
Result                                             OK if successful
Error                                              error code and related message
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method":      "PRINT.Print",
     "params": {
           "session": "JOB000002"
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "OK"
}
    The printing traffic is monitored during the printing job. Feature is always enabled
    and not configurable.
    When calling the PRINT method, the GetEvent method from the SUPERVISION
    service must be polled on a regular basis. If an event is identified, an action must be
    taken so that the print job can be finalized.
                                              17
PRINT.GetJobID                          Get current printing session JOB ID
device                                  device name
Result                                  current JOB ID if successful
Error                                   error code and related message
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "PRINT.GetJobID",
    "params": {
          "device": "Evolis Primacy"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0", "result":
    "JOB000002"
}
                                       18
PRINT.End       Close a print session                Additional information
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method": "PRINT.End",
     "params": {
           "session": "JOB000002"
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "OK"
}
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method": "PRINT.End",
     "params": {
           "device": "Evolis Primacy"
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "OK"
}
                                               19
SETTING SERVICE
                                  20
SETTING.Begin                         Start a configuration session
device                                device name
Result                                OK if successful
Error                                 error code and related message
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "SETTING.Begin",
    "params": {
        "device": "Evolis Primacy"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0", "result":
    "SET000001"
}
                                     21
SETTINGS.Import                              Import parameters
Session                                      Session ID
Format                                       printer
Data                                         Base64 encoded data (for XML format)
Result                                       OK if successful
Error                                        error code and related message
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "SETTING.Import",
    "params": {
          "session":   "SET000001",
          "format": "printer"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "OK"
}
    With this method, parameters can be imported via the active session, and in a
    non-persistent way (until the end of the configuration session). For further use,
    use the demo program in the API mode folder.
                                            22
SETTING.Get                              Gets the value of a parameter
Session                                  Session ID
Data                                     key  parameter ID
Result                                   Parameter value
Error                                    error code and related message
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method": "SETTING.Get",
     "parameters": {
           "session":    "SET000001",
           "data": "FColorContrast"
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "15"
}
                                        23
SETTING.Set                                        Sets the value of a parameter
Session                                            Session ID
Data                                               Key=value ID of parameter with new value
Result                                             OK if successful
Error                                              error code and related message
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method": "SETTING.Set",
     "parameters": {
           "session": "SET000001",
           "data": "FColorContrast=18"
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "OK"
}
    The settings.xml file describes all printing parameters and their possible values
    for eachprinter model. This file is available from:
    To get the available settings for Primacy 2, pay attention to use the new evosettings.exe
    tool (settings is no more available via the xml file).
    This tool is available here (default installation path ) once you have installed Evolis Premium
    Suite 2 :
    The full help/manual of the evosettings utility is available by invoking - - help argument, see
    below :
                                                  24
Get the current settings for a Primacy 2 thanks to evosettings
Use the following command to get the current setting for a printer:
To get all available settings and their possible values for a printer, please use following
command :
                                            25
SETTING.Export              Exports parameters
Session                     Session ID
Format                      From printer to device
                            text in text format
                            xml to a data file (.dat) for the device
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "SETTING.Export",
    "params": {
          "session":   "SET000001",
          "format": "text"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "BBlackManagement=ALLBLACKPOINT; BColorBrightness=VAL10; BColorContrast
=VAL10; BHalftoning=THRESHOLD; BMonochromeContrast=VAL10; BOverlayContrast=VAL10;
BOverlayManagement=FULLVARNISH; BPageRotate180=OFF;
FBlackManagement=ALLBLACKPOINT; FColorBrightness=VAL10; FColorContrast=VAL13;
FHalftoning=THRESHOLD; FMonochromeContrast=VAL10; FOverlayContrast=VAL10;
FOverlayManagement=FULLVARNISH"
}
                                             26
SETTING.End                   Ends the session
Session                       Session ID
Result                        OK if successful
Error                         error code and related message
REQUEST OBJECT
{
     "id": "1",
     "jsonrpc": "2.0",
     "method": "SETTING.End",
     "params": {
           "session": "SET000001"
     }
}
RESPONSE OBJECT
{
"id": "1",
"jsonrpc": "2.0",
"result": "OK"
}
                                                 27
    SUPERVISION SERVICE
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "SUPERVISION.List",
    "params": {
          "level": "2",
          "device": "Evolis Primacy"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "Primacy,READY,PRINTER_READY"
}
    If several printers are "subscribed", response to the request will have the following
    format, respectively for level=2, level=1 and level=0.
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": " Primacy,READY,PRINTER_READY;Primacy2,WARNING,FEEDER_EMPTY"
}
                                             28
 RESPONSE OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "result": " Primacy,READY;Primacy2,WARNING"
 }
 RESPONSE OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "result": "Primacy,Primacy2"
 }
The minor states offer more detailed information of the major states.
The status reported by the SUPERVISION service is the same status that are
reported by the Print Center, before, after and during a print job
                                         29
Supervision.AddDevice      Subscribes a new device to the notification service
Device                     device name
Result                     Ok if successful
error                      error code and related message
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method":
    "SUPERVISION.AddDevice", "params":
    {
          "device": "Evolis Zenius"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "OK"
}
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method":
    "SUPERVISION.RemoveDevice",
    "params": {
          "device": "Evolis Zenius"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "OK"
}
                                         30
SUPERVISION.GetState         Requests the state of a device
 Device                      device name
 Result                      majorstate, minorstate
 Error                       error code and related message
 REQUEST OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "method": "SUPERVISION.GetState",
     "params": {
           "device": "Evolis Primacy"
     }
 }
 RESPONSE OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "result": "READY,PRINTER_READY"
 }
The states reported by the SUPERVISION service are the same states that are
reported by the Print Center before, after and during a print job. If it is needed to
test a specific status, for example not reported outside a print job by the Print
Center, it is recommended to use the method GetStatus of the CMD service.
                                          31
SUPERVISION.GetEvent      Returns the notification of an unexpected event, as well as
                          the list of actions for a device
Device                    device name
Result                    NONE if no notification
                          Minorstate, combination of actions
Error                     error code and related message
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "SUPERVISION.GetEvent",
    "params": {
          "device": "Evolis Primacy"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "ERR_MECHANICAL:CANCEL,RETRY"
}
                                          32
SUPERVISION.SetEvent       Executes an action when an unexpected event is notified on
                           a device
 Device                    device name
 Result                    minorstate:action possible actions : CANCEL, OK, RETRY
 Error                     error code and related message
 REQUEST OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "method": "SUPERVISION.SetEvent",
     "params": {
           "action": "FEEDER_EMPTY:CANCEL",
           "device": "Evolis Primacy"
     }
 }
 RESPONSE OBJECT
 {
     "id": "1",
     "jsonrpc": "2.0",
     "result": "OK"
 }
                                       33
    ECHO SERVICE
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "ECHO.Echo",
    "params": {
          "data": "Hello World"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "Hello World"
}
                                              34
    ADD-ON SERVICE
Run a third-party add-on software (mostly for smart and contactless encoding)
REQUEST OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "method": "ADDON.Launch",
    "params": {
        "command": "testplugin.exe" "data": "testdata1 testdata2 testdata3"
    }
}
RESPONSE OBJECT
{
    "id": "1",
    "jsonrpc": "2.0",
    "result": "0"
}
The Launch method triggers a response as soon as the application is fully executed.
    The application must be executed without involving the user.The ADD-ON service
    is disabled by default.
The folder hosting the add-ons can be configured in the ESPF service.
                                             35
      ESPF SERVICE
REQUEST OBJECT
{
      "id": "1",
      "jsonrpc": "2.0",
      "method": "ESPF.GetParam",
      "params": {
          "key": "ESPFServerManager.port"
      }
}
RESPONSE OBJECT
{
      "id": "1",
      "jsonrpc": "2.0",
      "result": "18000"
}
                                               36
ESPF.SetParam                Edits the value of server parameter
key                          Parameters name
data                         new value to be set
result                       OK if successful
error                        error code and related message
REQUEST OBJECT
{
      "id": "1",
      "jsonrpc": "2.0",
      "method": "ESPF.SetParam",
      "params": {
          "key": "ESPFServerManager.port",
          "data": "18001"
      }
}
RESPONSE OBJECT
{
      "id": "1",
      "jsonrpc": "2.0",
      "result": "OK"
}
        •   ESPFService.version
        •   ESPFService.requestlanguageversion:
      Other parameters can be edited only through the server’s configuration file :
            - For Evolis Premium Suite < 7.0.0.0 : ESPFsvc.properties file
            - For Evolis Premium Suite > 7.0.0.0 (Evolis Premium Suite                2):
               evoservice.properties
                                                37
             SCANNER SERVICE
    REQUEST OBJECT
{
             "id": "1",
             "jsonrpc": "2.0",
             "method": "SCAN.Version",
             "params": {
                "device": "Evolis Primacy 2"
             }
        },
    RESPONSE OBJECT
    {
              "id": "1",
              "jsonrpc": "2.0",
              "result": "WiseCube WIS-1000 2.09.L702A (02:01) [2107-0002]"
    }
             This request allows to know the current scanner version installed. Only available
             with Primacy 2 and Evolis Premium Suite release above 7.0.0.0.
                                                           38
    Acquire an image
SCAN.Acquire                         Scan a card with specific parameters
    key                               Parameters name
    Result                            Parameters value
    Error                             error code and related message
    REQUEST OBJECT
{
             "id": "1",
             "jsonrpc": "2.0",
             "method": "SCAN.Acquire",
             "params": {
                "device": "Evolis Primacy 2",
                "options": "DPI=300, CARD_SPEED=220",
                "images": "TOP, TOP_IR, BOTTOM, BOTTOM_IR",
                "eject": false
             }
        },
    RESPONSE OBJECT
    {
              "id": "1",
              "jsonrpc": "2.0",
              "result": {
                "images": {
                         "BOTTOM": "base64:<data>",
                         "BOTTOM_IR": "base64:<data>",
                         "TOP": "base64:<data>",
                         "TOP_IR":"base64:<data>"
              }
         }
}
                                                         39
             Example with a session:
    REQUEST OBJECT
{
             "id": "1",
             "jsonrpc": "2.0",
             "method": "SCAN.Acquire",
             "params": {
                "session": "SCAN1",
                "options": "DPI=300, CARD_SPEED=220",
                "images": "TOP, TOP_IR, BOTTOM, BOTTOM_IR",
                "eject": false
             }
        },
    RESPONSE OBJECT
    {
              "id": "1",
              "jsonrpc": "2.0",
              "result": {
                "images": {
                         "BOTTOM": "base64:<data>",
                         "BOTTOM_IR": "base64:<data>",
                         "TOP": "base64:<data>",
                         "TOP_IR":"base64:<data>"
              }
         }
}
             This request allows to scan a card and get the output as an image. If a card is inside
             the printer, it will be scanned, otherwise a card will be inserted.
                •   WIDTH : image width in millimeters , default value :540mm par défaut (CR80 card).
                •   HEIGHT : image height in millimeters, default value 860mm (CR80 card).
                •   DPI : 600 or 300, default value 600. Evolis printer is calibrated to scan in 600
                    DPI resolution, in case scan is performed in 300 DPI resolution, it is required
                    to adapt the CARD_SPEED value (e.g., 220).
                                                         40
                •   CARD_OFFSET : Synchronization of the scan with the card beginning edge.
                    Factory setting. Value between 90 and 220.
                •   CARD_LENGTH : is related to the card's length, default value is 1200 (CR80 card).
                •   CARD_SPEED : is related to the DPI resolution. Factory settings for 600 DPI.
                    Value between 150 and 350.
    REQUEST OBJECT
{
             "id": "1",
             "jsonrpc": "2.0",
             "method": "SCAN.GetSession",
        },
    RESPONSE OBJECT
    {
              "id": "1",
              "jsonrpc": "2.0",
              "result": "<Current_Session_value>"
    }
             This request allows to know the current scanner session. Only available with
             Primacy 2 and Evolis Premium Suite release above 7.0.0.0. No required parameters.
                                                         41
    Start a scanner session
SCAN.Begin                         Start a scanner session
key                                Parameters name
Result                             Parameters value
Error                              error code and related message
REQUEST OBJECT
{
        "id": "1",
        "jsonrpc": "2.0",
        "method": "SCAN.Begin",
        "params": {
           "device": "Evolis Primacy 2"
        }
    }
RESPONSE OBJECT
    {
        "id": "1",
        "jsonrpc": "2.0",
        "result": "SCAN1"
    }
        This request allows to start a scanner session. Only available with Primacy 2 and
        Evolis Premium Suite release above 7.0.0.0. Only one session at a time. The result is
        to use for the other requests of the same session.
                                                      42
    End a scanner session
SCAN.End                        End a scanner session
key                             Parameters name
Result                          Parameters value
Error                           error code and related message
REQUEST OBJECT
{
        "id": "1",
        "jsonrpc": "2.0",
        "method": "SCAN.End",
        "params": {
           "device": "SCAN1"
        }
    }
RESPONSE OBJECT
    {
        "id": "1",
        "jsonrpc": "2.0",
        "result": "OK"
    }
        This request allows to end a scanner session, to free the scanner. Only available with
        Primacy 2 and Evolis Premium Suite release above 7.0.0.0. Only one session at a
        time. The only parameter to use corresponds to the returned value by a previous
        call to "SCAN.Begin" (e.g.: SCAN1).
                                                   43
    Get images from scanner
SCAN.GetImages                     Get images from scanner
key                                Parameters name
Result                             Parameters value
Error                              error code and related message
REQUEST OBJECT
{
        "id": "1",
        "jsonrpc": "2.0",
        "method": "SCAN.GetImages",
        "params": {
           "session": "SCAN1",
           "images": "TOP, TOP_IR, BOTTOM, BOTTOM_IR"
        }
    }
RESPONSE OBJECT
{
        "id": "1",
        "jsonrpc": "2.0",
        "result": {
           "images": {
              "TOP": "base64:...",
              "BOTTOM": "base64:...",
           }
        }
    }
        This request allows to get the current scanner images, It only works in a session.
        This could get images from the previous SCAN.Acquire request. Only available with
        Primacy 2 and Evolis Premium Suite release above 7.0.0.0. Only one session at a
        time. The only parameter to use corresponds to the returned value by a previous
        call to "SCAN.Begin" (e.g.: SCAN1). Parameters are a list of image to get (see
        SCAN.Acquire)
                                                      44
    Send command to the scanner
SCAN.SendCommand                  Send command to the scanner
    key                           Parameters name
    Result                        Parameters value
    Error                         error code and related message
    REQUEST OBJECT
{
         "id": "1",
         "jsonrpc": "2.0",
         "method": "SCAN.SendCommand",
         "params": {
            "device": "Evolis Primacy 2",
            "command": "#GV"
         }
     }
    RESPONSE OBJECT
     {
         "id": "1",
         "jsonrpc": "2.0",
         "result": {
            "code": 12,
            "data": "..."
         }
     }
}
                                                     45
            Example with a session:
    REQUEST OBJECT
    {
            "id": "1",
            "jsonrpc": "2.0",
            "method": "SCAN.SendCommand",
            "params": {
               "session": "SCAN1",
               "command": "#GV"
            }
        }
    RESPONSE OBJECT
        {
            "id": "1",
            "jsonrpc": "2.0",
            "result": {
               "code": 12,
               "data": "..."
            }
        }
}
            This request allows to send a direct command to the scanner (work with or without
            a session). Returns will be base 64 encoded in case it contains binary data (with a
            "base64:" prefix). Regarding specific commands list, additional information only
            upon request.
                                                    46
APPENDIX
ESPF SERVER CONFIGURATION
The ESPF server can be configured using its configuration file. The server's settings
are considered upon server boot.
This file hosts general server parameters, as well as parameters specific to services
hosted on the server. The following tables describe a selection of such parameters.
For Primacy 2, and Evolis Premium Suite 2 please refer to this section.
                                         47
Configuration file available settings:
This section gathers the available settings for the Evolis Services Provider
Framework for Evolis Suite (Evolis Premium Suite, Edikio Printer Suite, Badgy
Printer Suite) up to version 6.
For Evolis Premium Suite release above 7.0.0.0 ( Evolis Premium Suite 2), please
refer to this section
 Logs settings
 Name                                        Value
 ESPFService.log                             The true value enables the debugging logs
                                             (default).
                                             FALSE value disables it.
 ESPFService.loglevel                        Verbose level :
                                             1     Fatal
                                             2     Critical
                                             3     Error (default)
                                             4     Warning
                                             5     Notice
                                             6     Information
                                             7     Debug
                                      48
ESPFServerManager.disablepipeserver      TRUE value disables the Named pipe
                                         transport layer upon server boot.
                                         FALSE value enables it (default)
                                  49
RETURNED ERRORS
Error returned by the server has different states described in the below matrix,
errors are distributed by service and a general category "All services".
All services
 Code                      -32700
 Message                   (E)Parse error
 Description               Invalid JSON was received by the server. An error occurred on
                           the server while parsing the JSON text
 Code                      -32600
 Message                   (E) Invalid Request
 Description               The JSON sent is not a valid Request object
 Code                      -32601
 Message                   (E) Method not found
 Description               The method does not exist / is not available
 Code                      -32602
 Message                   (E) Invalid params
 Description               Invalid method parameter(s)
 Code                      -32603
 Message                   (E) Internal error
 Description               Internal JSON-RPC Error
 Code                      -32000
 Message                   (E) Service not found
 Description               The service does not exist / is not available
CMD service
 Code                      1200
 Message (E)               Get status error
 Description               Get status error
 Code                      1201
 Message                   (E) Send command error
 Description               Send command error
 Code                      1202
 Message                   (E) Reset communication error
 Description               Reset communication error
 Code                      1300
 Message                   (W) Session already reserved
 Description               The communication session is already reserved
                                       50
Code            1301
Message         (W) Timeout
Description     The send command timeouts
Code            1302
Message         (W) Device not supervised
Description     The target device is not supervised
Code            1303
Message         (W) No Status
PRINT service
Code            1600
Message (E)     Print error
Description     Print Error
Code            1700
Message (W)     Printing session already in progress for the device
Description     The device has already a printing session in progress
Code            1701
Message (W)     Invalid printing session.
Description     The session id sent is not a valid printing session id
Code            1702
Message         (W) Cannot perform action : action already in progress
Description     Cannot perform action: action already in progress
Code            1703
Message         (W) Cannot perform action : setting or bitmap missing
Description     Cannot perform action: setting or bitmap missing
Code            1704
Message         (W) Cannot perform action : processing error
Description     Cannot perform action: processing error
Code            1705
Message         (W) Cannot perform action : job canceled
Description     Cannot perform action: job canceled
                              51
SETTING service
Code              1400
Message           (E) Get error
Description       Get Error
Code              1401
Message           (E) Set error
Description       Set Error
Code              1402
Message           (E) Import error
Description       import Error
Code              1403
Message           (E) Export error
Description       Export Error
Code              1500
Message           (W) Invalid printing session.
Description       The session id sent is not a valid printing session id
Code              1501
Message           (W) Cannot perform action : action already in progress
Description       Cannot perform action: action already in progress
Code              1502
Message           (W) Cannot perform action : import not done
Description       (W) Cannot perform action : import not done
SUPERVISION service
Code              1502
Message           (W) Cannot perform action : import not done
Description       (W) Cannot perform action : import not done
Code              1000
Message           (E) Device supervision/un-supervision error
Description       The device cannot be supervised/un-supervised
Code              1001
Message           (E) Set event action error
Description       Set event action error
                                  52
Code              1100
Message           (W) Device not found
Description       The device cannot be found
Code              1101
Message           (W) Device already supervised
Description       The device is already supervised
Code              1102
Message           (W) Device already un-supervised
Description       The device is already un-supervised
Code              1103
Message           (W) No event waiting for an action
Description       There is no event waiting for an action
Code              1104
Message           (W) Event action to set not found
Description       The event action to set does not exist / is not available
Code              1105
Message           (W) Different event waiting for an action
Description       The event waiting for an action is different
ADD-ON service
Code              1800
Message           (E) Launch error
Description       Launch error
ESPF service
Code              2000
Message           (E) Get parameter error
Description       Get parameter error
Code              2001
Message           (E) Set parameter error
Description       Set parameter error
Code              2100
Message           (W) The parameter key is invalid
Description       The parameter key is invalid
SCANNER service
Code              1900
Message           (E) No scanner in the printer
Description       No scanner in the printer
                              53
Code          1901
Message       (E) Scanner already in use by someone else
Description   Scanner already in use
Code          1902
Message       (E) Given session is invalid
Description   Session ID in the request is not valid
Code          1903
Message       (E) Invalid option value
Description   Issue during the scan
Code          1904
Message       (E) Invalid images value
Description   Images value is not in the right formatting or value is wrong
Code          1905
Message       (E) Error while scanning card
Description   An unexpected error occurred while scanning the card
                          54
PRINTERS' STATES
Major state
 Designation      Description
 OFF              Unable to communicate
 ERROR            Printer error (requests a human intervention)
 READY            Printer Ready
 WARNING          Next printing unavailable (requests a human intervention)
Minor state
For Evolis Premium Suite above 7.0.0.0 ( = Evolis Premium Suite 2), some status
changes in the answer of the request :
                                        55
ERR_MAGNETIC_DATA        Magnetic encoding failed              ERROR
                         Invalid data format.
ERR_MECHANICAL           Mechanical error                      ERROR
                         A mechanical error has occurred.
ERR_READ_MAGNETIC        Magnetic encoding failed              ERROR
                         Magnetic track reading failed.
ERR_REJECT_BOX_FULL      Reject Box Full                       ERROR
                         Please remove all the cards from
                         the reject hopper to resume
                         printing.
ERR_RIBBON_ERROR         Ribbon problem                        ERROR
                         The ribbon is cut or stuck to the
                         card.
ERR_WRITE_MAGNETIC       Magnetic encoding failed              ERROR
                         Read-after-Write failure.
FEEDER_EMPTY             Card feed problem                     ERROR
(ERR_FEEDER_ERROR)       Please check cards, position in the
                         card      feeder     and      gauge
                         adjustment.
INF_WRONG_ZONE_EXPIRED   Ribbon not valid                      ERROR
                         Compatibility problem between
                         ribbon and printouts credit limit
                         reached. Please contact your
                         reseller.
RIBBON_ENDED (ERR)       Ribbon end                            ERROR
                         Ribbon end, please replace by a
                         new one.
LAMINATE_END (ERR)       Film end                              ERROR
                         Film end. Please replace the film.
ERR_LAMINATE             Film problem                          ERROR
                         Film problem. The film is cut or
                         stuck to the card.
ERR_LAMI_MECHANICAL      Mechanical error                      ERROR
                         A mechanical error has occurred in
                         the lamination module.
ERR_LAMI_TEMPERATURE     Temperature error                     ERROR
                         The        lamination       module
                         encountered a temperature error.
ERR_LAMI_COVER_OPEN      Door open during lamination           ERROR
                         The lamination module door got
                         opened during the lamination
                         process. Please close it and retry.
INF_CLEANING             Regular cleaning required             READY
                         Printer cleaning required.
                         (this state is reported only when
                         the printing starts, every 50 cards
                         approximatively)
INF_CLEANING             Insert your adhesive cleaning card    READY
(INF_CLEAN_2ND_PASS)     Please insert your sticky cleaning
                         card. 'Cancel' if you want to
                         proceed with printing.
                         (this state is reported only when
                         the printing starts, every 50 cards
                         approximatively)
INF_CLEANING_RUNNING     Cleaning in progress                  READY
                                    56
INF_LAMI_CLEANING_RUNNING    Lamination module cleaning in         READY
                             progress
INF_LAMI_UPDATING_FIRMWARE   Lamination     module   firmware      READY
                             update in progress
INF_SLEEP_MODE               Printer in Standby mode               READY
                                        57
                             Please remove all the printed cards
                             from the output hopper to resume
                             printing.
DEF_NO_RIBBON                No ribbon                             WARNING
                             Replace the ribbon.
DEF_PRINTER_LOCKED           Communication with the printer is     WARNING
                             locked
                             Contact your dealer
DEF_UNSUPPORTED_RIBBON       Ribbon incompatible with this         WARNING
                             printer model
                             The ribbon inserted cannot work
                             with this printer model.
DEF_WAIT_CARD                Waiting for a card insertion          WARNING
                             Please insert your card manually.
ERR_BAD_RIBBON               Ribbon installed is incompatible      WARNING
                             with settings
                             The ribbon installed does not
                             correspond to the manually
                             defined settings. Printing cannot
                             take place.
                             (this state is reported only when
                             the printing starts)
FEEDER_EMPTY (DEF)           Card feed problem                     WARNING
                             Please check cards, position in the
                             card      feeder     and     gauge
                             adjustment.
INF_CLEANING_ADVANCED        Advanced cleaning required            WARNING
                             Printer advanced cleaning is
                             required.
                             (this state is reported only when
                             the printing starts, every 50 cards
                             approximatively)
INF_CLEANING_LAST_OUTWARRA   Regular cleaning mandatory            WARNING
NTY                          Click on 'Cancel' and proceed with
                             cleaning immediately. Would you
                             continue, this will void the print
                             head warranty.
                             (this state is reported only when
                             the printing starts)
INF_CLEANING_REQUIRED        Regular cleaning mandatory - No       WARNING
                             card issuance allowed by your
                             Administrator
                             Click on 'Cancel' and proceed with
                             cleaning immediately.
                             (this state is reported only when
                             the printing starts)
INF_UNKNOWN_RIBBON (1)       Ribbon not identified                 WARNING
                             Ribbon identification impossible.
                             Please proceed with Manual
                             settings.
INF_UNKNOWN_RIBBON (2)       Ribbon not identified                 WARNING
                             Ribbon identification impossible.
                             Please proceed with Manual
                             settings.
INF_WRONG_ZONE_ALERT         Ribbon not valid                      WARNING
                             Compatibility problem between
                             ribbon and printer. Less than 50
                             printouts     remaining.     Please
                             contact your reseller.
                                        58
                           (this state is reported only when
                           the printing starts, every 10 cards
                           approximatively)
INF_WRONG_ZONE_RIBBON      Ribbon not valid                      WARNING
                           Compatibility problem between
                           ribbon and printer. Please contact
                           your reseller.
                           (this state is reported only when
                           the printing starts, every 25 cards
                           approximatively)
RIBBON_ENDED (DEF)         Ribbon end                            WARNING
                           Ribbon end, please replace by a
                           new one.
DEF_NO_LAMINATE            No film                               WARNING
                           No film in lamination module.
                           Please replace the film.
INF_LAMINATE_UNKNOWN       Film not identified                   WARNING
                           Unknown film. Please contact your
                           reseller.
INF_LAMINATE_LOW           Film close to the end                 WARNING
                           Film close to the end. Please
                           arrange for replacement.
                           (this state is reported only when
                           the printing starts, every 10 cards
                           approximatively, and changes
                           automatically after 10s)
LAMINATE_END (DEF)         Film end                              WARNING
                           Film end. Please replace the film.
DEF_LAMINATE_UNSUPPORTED   Incompatible film                     WARNING
                           Film incompatible with lamination
                           module. Please contact your
                           reseller.
DEF_LAMI_COVER_OPEN        Door open                             WARNING
                           Lamination module door open.
                           Close the lamination module door.
INF_LAMI_TEMP_NOT_READY    Adjusting temperature                 WARNING
                           Lamination module temperature
                           adjustment in progress. Please
                           wait…
DEF_LAMI_HOPPER_FULL       Output jammed                         WARNING
                           The lamination output is jammed.
                           Please remove the card(s) and
                           retry.
                                      59
Disclaimer
While Evolis makes every effort to deliver high quality products, we do not guarantee that our
products are free from defects. Our SDK, samples and demo software, any content or
documentation delivered in this package (Evolis SDK) is provided "as is". The use of it is at your
own risk.
No oral or written communication from or information provided by Evolis shall create awarranty.
Under no circumstances shall Evolis be liable for direct, indirect, special, incidental, or
consequential damages resulting from the use, misuse, or inability to use this Software
Development Kit (named Evolis SDK), even if Evolis has been advised of the possibility of such
damages