Propósito:
Permite cargar saldo en una cuenta. Este comando requiere enviar la APIKEY (contraseña API) que tiene configurado el servidor destino, esta contraseña solo es conocida por el dueño de cada establecimiento comercial, por defecto no viene configurada, y por lo tanto esta funcionalidad viene desactivada.
Como esta contraseña debe ser absolutamente secreta, debe ser almacenada y solo usada en el lado servidor (por ejemplo, en el PHP server), y nunca transmitida al lado cliente (browser, app, etc.).
Cada dueño de establecimiento comercial es libre de cambiar la APIKEY o quitarla y anular la funcionalidad, cuantas veces lo requiera. En la siguiente imagen se muestra el formulario de configuración donde cambiar la APIKEY en el Server de los establecimientos, solo pueden escribir una nueva APIKEY y presionar ENTER, un beep hará de confirmación, este formulario no permite ver ni obtener APIKEY anteriormente registradas.
ENGLISH:
Purpose:
It allow to deposit money into the account. This command requires to send the API password for the target server, which only will be known by the administrator of the target establishment, So this API password must be hold/use only in secure PHP side, not browser client side. On the target server the API password can be set or changed using the administrator account and enter in the following screen (see image), just write it down, and press ENTER, a beep will sound as confirmation. The form don’t allow to get the APIKEY.
Si el servidor objetivo pertenece a un CLAN (conjunto de establecimientos, cada uno con su servidor, cuyo servers se sincronizan en tiempo real Ej: Franquicias), al agregar dinero se pedirá una resincronización de la cuenta, y luego, la carga impactará el CLAN, si la cuenta está siendo usada en otro establecimiento del clan, la misma estará bloqueada y se devolverá un error, ya que un solo servidor puede hacer uso de la cuenta al mismo tiempo.
Las transacciones realizadas con esta función serán registradas bajo la cuenta contable “APIWEB” en el libro contable. Asegúrese de que la cuenta contable código rápido “APIWEB” exista para que se visibilice en el balance de ingresos y egresos, y tenga las propiedades de “Imputable como ingresos” e “Imputable como egresos” para que las operaciones aparezcan en el balance diario, ya que estas cargas o devoluciones de cargas no corresponden a lo actuado por ninguna caja de cajero/empleado, sino que impactan directo en la contabilidad.
En el Historial de transacciones que ve el cliente final en su cuenta figurará como “Carga desde API_WEB”.
Esta función está pensada para integrar y automatizar cargas por medios de pago electrónicos, agregando saldo a la cuenta del cliente final. Esta función no es la funcionalidad del empleado / cajero, para desarrollar una consola del cajero existen otros CommandClass que corresponden a la carga de cuentas realizadas por un cajero.
Esta función también requiere la SessionToken de usuario final que va a cargarse su cuenta, por lo tanto está pensado para que un usuario final, se identifique, y luego cargue su cuenta usando una plataforma de pagos.
Al tener que identificarse primero, ya sabemos dos cosas, la primera es que el establecimiento está ABIERTO, es decir, no todos los establecimientos están activos 24/7, muchos solo atienden en horario comercial, y apagan sus servidores, al poder loguearse se garantiza de que el servidor destino está prendido, y que hay comunicación con dicho servidor. Para loguearse use CommandClass _LOGIN, y para sostener el SessionToken _RELOGIN (una vez cada 20 minutos estará bien). Al identificarse, también se estará validando que la cuenta existe y no está baneada/bloqueada. Para concluir, usar _LOGOUT.
Todas las transacciones son en moneda local principal.
CommandClasses relacionados:
CommandClass GETMEMBERS. <—- Devuelve el listado de establecimientos.
CommandClass _CREATEACCOUNT. <—- Crea una cuenta en un establecimiento.
CommandClass _LOGIN. <—- Proceso de identificación del usuario.
CommandClass _RELOGIN <—- Evita que el SessionToken se caiga por inactividad.
CommandClass _LOGOUT <—- Cierra sesión.
CommandClass _GETUSERDATA1.
CommandClass _GETUSERDATA2. <— Entre otras cosas devuelve el historial de transacciones.
CommandClass _GETUSERDATA3.
ENGLISH
If the target server is in clan, it will impact the clan, as it will order an resynchronization prior to add the cash, if the account is in use in other server, it can deny the access to the account, an error will pop.
Money added with this function, the transaction is registered in accountant books as “APIWEB” account name, transaction from that, to the targeted user account.
In the history of the targeted account will be shown as “Carga desde API_WEB“.
This function is meant to process automatic electronic payments services, and this way to add credit in the end user account. IT IS NOT for a cashier/employee to add credit remotely, for cashier side scripts there is or will be others functions.
And ofcourse, SessionToken is obtained from _LOGIN and maintained with _RELOGIN API calls (one per 20 min is fine). Which imply, the enduser is already identified related to a Master Control Account. Se also _LOGOUT. This allow to create apps, where the end user login, then charge its account with external payments methods, and check its balance, his balance history, and logout.
All transaction are in LOCAL MAIN CURRENCY.
For related interesting API calls see:
CommandClass _CREATEACCOUNT.
CommandClass _LOGIN. <—- User identification process.
CommandClass _RELOGIN <—- Avoids to drop the session token on inactivity.
CommandClass _LOGOUT <—- Close session.
CommandClass _GETUSERDATA1.
CommandClass _GETUSERDATA2. <— it returns the transactions history aswell.
CommandClass _GETUSERDATA3.
Minimum version for the target server required: v17.0.50.
Input parameters:
- CommandClass = _ADDCASH
- Param1 = target CyberName.
- Param2 = Session Token.
- Param3 = API Password.
- Param4 = Money ammount.
Output:
[{“ResponseClass”: “ERROR”, “Param1”: “message”, … }]
[{“ResponseClass”: “OK”,”Param1″:”New total ammount”}]
Example of usage:
Como esta función debe ser ejecutada en el lado servidor para proteger la APIKEY, presento un ejemplo escrito en PHP.
As this function must be executed in the server side, I present an example written in PHP.
.
<?php
/* For the purpose of testing this PHP we will call it using the URL with parameters. But any serious website must do it with the POST method. */
$UserNameComplete = $_GET['UserName'];
$CyberName = $_GET['CyberName'];
$UserSessionToken = $_GET['SessionToken'];
$Ammount = $_GET['Money'];
/*
$UserNameComplete = $_POST['UserName'];
$CyberName = $_POST['CyberName'];
$UserSessionToken = $_POST['SessionToken'];
$Ammount = $_POST['Money'];
*/
/* the php side can hold the api password safely hardcoded or in SQL, as the website will belong to the administrator. */
$APISecretPassword = 'el_PASSWORD_API_que_le_pongas_a_tu_server';
$WebData = json_decode (curl('https://wingamer.ar/ApiMasterControl/Comm.php?CommandClass=_ADDCASH&Param1=' . urlencode ($CyberName) . '&Param2=' . urlencode ($UserSessionToken) . '&Param3=' . urlencode($APISecretPassword) . '&Param4=' . $Ammount));
if ($WebData['0']->ResponseClass === 'OK')
{
// Ok, the deposit is completed.
ECHO '<p>Your new total balance is:' . $WebData['0']->Param1 . '</p>';
}
else
{
/* As a general rule, everything can go wrong, SQL here in a table of failed transactions or reverse the payment at the payment service. */
// It present to the user the error.
ECHO '<p>' . $WebData['0']->Param1 . '</p>';
}
die ('');
exit (0);
function curl($url)
{
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HEADER, "FlulpyCrea\'s platform for ESports games");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($ch);
curl_close($ch);
return $res;
}
?>