switchUser

This is an authentication function. When called, it provides you a "session key" that you can use in subsequent API calls as a token of authentication.

switchUser allows you to log in with user PIN (no user name / password needed); however, this API call can only be used for "user switching". It means that for calling switchUser, you need to already have a valid session key (or one that has just expired, no more than 2 hours old).

For a more general authentication function (that you should be using in most cases!), see verifyUser. It requires a user name and password. In verifyUser documentation, you will also find a general introduction to API authentication and sessions.

Successful user switch will give you a NEW session key, with the user rights of the PIN holder.

If authentication does not succeed, switchUser returns error 1051 or 1052. If the supplied session key is invalid, API returns error 1054 or 1055. If the session key is too old, API returns error 1056. In case of a success, API returns the information described below.

Input parameters

Parameter name	Description	Possible value	Required
sessionKey	A valid session key (or one that has expired in the last 2 hours)	string	yes
cardCode	New user PIN	string	yes
sessionLength	Desired session length in seconds (1...86400 sec). If you omit the parameter, or specify 0 or a negative value, a session with a default length of 3600 will be created. If you specify a value larger than 86400 seconds, session length will be set to 86400 seconds.	integer
doNotGenerateIdentityToken	If set to 1, then API will NOT return parameter "identityToken".	Integer (1 or 0)

Response

Field name

Type

Description

userID

integer

ID of the user account (who was just authenticated with PIN)

userName

string

User name

employeeID

integer

ID of the company employee that has the abovementioned user account

employeeName

string

groupID

integer

ID of the user group where the user belongs

groupName

string

name of the user group

ipAddress

string

IP address of the API client.

sessionKey

string

A new session identifier, to be used for subsequent API calls.

sessionLength

integer

time after which the session key expires (in seconds).

loginUrl

string

berlinPOSVersion

string

Application-specific field for Erply's Berlin POS. Indicates the version number (typically an integer) of the live / production POS version that is appropriate for this customer — or the version that has specifically been configured for this customer.

This field does not mean that the customer is definitely using Berlin POS. The customer may be using other POS products or not using a POS at all.

Also, API does not currently provide a POS version number for preproduction / staging / testing.

berlinPOSAssetsURL

string

Application-specific field for Erply's Berlin POS. Indicates the URL from where POS can load its static assets.

The URL does not include and does not depend on POS version number. POS should append version number to the URL, or perform some other transformation if needed.

epsiURL

string

Application-specific field for Erply's Berlin POS. Indicates the location of the JNLP file for Erply Point Of Sale Integrator (EPSI), which provides support for various POS hardware.

cayanGatewayURLs

array

Application-specific field for Berlin POS - returned only for Berlin POS.

List of Cayan (Merchant Warehouse) payment gateway URLs for this particular account. This only specifies the most appropriate service endpoints for the account to use; it does not indicate that the account is actually using Cayan payment integration.

This array may contain 0 or more records. If Cayan support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
target	String	Service hostname
port	Integer	Service port
weight	Integer (0..65535)	For load balancing. See internal documentation.
priority	Integer (0..65535)	Priority of this host. See internal documentation.

avalaraGatewayURLs

array

Application-specific field for Berlin POS - returned only for Berlin POS.

URLs of gateways to the Avalara tax calculation service. This only specifies the most appropriate service endpoints to use, if needed, and does not indicate that the account is actually using Avalara integration.

This array may contain 0 or more records. If Avalara support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
target	String	Service hostname
port	Integer	Service port
weight	Integer (0..65535)	For load balancing. See internal documentation.
priority	Integer (0..65535)	Priority of this host. See internal documentation.

pusherAuthenticationURLs

array

Application-specific field for Berlin POS - returned only for Berlin POS.

URLs of gateways to the Pusher messaging service, for this particular account.

This array may contain 0 or more records. If Pusher support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
target	String	Service hostname
port	Integer	Service port
weight	Integer (0..65535)	For load balancing. See internal documentation.
priority	Integer (0..65535)	Priority of this host. See internal documentation.

strikeIronGatewayURLs

array

Application-specific field for Berlin POS - returned only for Berlin POS.

URLs of gateways to the StrikeIron (Informatica) tax rate lookup service, for this particular account.

This array may contain 0 or more records. If StrikeIron support has been disabled in this server, the array will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
target	String	Service hostname
port	Integer	Service port
weight	Integer (0..65535)	For load balancing. See internal documentation.
priority	Integer (0..65535)	Priority of this host. See internal documentation.

customerRegistryURLs

array

Information about standalone customer registry service.

This array may contain 0 or more records. If account does not use a standalone customer registry (customers are stored in Erply as usual), this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
url	String	URL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls (eg. "V1/Customer/create") to this URL.
token	Integer	Authentication token for the service. When the customer service reports the token has expired, call verifyUser again to get a new one.
priority	Integer (0..65535)	Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weight	Integer (0..65535)	For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.

couponRegistryURLs

array

Information about standalone coupon registry service.

This array may contain 0 or more records. If account does not use a standalone coupon registry (coupons are stored in Erply as usual), this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
url	String	URL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls to this URL.
token	Integer	Authentication token for the service. When the coupon service reports the token has expired, call verifyUser again to get a new one.
priority	Integer (0..65535)	Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weight	Integer (0..65535)	For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.

transactionRegistryURLs

array

Information about standalone transaction registry service.

This array may contain 0 or more records. If account does not use a standalone transaction registry (transactions are stored in Erply as usual), this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
url	String	URL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls to this URL.
token	Integer	Authentication token for the service. When the transaction service reports the token has expired, call verifyUser again to get a new one.
priority	Integer (0..65535)	Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weight	Integer (0..65535)	For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.

displayAdManagerURLs

array

Information about the service that provides advertisements to the point-of-sale customer display screen. (This information is meant for Berlin POS.)

This array may contain 0 or more records. If account has not been configured to use the advertisement manager, this list will be empty. Otherwise it will contain at least one record.

Each record in the array contains the following fields:

Field name	Type	Description
url	String	URL of the service endpoint (with "https://" protocol in the beginning and "/" in the end). Append the names of API calls to this URL.
token	Integer	Authentication token for the service.
priority	Integer (0..65535)	Priority of this host. A client must attempt to contact the target host with the lowest-numbered priority it can reach. Target hosts with the same priority should be tried in pseudorandom order.
weight	Integer (0..65535)	For load balancing. When selecting a target host among those that have the same priority, the chance of trying this one first should be proportional to its weight. Larger weights SHOULD be given a proportionately higher probability of being selected.

epsiDownloadURLs

array

Provides URLs with downloadable packages for EPSI (Erply point of sale integrator) installation. Provides a record per each operating system with installation link.

Each record in the array contains the following fields:

Field name	Type	Description
operatingSystem	String	Possible values - "Windows", "macOS" and "Linux"
url	String	Installation link

identityToken

string

Provides Identity API Json Web Token

token

string

Replaces identityToken. Provides an Erply generated JWT token.

Can be used with integrations that require the JWT for authentication. This can also be retrieved with getJwtToken with a session key without username and password.