Introducción
Esto describe los recursos públicos que componen la versión oficial de API Juice v11.5.0. Si tiene algún problema o solicitud, comuníquese con support@utiliflex.com. En este documento, el dominio api.utiliflex.com se utiliza únicamente como un marcador de posición de ejemplo y diferirá de un sistema a otro..
Información básica sobre JuiceAPI
Esta sección describe los conceptos básicos para trabajar con JuiceAPI, en lo que respecta a autorizar la solicitud de una versión de API específica, si está disponible, el esquema de encabezado y cuerpo general devuelto por la API, así como detalles sobre los códigos de error que la API puede devolver.
Información general sobre la Integración
JuiceAPI es una interfaz HTTP RESTful que, dependiendo del punto final, transfiere datos a través de parámetros URI y cadenas de consulta, o en un cuerpo POST con JSON o CSV. La salida de cada llamada será un cuerpo vacío, en tales casos, el código de estado HTTP debe verificarse en busca de éxito o falla o será un cuerpo JSON siguiendo nuestro formato de estructura de retorno genérico definido más adelante en esta sección.
Esquema del encabezado HTTP
curl https://api.utiliflex.com/auth-test
HTTP/1.1 200 OK
Date: Fri, 12 Oct 2012 23:33:14 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive Status: 200 OK
X-Juice-Media-Type: juice.v1
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff
All API access is over HTTPS, and accessed from the https://api.utiliflex.com/.
For all requests the API will return the Content-Type, Status, X-Juice-Media-Type,
Content-Length, and Cache-Control headers.
The body of the response is in JSON with all timestamps, with the exception of
the header, are in RFC3339 format: YYYY-MM-DDTHH:MM:SSZHH:MM
Parámetros
curl "https:api.utiliflex.com/juicecards/verify?portal=foo"
Many API methods take additional parameters via the URI. For GET requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameters.
In this example, the verify value is provided for the :method parameters in the path while :portal is passed in the query string. For POST, PATCH, PUT, and DELETE requests, parameters not included in the URL should be encoded as JSON with a Content-Type of ‘application/json’.
Estructura de retorno genérica
All data returned from the API is wrapped in the same JSON envelope which consists of three fields.
| Field | Type | Description |
|---|---|---|
| error | int | El código de error, si es que hay alguno, para la solicitud. Si no hay error este campo será 0. Ver la sección de Client Errors para ver una lista de posibles códigos de error |
| error_message | string | Mensaje de error en texto plano que describe el error. Este campo se omite si no hubo ningún error al procesar la solicitud. |
| data | object | Los datos de retorno específicos del método llamado, vea el documento correspondiente al método llamado para conocer los detalles de lo que puede haber en este campo. Este campo puede ser omitido si hubo un error. |
Comprobación de estado (health check)
curl --request GET --url api.utiliflex.com:8080/health-check
{
"error":0,
"data":{
"alive":true,
"server_time":"2018-07-20T14:33:31.850901852-04:00"
}
}
El punto final de comprobación de estado (health check) no requiere autenticación, y puede utilizarse para comprobar el estado actual de la API. Esto también hace que la API pruebe su conexión con la Base de Datos. Si todo se comprueba, este endpoint vuelve con los valores alive: true y devuelve la hora actual del sistema.
Manejo de la autenticación a la API
Hay dos formas de autentificar con JuiceAPI, ya sea con la Autenticación Básica o usando un Token API. En el resto del presente documento se supone que todas las llamadas utilizan uno de estos métodos de autenticación, a menos que se especifique lo contrario. El USERNAME y PASSWORD ion las mismas credenciales que se utilizan para autenticar a la aplicación principal de Juice, el API TOKEN es el token de la API del usuario del sistema que fue generado por el sistema.
Verificación de autenticación (Autenticación básica)
Para autorizar, use este código:
curl --request GET \
--user USERNAME:PASSWORD \
--url api.utiliflex.com:8080/auth-test
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"status":"OK"
}
}
Asegúrate de reemplazar
USERNAMEyPASSWORDcon tu nombre de usuario y contraseña.
La autenticación básica envía el nombre de usuario y la contraseña como una cadena codificada en Base64 en las cabeceras del HTTP, y generalmente es soportada por la mayoría, si no todas las herramientas y marcos de trabajo (frameworks) de forma nativa.
Solicitud HTTP
Authorization: Basic dGVzdDoxMjPCow==
GET /auth-test
Comprobación de autenticación (OAuth)
curl --request GET \
--url 'api.utiliflex.com:8080/auth-test' \
--header 'Authorization: token jsmith:56d2bf16-9881-4e5d-bbeb-c79a72225a5b'
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"status":"OK"
}
}
Utilizando un token de la API, el nombre de usuario y el token de la API deben estar en el campo de cabecera de autorización en forma de token USERNAME:TOKEN para que el sistema reconozca el token e intente validarlo.
Solicitud HTTP
Authorization token USERNAME:TOKEN
GET /auth-test
Funciones de medición
Obtención de una lista de tipos de medidores compatibles
curl --request GET \
--url 'api.utiliflex.com:8080/meters/com-types/get-supported'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/com-types/get-supported');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"AMR":{
"com":"AMR"
},
"ByBot":{
"com":"ByBot",
"source":[
{
"name":"bybot",
"pull_reads":true
}
]
},
"DLMS":{
"com":"DLMS",
"source":[
{
"name":"microstar",
"pull_reads":false
}
]
},
"MAS":{
"com":"MAS",
"source":[
{
"name":"mas",
"pull_reads":true
}
]
},
"MultiSpeak":{
"com":"MultiSpeak",
"source":[
{
"name":"multispeak",
"pull_reads":true
}
]
},
"NES":{
"com":"NES"
}
}
}
JuiceAPI admite la consulta de una lista de tipos de comunicación de medidores compatibles con Juice. El valor del campo com es el nombre utilizado por Juice para identificar el tipo de comunicación específico usado por el/los medidor(es), en los casos en que este método de comunicación sea un estándar aceptado por la industria, el tipo “com” será el nombre de ese estándar, por ejemplo, MultiSpeak, el tipo “com” también puede ser nombrado específicamente para un fabricante de medidores, por ejemplo, NightHawk, para un tipo de comunicación sólo utilizado para medidores por esa compañía, o el tipo “com” puede ser específico de integración para poder trabajar con un sistema personalizado de cabecera/MDM.
El campo source → name es el nombre utilizado internamente por la API al referirse a los datos entrantes, como las lecturas de medidores entrantes, para denotar la fuente de los datos.
El campo source → pull_reads se utiliza internamente para determinar si Juice necesita activar o no las solicitudes de lectura por lotes.
Solicitud HTTP
GET /meters/com-types/get-supported
Obtención de la lista de medidores
curl --requst GET \
--url 'api.utiliflex.com:8080/meters/get-meters?portal=example&com=MultiSpeak'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/get-meters?portal=example&com=MultiSpeak');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"meters":[
{
"serial_number":"1234abcde",
"com_type":"MultiSpeak"
},
{
"serial_number":"AMI1234",
"com_type":"MultiSpeak"
}
]
}
}
El JuiceAPI soporta la obtención de una lista de todos los medidores actualmente en el sistema para un portal específico, y opcionalmente filtrados por un tipo de comunicación específico. Este punto final no requiere autenticación para su uso.
Solicitud HTTP
GET /meters/get-meters?portal=<portal>&com=<com>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal para consultar los medidores | Yes |
| com | Un tipo de comunicación específico para devolver los valores | No |
Obtener los detalles del medidor
curl --requst GET \
--url 'api.utiliflex.com:8080/meters/get-meter?portal=example&serialnumber=1234abcde'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/get-meter?portal=example&serialnumber=1234abcde');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error": 0,
"data": {
"portal": "test",
"loc_id": "L03281",
"account": "03280",
"id": "1234abcde",
"serial_number": "1234abcde",
"name": "",
"com": "MultiSpeak",
"tariff": "SBT",
"subtariff": "PrePaid",
"type_id": "",
"status_type_id": "",
"service_status": 0,
"sgc": "",
"kva_demand_rating": 0,
"vendable": 1,
"meter_location": "",
"misc_data": "",
"meter_state": "DISCONNECTING",
"installer": "",
"units": "kWh",
"factor": 1,
"phases": 1,
"ststi": "",
"sts_key_rev": "",
"sts_exp_num": 255,
"sts_base_date": 0,
"sts_version": 0,
"disco_profile": "PendingAny",
"breaker": "",
"comments": "",
"created": "2017-10-19T13:46:40-04:00",
"last_mod": "2019-01-29T13:09:21-05:00",
"type": "57",
"form_factor": "",
"wiring": "-",
"current_per_phase": 0,
"voltage_per_phase": 0,
"frequency": 0,
"ami_wallet": "units"
}
}
Este punto final permite obtener detalles básicos del medidor para un determinado medidor, incluyendo el ID de la ubicación y la cuenta del cliente a la que puede o no estar conectado.
Solicitud HTTP
GET /meters/get-meter?portal=<portal>&serialnumber=<serialnumber>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal para consultar los medidores | Yes |
| serialnumber | El número de serie del medidor para obtener los detalles | Yes |
Respuesta de devolución de llamada
curl --request POST \
--url 'api.utiliflex.com:8080/meters/ami-control/callback?portal=examlpe&source=multispeak'
--data '{
"uuid": "6bce3e16-b6f9-418e-9751-44888850bbdf",
"command": "READ",
"result": "success",
"error_code": 0,
"error_msg": "",
"data": [{
"serial_number": "1234abcde",
"reading": 100.24,
"read_timestamp": "2019-05-08T22:50:10Z",
"meter_state": "connected"
}]
}'
<?php
$data = '{
"uuid": "6bce3e16-b6f9-418e-9751-44888850bbdf",
"command": "READ",
"result": "success",
"error_code": 0,
"error_msg": "",
"data": [{
"serial_number": "1234abcde",
"reading": 100.24,
"read_timestamp": "2019-05-08T22:50:10Z",
"meter_state": "connected"
}]
}';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/ami-control/callback?portal=examlpe&source=multispeak');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
Cuando Juice hace una solicitud a la cabecera AMI/AMR/MDM y los resultados finales se publican en una llamada REST separada, los resultados finales deben ser configurados en la llamada de retorno o a una URL de devolución de llamada alternativa es proporcionada por Utiliflex que toma el cuerpo POST del sistema de cabecera / MDM de terceros y traduce los datos para enviar a este punto final..
Esta sección sólo es relevante si no se utiliza una URL de devolución de llamada alternativa, ya que ese punto final alternativo se encargará de procesar los datos del formato enviado por el sistema de cabecera/MDM y lo convertirá al siguiente formato y enviará los datos a la API automáticamente.
Solicitud HTTP
POST /meters/ami-control/callback?portal=<portal>&source=<source>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal para el medidor o medidores a los que se hace referencia en la respuesta | Yes |
| source | Un identificador único que especifica la fuente de la información que regresa. La fuente debe estar presente en la lista de tipos de comunicación soportados | Yes |
Cuerpo (body)
| Name | Type | Description | Required |
|---|---|---|---|
| uuid | string | El identificador único de la solicitud que fue generado por Juice | Yes |
| command | string | El comando que se envió en la solicitud original | Yes |
| result | string | Si el resultado de la solicitud fue success o fail |
No |
| error_code | int | El código de error del sistema de cabecera (si lo hay) | No |
| error_msg | string | El mensaje de error del sistema de cabecera (si lo hay) | No |
| data | array of objects | Información adicional sobre la solicitud (véase la definición más abajo) | No |
Objeto de datos
| Name | Type | Description | Required |
|---|---|---|---|
| serial_number | string | El número de serie del medidor | Yes |
| reading | float64 | La lectura actual del medidor en Wh | No |
| read_timestamp | datetime | La hora en que se tomó la lectura del medidor | No |
| meter_state | string | El estado del relé del medidor según lo informado por el sistema de la cabecera | No |
Trabajar con lecturas de medidor con JuiceAPI
Agregar nuevas lecturas
Ejemplo de datos CSV
metername,serialnumber,deviceid,datetime,multiplier,sumforwardactive,sumreverseactive,sumforwardreactive,sumreversereactive,meterstate
,1234abcde,,2017-11-16T07:00:00Z04:00,1.0,108.8,0,0,0,connected
Datos JSON de ejemplo
[
{
"metername":"",
"serialnumber":"1234abcde",
"deviceid":"",
"datetime":"2017-11-16T07:00:00-04:00",
"multiplier":1.0,
"sumforwardactive":0,
"sumreverseactive":0,
"sumforwardreactive":0,
"sumreversereactive":0,
"meterstate":"connected"
}
]
curl --request POST \
--url 'api.utiliflex.com:8080/meters/reads/insert?source=multispeak&format=CSV' \
--data 'metername,serialnumber,deviceid,datetime,multiplier,sumforwardactive,sumreverseactive,sumforwardreactive,sumreversereactive,meterstate
,1234abcde,,2017-11-16T07:00:00Z04:00,1.0,108.8,0,0,0,connected'
<?php
$data = 'metername,serialnumber,deviceid,datetime,multiplier,sumforwardactive,sumreverseactive,sumforwardreactive,sumreversereactive,meterstate\n';
$data .= ',1234abcde,,2017-11-16T07:00:00Z04:00,1.0,108.8,0,0,0,connected';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, '');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"imported_reads":1
}
}
Para añadir nuevas lecturas de medidores en un escenario de lectura programada, los siguientes datos deben ser publicados en el sistema en formato CSV o JSON .
Esta sección sólo es relevante si no se utiliza un URL alternativo, ya que ese punto final alternativo se encargará de procesar los datos del formato enviado por el sistema de cabecera/MDM y lo convertirá al siguiente formato y enviará los datos a la API automáticamente.
Solicitud HTTP
POST /meters/reads/insert?portal=<portal>&source=<source>&watts=<watts>&volts=<volts>&format=<format>
Parámetros de la consulta
| Parameter | Default | Description | Required |
|---|---|---|---|
| portal | '' | El portal al que pertenece el medidor | No |
| source | '' | La fuente de las lecturas | Yes |
| watts | false | Si el valor de los campos activos en vatios-hora (Wh) se establece como verdadero para el valor a convertir durante la importación | No |
| volts | false | Si el valor de los campos reactivos en voltios-amperios reactivos (var) se establece como verdadero para el valor a convertir durante la importación | No |
| format | '' | Formato del valor del cuerpo, los formatos válidos son CSV y JSON | Yes |
POST Body
| Field | Type | Description |
|---|---|---|
| metername | string | Se proporciona un nombre descriptivo para el medidor, si lo hay. |
| serialnumber | string | El número de serie único del medidor |
| deviceid | string | ID único del medidor / dispositivo com si es diferente del número de serie |
| datetime | string | La fecha y hora efectiva para la lectura del medidor, en formato RFC3339. |
| multiplier | double | Multiplicador especial para el medidor/lectura, por defecto 1.0 |
| sumforwardactive | float | Energía activa positiva, la lectura por defecto es en kilovatios hora (kWh) |
| sumreverseactive | float | Energía activa negativa, por defecto la lectura es en kilovatios hora (kWh) |
| sumforwardreactive | float | Energía reactiva positiva, por defecto la lectura reactiva es en Kilovoltios-amperios reactivos (kvar) |
| sumreversereactive | float | Energía reactiva negativa, por defecto la lectura reactiva es en Kilovoltios-amperios reactivos (kvar) |
| meterstate | string | El estado del relé del medidor en el momento de la lectura si es reportado por el sistema headend/mdm |
Obteniendo lecturas de medidor para un medidor
curl --request GET \
--url 'api.utiliflex.com:8080/meters/reads/get?serialnumber=AMI1234'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/meters/reads/get?serialnumber=AMI1234');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": [
{
"portal": "example",
"account": "03283",
"locid": "L03290",
"serialnumber": "AMI1234",
"datetime": "2019-02-08T12:30:00-05:00",
"multiplier": 1,
"deviceid": "AMI1234",
"source": "multispeak",
"status": "U:67",
"timezoneindex": 11,
"lastmod": "2019-03-08T15:41:28-05:00",
"sumforwardactive": 100000,
"toubucket1wh": 100000
},
{
"portal": "example",
"account": "03283",
"locid": "L03290",
"serialnumber": "AMI1234",
"datetime": "2019-03-08T15:00:00-05:00",
"multiplier": 1,
"deviceid": "AMI1234",
"source": "jsmith",
"status": "U:71",
"timezoneindex": 11,
"lastmod": "2019-03-08T15:42:02-05:00",
"sumforwardactive": 200000,
"usagediff": 100000,
"toubucket1wh": 200000
}
]
}
Este punto final devuelve una lista de todas las lecturas de medidor en Juice para un medidor dado, opcionalmente filtrado para devolver lecturas solo dentro de un rango de fechas dado.
Solicitud HTTP
GET /meters/reads/get?serialnumber=<serialnumber>&from=<from date>&to=<to date>
Parámetros de consulta
| Field | Type | Description | Required |
|---|---|---|---|
| serialnumber | string | El número de serie del medidor para obtener las lecturas del medidor | Yes |
| from | date | La fecha de inicio de las lecturas a buscar, en formato YYYY-MM-DD |
No |
| to | date | Si se usa junto con from establece una fecha final para obtener lecturas, también YYYY-MM-DD |
No |
Importador de archivos planos JuiceAPI
Esta sección describe el trabajo con el importador de archivos planos de JuiceAPI para importar y actualizar diversas informaciones en el sistema. El formato utilizado por el importador de archivos planos es CSV y soporta tanto las terminaciones de línea de Unix como las de DOS .
Sintaxis del archivo
Ejemplo de un archivo con campos entre comillas y sin comillas
field1,field2
normal string,"quoted-field"
Ejemplo de un archivo que tiene comillas dobles dentro de los datos
field1,field2
"the ""word"" is true","a ""quoted-field"""
Ejemplo de un archivo con nuevas líneas y comas dentro de los datos
field1,filed2
"Multi-line
field","comma is ,"
Para obtener más información sobre la sintaxis CSV válida para el archivo, lea RFC 4180.
El formato del archivo es CSV, con terminaciones de línea en Unix or DOS . Los campos pueden contener comas (,) y nuevas líneas (\n) sólo si el campo se cita en el archivo de origen con comillas dobles, los campos también pueden contener comillas dobles sólo si se escapan correctamentenly. El analizador ignora silenciosamente los retornos (\r), utilizados en DOS/Windows y Mac OS 9
y en los formatos de terminación de línea inferior son ignorados silenciosamente por el analizador, lo que significa que si están presentes en el archivo fuente no habrá diferencia al analizar.
Cualquier línea que comience con # será ignorada por el analizador, lo que es útil para añadir comentarios de línea al archivo. Los comentarios de línea no necesitan ajustarse a las reglas de sintaxis del CSV.
Importador de archivos de datos de Trinity
El acto de importar y / o actualizar la información del cliente, la ubicación y el medidor se realiza con el importador de datos de trinity.
Archivo de importación / actualización de ubicación
Ejemplo de archivo de ubicación
locname,locaddr1,locaddr2,loccity,locstate,loczip,loclat,loclong,meterinstalldate,contract,serialnum
1009001,557-2026 Purus St.,,Watertown,TN,07367,,,2018-07-01,unassigned,unassigned
Para importar nueva información de localización en Juice o para actualizar la información de localización existente se utilizan los siguientes campos en el archivo plano:
| Field | Type | Description | Blank | Updatable |
|---|---|---|---|---|
| locname | string | Nombre identificable único para la ubicación, por ejemplo, llave de CIS | No | No |
| locaddr1 | string | Dirección de la ubicación | No | Yes |
| locaddr2 | string | Información adicional sobre la dirección del lugar | Yes | Yes |
| loccity | string | Nombre de la ciudad de la ubicación | No | Yes |
| locstate | string | Nombre del estado de la ubicación | No | Yes |
| loczip | string | Código postal de la ubicación | No | Yes |
| loclat | float | Información sobre la latitud de la ubicación | Yes | Yes |
| loclong | float | Información sobre la longitud de la ubicación | Yes | Yes |
| meterinstalldate | date | Fecha en que se instaló el medidor más reciente, si no hay un medidor en este lugar, pasado o presente, 0000-00-00 para el año-mes-día. |
No | Yes |
| contract | string | ID de cliente para adjuntar a la ubicación | No | Yes |
| serialnum | string | ID del medidor para adjuntar a la ubicación | No | Yes |
Archivo de importación/actualización de medidores
Ejemplo de archivo de medidor
serialnum,deviceid,comtype,tariff,sgc,ti,keyrev,keyexp,basedate,sts_version,maxpower,addactiveread,server,wallet,contract,locname
7084636088,7084636088,STS,SBT,600403,01,1,255,1993,4,,0,primary,currency,unassigned,unassigned
1234abcde,1234abcde,MultiSpeak,SBT,,,,,,,,0,primary,units,unassigned,1009001
Para importar la nueva información del medidor a Juice o para actualizar la información del medidor existente se utilizan los siguientes campos en el archivo plano:
| Field | Type | Description | Blank | Updatable |
|---|---|---|---|---|
| serialnum | string | Número de serie del medidor | No | No |
| deviceid | string | Número de identificación del medidor si es diferente del número de serie | Yes | Yes |
| comtype | string | Tipo de comunicación del medidor, ver Getting List of Supported Meter Com Types | No | Yes |
| tariff | string | Tarifa de Juice para el medidor | Yes | Yes |
| sgc | int | Código del Grupo de Suministro para el medidor si es un medidor STS | Yes | Yes |
| ti | string | Índice arancelario para el medidor si el medidor STS | Yes | Yes |
| keyrev | int | Número de revisión clave si el medidor STS | Yes | Yes |
| keyexp | int | Número de caducidad de la clave STS | Yes | Yes |
| basedate | int | Base date for STS TID rollover (4 digit year) | Yes | Yes |
| sts_version | int | Versión del protocolo STS (STS 4 or STS 6) | Yes | Yes |
| maxpower | int | Ajuste de potencia máxima para el medidor si el medidor STS | Yes | Yes |
| addactiveread | float | Lectura actual en el medidor o en la Cabecera/MDM para importar a Juice. Se añade un cero a la lectura de un nuevo medidor, dejarlo en 0. Dejar en blanco para STS | Yes | Yes |
| server | string | La llave/identificador para el sistema de cabecera a utilizar para este medidor | Yes | Yes |
| wallet | string | El tipo de billetera en Juice que debe usarse para mantener el saldo prepago. Las opciones válidas son: currency Y units |
No | Yes |
| contract | string | Cliente para conectar al medidor | No | Yes |
| locname | string | Ubicación para conectar al medidor | No | Yes |
Archivo de importación / actualización de clientes
Ejemplo de archivo de cliente
contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum
5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,1009001,1234abcde
To import new customer information into Juice or update existing customer information the following fields are used in the flat file:
| Field | Type | Description | Blank | Updatable |
|---|---|---|---|---|
| contract | string | Identificación de la cuenta/contrato del sistema de legado | No | No |
| name | string | Nombre completo del cliente | No | Yes |
| phone1 | string | Número preferido para utilizar en las notificaciones de IVR | No | Yes |
| phone2 | string | Número secundario para utilizar en las notificaciones de IVR | Yes | Yes |
| sms1 | string | Número preferido para las notificaciones por SMS | No | Yes |
| sms2 | string | Número secundario para las notificaciones por SMS | Yes | Yes |
| string | Dirección de correo electrónico a utilizar para las notificaciones por correo electrónico | No | Yes | |
| address1 | string | Dirección para la dirección de facturación del cliente | Yes | Yes |
| address2 | string | Información adicional de la dirección de la calle | Yes | Yes |
| city | string | Nombre de la ciudad para la dirección de facturación del cliente | Yes | Yes |
| state | string | Nombre del estado / provincia para la dirección de facturación del cliente | Yes | Yes |
| postalcode | int | Código postal / postal para la dirección de facturación del cliente | Yes | Yes |
| locname | string | ID de la ubicación en Juice para adjuntar al cliente | No | Yes |
| serialnum | string | ID del medidor en Juice para adjuntar al cliente | No | Yes |
Añadiendo nuevos registros de Trinity
Agregar una Nueva Ubicación
curl --request POST \
--url 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=locations' \
--data 'locname,locaddr1,locaddr2,loccity,locstate,loczip,loclat,loclong,meterinstalldate,contract,serialnum
1009001,557-2026 Purus St.,,Watertown,TN,07367,,,2018-07-01,unassigned,unassigned'
<?php
$data = 'locname,locaddr1,locaddr2,loccity,locstate,loczip,loclat,loclong,meterinstalldate,contract,serialnum';
$data .= '1009001,557-2026 Purus St.,,Watertown,TN,07367,,,2018-07-01,unassigned,unassigned';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=locations');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"records_imported":1,
"record_keys":[
{
"juice_key":"L03291",
"external_key":"1009001"
}
]
}
}
Agregar un Nuevo Medidor
curl --request POST \
--url 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=meters' \
--data 'serialnum,deviceid,comtype,tariff,sgc,ti,keyrev,keyexp,basedate,sts_version,maxpower,addactiveread,server,wallet,contract,locname
1234abcde,1234abcde,MultiSpeak,SBT,,,,,,,,0,primary,units,unassigned,1009001'
<?php
$data = 'serialnum,deviceid,comtype,tariff,sgc,ti,keyrev,keyexp,basedate,sts_version,maxpower,addactiveread,server,wallet,contract,locname';
$data .= '1234abcde,1234abcde,MultiSpeak,SBT,,,,,,,,0,primary,units,unassigned,1009001';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=meters');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"records_imported":1
}
}
Agregar un Nuevo Cliente
curl --request POST \
--url 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=customers' \
--data 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum
5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,L03291,0cb4fce5'
<?php
$data = 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum\n';
$data .= '5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,L03291,0cb4fce5';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/import?portal=example&table=customers');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estrcturado de esta manera:
{
"error":0,
"data":{
"records_imported":1,
"record_keys":[
{
"juice_key":"03284",
"external_key":"5004000"
}
]
}
}
Solicitud HTTP
POST /file-importer/trinity/import?portal=<portal>&table=<table>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El nombre del portal para importar información de registros. | Yes |
| table | La tabla base en la que deben insertarse estos registros. Las opciones válidas incluyen: customers, locations, y meters |
Yes |
Solicitud de mapeo de llave de importación
curl --request GET \
--url 'api.utiliflex.com:8080/file-importer/trinity/get-keys?portal=example&table=customers'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/get-keys?portal=example&table=customers');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error": 0,
"data": [
{
"juice_key": "00001",
"external_key": "1005088"
},
{
"juice_key": "00002",
"external_key": "1024732"
},
{
"juice_key": "00003",
"external_key": "1024760"
},
{
"juice_key": "00004",
"external_key": "1020485"
},
{
"juice_key": "00005",
"external_key": "1020522"
}
]
}
Si bien JuiceAPI es capaz de realizar búsquedas de claves externas (foreign keys) durante el proceso de importación / actualización, también es posible que JuiceAPI devuelva una lista que contenga la clave interna (internal key) de Juice y la clave externa proporcionada por el proveedor durante la importación inicial. Esto funciona en una base por tabla, y solo para la tabla de clientes y ubicaciones.
Solicitud HTTP
GET /file-importer/trinity/get-keys?portal=<portal>&table=<table>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El nombre del portal Juice para obtener claves (keys) | Yes |
| table | El nombre de la tabla para obtener claves (keys), las opciones válidas son customers y locations |
Yes |
Actualizar los registros existentes de Trinity
curl --request POST \
--url 'api.utiliflex.com:8080/file-importer/trinity/update?portal=example&table=customers' \
--data 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum
5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,1009001,0cb4fce5'
<?php
$data = 'contract,name,phone1,phone2,sms1,sms2,email,address1,address2,city,state,postalcode,locname,serialnum\n';
$data .= '5004000,Palmer Guy,14235550100,,14235550100,,palmerg@example.com,557-2026 Purus St.,,Watertown,TN,07367,1009001,0cb4fce5';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/trinity/update?portal=example&table=customers');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error": 0,
"data": {
"records_updated": 1,
"record_keys": [
{
"juice_key": "03284",
"external_key": "5004000"
}
]
}
}
Utilizando el importador de archivos planos también es posible actualizar un subconjunto de los datos de trinidad (Trinity) (Cliente, Ubicación, Medidor).
Solicitud HTTP
POST /file-importer/trinity/update?portal=<portal>&table=<table>
Parámetros de consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El nombre del portal para actualizar los registros | Yes |
| table | La tabla base para actualizar. Las opciones válidas son: customers, locations, y meters |
Yes |
Importador de archivos de Ajuste de Saldo masivo
Usando el Importador de Achivos de Ajuste de Saldo Masivo ss posible importar cosas como los atrasos, así como los ajustes al saldo de la cartera de un cliente dentro del sistema.
Definición del archivo de ajuste
Tanto los atrasos como los ajustes de cartera utilizan la misma definición de archivo
| Field | Type | Description | Blank |
|---|---|---|---|
| account | string | El número de cuenta para aplicar el ajuste puede ser clave de Juice o clave externa si foreignkeys=true |
No |
| startdate | datetime | Cuando los atrasos deban tener efecto en la cuenta, la fecha debe estar en formato RFC3339 por ejemplo: YYYY-MM-DDTHH:MM:SSZhh:mm. La T s el separador de fecha y hora y la Z denota la compensación de UTC. Para los ajustes de la cartera, tanto de la moneda como de la unidad, este campo no se utiliza y puede dejarse en blanco. |
Yes |
| amount | float | Cantidad para ajustar la cartera o crear un nuevo atraso. La cantidad debe ser representada sin ningún tipo de signo ($/+/-). Para los atrasos y ajustes de moneda este valor es un valor de moneda, para los ajustes de cartera de la unidad este valor es en kWh. | No |
| paid | float | Suma de la cantidad de dinero ya pagada por los atrasos, para ajustes de cartera dejar en blanco. | Yes |
| payplan | string | Debe ser un número numérico seguido de un signo de porcentaje (%) representado como un valor de cadena (string). Si el espacio en blanco es el 100%. Para los ajustes de la cartera, tanto de la moneda como de la unidad, este campo no se utiliza. | Yes |
Importación de datos de ajuste de atrasos
curl --request POST \
--url 'api.utiliflex.com/file-importer/balance-adj/arrears?portal=example' \
--data 'account,startdate,amount,paid,payplan
03284,2018-07-23T00:00:00Z04:00,100.00,0.00,100%'
<?php
$data = 'account,startdate,amount,paid,payplan\n';
$data .= '03284,2018-07-23T00:00:00Z04:00,100.00,0.00,100%';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com/file-importer/balance-adj/arrears?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error":0,
"data":{
"records_imported":1,
"customers":[
{
"account":"03284",
"arrears_amount":"$100.00"
}
]
}
}
Nota: El valor en el campo
arrears_amountestá formateado de acuerdo con la moneda predeterminada para el portal.
Solicitud HTTP
POST /file-importer/balance-adj/arrears?portal=<portal>&debit=<debit>&credit=<credit>&foreignkeys=<fkeys>
Parámetros de la consulta
| Parameter | Default | Description | Required |
|---|---|---|---|
| portal | '' | El nombre del portal para importar los ajustes | Yes |
| debit | 1100 | El COA de Juice para debitar en las entradas de GL, por defecto es 1100 si se deja en blanco |
No |
| credit | 9100 | El COA de jugo para acreditar en las entradas de GL, por defecto es 9100 si se deja en blanco |
No |
| foreignkeys | false | Ya sea para usar las claves de Juice o las claves extranjeras (foreign keys) para la búsqueda de cuentas, por defecto se usan las claves de Juice | No |
Importación de ajustes de la cartera de la unidad
curl --request POST \
--url 'api.utiliflex.com:8080/file-importer/balance-adj/unitwallet/fund?portal=example' \
--data 'account,startdate,amount,paid,payplan
03284,,10,,'
<?php
$data = 'account,startdate,amount,paid,payplan';
$data .= '03284,,10,,';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/file-importer/balance-adj/unitwallet/fund?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve a un JSON estructurado de esta manera:
{
"error":0,
"data":{
"imported":1
}
}
Solicitud HTTP
POST /file-importer/balance-adj/unitwallet/<type>?portal=<portal>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El nombre del portal para importar los ajustes de la cartera de la unidad | Yes |
Tipos de ajuste
Los siguientes tipos de ajuste son compatibles actualmente:
| Type | Description |
|---|---|
| fund | Añade la cantidad dada al saldo de la cartera del cliente como una emisión gratuita |
| debit | Resta la cantidad dada del saldo de la cartera de los clientes |
Clientes
Obtener información básica del cliente
curl --request GET \
--url 'api.utiliflex.com:8080/customers/get-customer?portal=example&account=03280'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/get-customer?portal=example&account=03280');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": {
"account": "03280",
"contract": "5003986",
"portal": "test",
"name": "Ringo Starr",
"last_name": "Starr",
"first_name": "Ringo",
"phone_1": "14235290856",
"phone_2": "",
"sms_1": "14235290856",
"sms_2": "",
"email_1": "ringo@example.com",
"email_2": "",
"address_1": "3131 Mountain Creek RD",
"address_2": "Apt 14A2",
"city": "Chattanooga",
"state": "TN",
"postal_code": "37415",
"created": "2017-10-19T13:47:09-04:00",
"last_mod": "2019-04-16T15:58:28-04:00",
"notify_days": 3,
"email_notify": 1,
"sms_notify": 0,
"phone_notify": 0
}
}
Este punto final permite obtener información básica de la cuenta del cliente.
Solicitud HTTP
GET /customers/get-customer?portal=<portal>&account=<account>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal para consultar información | Yes |
| account | El número de cuenta de Juice para que el cliente obtenga detalles | Yes |
Obtener el balance de la cartera de los clientes
curl --request GET \
--url 'api.utiliflex.com:8080/customers/wallet/get-value?portal=example&account=03280&serialnumber=1234abcde'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/wallet/get-value?portal=example&account=03280&serialnumber=1234abcde');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
Cuando se solicita el saldo de la cartera para el cliente y el medidor utilizando una cartera unitaria
{
"error": 0,
"data": {
"account": "03280",
"meter": {
"1234abcde": {
"unit_balance": 0.58,
"units": "kWh",
"est_amt": "$0.17"
}
}
}
}
Cuando se solicita el saldo de la cartera para el cliente y el medidor usando una cartera de divisas
{
"error": 0,
"data": {
"account": "03284",
"meter": {
"14155008478": {
"currency_balance": "$30.00"
}
}
}
}
Este punto final permite obtener el saldo de la cartera de un cliente, ya sea la cartera monetaria o la cartera de la unidad, dependiendo de la que se utilice para el medidor en cuestión. De forma predeterminada, este punto final devuelve el saldo actual de la billetera del cliente, pero opcionalmente puede devolver el saldo en un punto determinado.
Solicitud HTTP
GET /customers/wallet/get-value?portal=<portal>&account=<account>&serialnumber=<serialnumber>&end_date=<datetime>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal de consulta de información | Yes |
| account | El número de cuenta de Juice para que el cliente obtenga el saldo for | Yes |
| serialnumber | El número de serie del medidor adjunto al cliente para obtener el saldo efectivo | Yes |
| end_date | La fecha límite para los saldos de cartera, utilizada para obtener el saldo en cierto punto. La fecha y hora debe estar en formato RFC3339 |
No |
Obtener el saldo de la cartera de varios clientes
curl --request GET \
--url 'api.utiliflex.com:8080/customers/wallet/get-values?portal=example&account=03280|03283|03284'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/wallet/get-values?portal=example&account=03280|03283|03284');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": [
{
"account": "03284",
"meter": {
"14155008478": {
"currency_balance": "$30.00"
}
}
},
{
"account": "03280",
"meter": {
"1234abcde": {
"unit_balance": 0.58,
"units": "kWh",
"est_amt": "$0.17"
}
}
},
{
"account": "03283",
"meter": {
"58027013": {
"unit_balance": 238.78,
"units": "kWh",
"est_amt": "$20.05"
},
"AMI1234": {
"unit_balance": 238.78,
"units": "kWh",
"est_amt": "$20.05"
}
}
}
]
}
Este punto final permite obtener el saldo de la cartera de una o más cuentas de clientes, limitado a un máximo de 200 cuentas por solicitud. Si alguna de las cuentas solicitadas tiene varios medidores adjuntos, se informará el saldo efectivo de la cartera para cada medidor. Por defecto, este punto final devuelve el saldo actual de la billetera del cliente, pero opcionalmente puede devolver el saldo en un punto determinado.
Solicitud HTTP
GET /customers/wallet/get-value?portal=<portal>&account=<account>&end_date=<datetime>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal para consultar información | Yes |
| account | Una lista de números de cuenta de Juice, separados con barras verticales | llimitada a 200 cuentas por solicitud, de los clientes para obtener el saldo |
Yes |
| end_date | La fecha límite para los saldos de billetera, utilizada para obtener el saldo en cierto punto. La fecha y hora debe estar en formato RFC3339 |
No |
Gestión de atrasos de los clientes
Esta sección documenta la gestión de los atrasos de un cliente mediante el uso de JuiceAPI, lo que implica el listado de los atrasos actuales adeudados por los clientes y, en futuras actualizaciones, la gestión directa del saldo de atrasos, o la creación de nuevos atrasos directamente.
Obtención de una lista de todas las cuentas de clientes con atrasos actuales
curl --request GET \
--url 'api.utiliflex.com:8080/customers/arrears/all-owed-arrears?portal=example&details=true'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/arrears/all-owed-arrears?portal=example&details=true');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
"error": 0,
"data": {
"customers": [
{
"account": "00001",
"arrears_amount": "-$12.50"
},
{
"account": "00002",
"arrears_amount": "-$1,765.75"
},
{
"account": "00003",
"arrears_amount": "-$445.16"
},
{
"account": "00004",
"arrears_amount": "-$330.30"
},
{
"account": "00005",
"arrears_amount": "-$681.77"
}
]
}
}
El punto final de todos los atrasos adeudados devuelve una lista de todas las cuentas de clientes en Juice que tienen saldos de atrasos pendientes, y el total de todos sus saldos pendientes.
Solicitud HTTP
GET /customers/arrears/all-owed-arrears?portal=<portal>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El nombre del portal para consultar datos de atrasos | Yes |
Obtención de una lista de atrasos por tipo de atraso
curl --request GET \
--url 'api.utiliflex.com:8080/customers/arrears/get-arrears/by-type?portal=example&arrears_coa=9100&details=true'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/arrears/get-arrears/by-type?portal=example&arrears_coa=9100&details=true');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error": 0,
"data": {
"customers": {
"03283": [
{
"account": "03283",
"arrears_id": 5,
"issued_date": "2019-04-18T14:31:41-04:00",
"start_date": "2019-04-18T00:00:00-04:00",
"arrears_type": "CIStransfer",
"pay_plan": "100%",
"arrears_amount": "-$100.00",
"paid_amount": "$0.00",
"outstanding_amount": "-$100.00"
}
],
"03284": [
{
"account": "03284",
"arrears_id": 85,
"issued_date": "2019-04-01T09:17:17-04:00",
"start_date": "2019-04-01T00:00:00-04:00",
"arrears_type": "CIStransfer",
"pay_plan": "25%",
"arrears_amount": "-$20.00",
"paid_amount": "$20.00",
"outstanding_amount": "$0.00",
"payments": [
{
"created": "2019-04-04T10:32:44-04:00",
"trans": 245,
"type": "payment",
"amount": "$12.50"
},
{
"created": "2019-04-04T16:03:21-04:00",
"trans": 252,
"type": "payment",
"amount": "$3.33"
},
{
"created": "2019-04-04T16:03:21-04:00",
"trans": 253,
"type": "payment",
"amount": "$0.25"
},
{
"created": "2019-04-25T15:35:15-04:00",
"trans": 291,
"type": "writeoff",
"amount": "$3.92"
}
]
}
]
}
}
}
A través de la API también es posible obtener una lista de todas las cuentas de clientes que tienen un saldo pendiente para un tipo de atraso determinado. Además de mostrar opcionalmente los detalles de cada pago de ese atraso
Solicitud HTTP
GET /customers/arrears/get-arrears/by-type?portal=<portal>&arrears_coa=<coa>&details=<details>
Parámetros de la consulta
| Parameter | Type | Description | Required |
|---|---|---|---|
| portal | string | The system portal to get arrears list for | Yes |
| arrears_coa | string | El COA para que regrese el tipo de atrasos | Yes |
| details | bool | Si se establece como true se devolverá una lista de los pagos realizados para cada atraso (default: false) |
No |
Obtener una lista de atrasos para un cliente
curl --request GET \
--url 'api.utiliflex.com:8080/customers/arrears/get-arrears/for-customer?portal=example&account=03285&details=true'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/customers/arrears/get-arrears/for-customer?portal=example&account=03285&details=true');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error": 0,
"data": {
"customers": {
"03285": [
{
"account": "03285",
"arrears_id": 2,
"issued_date": "2019-04-25T14:23:32-04:00",
"start_date": "1970-01-01T00:00:00-05:00",
"arrears_type": "Gimme5",
"pay_plan": "100%",
"arrears_amount": "-$0.44",
"paid_amount": "$0.00",
"outstanding_amount": "-$0.44"
},
{
"account": "03285",
"arrears_id": 1,
"issued_date": "2019-04-25T14:22:44-04:00",
"start_date": "2019-04-25T00:00:00-04:00",
"arrears_type": "CIStransfer",
"pay_plan": "25%",
"arrears_amount": "-$1,000.00",
"paid_amount": "$0.00",
"outstanding_amount": "-$1,000.00"
}
]
}
}
}
A través del API también es posible obtener una lista de todos los atrasos de un cliente. Además de mostrar opcionalmente los detalles de cada pago de ese atraso
Solicitud HTTP
GET /customers/arrears/get-arrears/for-customer?portal=<portal>&account=<account>&details=<details>
Parámetros de la consulta
| Parameter | Type | Description | Required |
|---|---|---|---|
| portal | string | El portal del sistema para obtener la lista de atrasos para | Yes |
| account | string | El número de cuenta de Juice para que el cliente obtenga los datos de los atrasos | Yes |
| details | bool | Si se establece en true devolverá una lista de los pagos efectuados por cada uno de los atrasos (default: false) |
No |
Gestión de atrasos
En esta sección se describe el punto final disponible para la gestión de los atrasos y los tipos de atrasos en Juice.
Lista de tipos de atrasos
curl --request GET \
--url 'api.utiliflex.com:8080/arrears/list-types?portal=example'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/arrears/list-types?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error": 0,
"data": [
{
"portal": "%",
"arrears_type": "Recovery ",
"description": "Initial Meter Recovery",
"coa": "1101",
"last_mod": "2016-09-12T11:53:01-04:00",
"selectable": true
},
{
"portal": "%",
"arrears_type": "PostPaid",
"description": "PostPaid Recovery",
"coa": "1102",
"last_mod": "2016-09-12T11:53:01-04:00",
"selectable": true
},
{
"portal": "example",
"arrears_type": "CIStransfer",
"description": "Transfer from legacy CIS system",
"coa": "9100",
"last_mod": "2017-01-30T19:58:57-05:00",
"selectable": true
},
{
"portal": "%",
"arrears_type": "FundsRecovery",
"description": "Bad Funds Recovery",
"coa": "9110",
"last_mod": "2016-09-12T11:53:01-04:00",
"selectable": true
},
{
"portal": "%",
"arrears_type": "FundsRecoveryFee",
"description": "Bad Funds Recovery Fee/Fine",
"coa": "4950",
"last_mod": "2016-09-12T11:53:01-04:00",
"selectable": true
},
{
"portal": "%",
"arrears_type": "TamperFine",
"description": "Tamper Fine",
"coa": "4959",
"last_mod": "2016-09-12T11:53:01-04:00",
"selectable": true
},
{
"portal": "%",
"arrears_type": "Installation",
"description": "Installation",
"coa": "4955",
"last_mod": "2016-09-12T11:53:01-04:00",
"selectable": true
}
]
}
Este punto final devuelve una lista de todos los tipos de atrasos que están disponibles en cualquier portal del sistema, así como los tipos de atrasos específicos del portal..
Solicitud HTTP
GET /arrears/list-types?portal=<portal>
Parámetros de consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El nombre del portal para consultar datos de atrasos | Yes |
Ubicación
Obtener detalles de Ubicación
curl --request GET \
--url 'api.utiliflex.com:8080/location/get-location?portal=example&locid=L03281'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/location/get-location?portal=example&locid=L03281');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": {
"portal": "example",
"loc_id": "L03281",
"serial_number": "1234abcde",
"account": "03280",
"loc_name": "10029384",
"loc_address_1": "3131 Mountian Creek Rd",
"loc_address_2": " Apt 14A2",
"loc_city": "Chattanooga",
"loc_state": "TN",
"loc_zip": "37415",
"loc_lat": "",
"loc_long": "",
"substation": "",
"transformer": "",
"module": "",
"socket": 0,
"meter_installed": "2015-05-01T00:00:00-04:00",
"created": "2017-10-19T13:46:00-04:00",
"last_mod": "2017-12-19T13:37:17-05:00",
"voltage": "120V",
"kva": 0,
"tariff": "SBT",
"subtariff": "PrePaid",
"type": "ANSI",
"form_factor": "1S",
"wiring": "2W",
"current_per_phase": 100,
"feeder": "",
"unit": ""
}
}
Este punto final permite obtener información básica de ubicación.
Solicitud HTTP
GET /location/get-location?portal=<portal>&locid=<locid>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal para consultar los medidores | Yes |
| locid | El ID de ubicación de Juice para la ubicación para obtener detalles for | Yes |
Gestión de tarifas
Listado de tarifas actuales en Juice
curl --request GET \
--url 'api.utiliflex.com:8080/tariff/fetch-current?portal=example'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/fetch-current?portal=example');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": [
{
"id": 3,
"portal": "example",
"tariff": "SBT",
"desc": "Standard Block Tariff",
"rate": [
{
"id": 33,
"service": "Electricity",
"tier": "B1",
"rate": "0.3452",
"start_date": "2017-02-06T01:40:00-05:00",
"end_date": "2030-12-31T23:59:00-05:00",
"last_mod": "2017-02-06T10:11:20-05:00",
"usage_base_start": 0,
"rate_plan_desc": "Block 1",
"units": "kWh",
"coa": 4005,
"ar_coa": 1102
},
{
"id": 34,
"service": "Electricity",
"tier": "B2",
"rate": "0.3572",
"start_date": "2017-02-06T01:29:00-05:00",
"end_date": "2030-12-31T23:59:00-05:00",
"last_mod": "2017-02-06T10:12:22-05:00",
"usage_base_start": 500,
"rate_plan_desc": "Block 2",
"units": "kWh",
"coa": 4005,
"ar_coa": 1102
},
{
"id": 35,
"service": "Electricity",
"tier": "B3",
"rate": "0.1",
"start_date": "2017-02-06T01:24:00-05:00",
"end_date": "2030-12-31T23:59:00-05:00",
"last_mod": "2017-02-06T10:12:58-05:00",
"usage_base_start": 1000,
"rate_plan_desc": "Block 3",
"units": "kWh",
"coa": 4005,
"ar_coa": 1102
}
],
"fixed": {
"id": 1,
"portal": "example",
"tariff": "SBT",
"desc": "Fixed Charge",
"amount": "12.5",
"coa": "4900",
"ar_coa": "1102"
},
"kva_fixed": {
"levy": [
{},
{},
{}
],
"last_mod": "0001-01-01T00:00:00Z"
},
"meter_count": 2
},
{
"id": 1,
"portal": "example",
"tariff": "RESIDENTIAL",
"desc": "Residential rate",
"muni": "Chattanooga",
"rate": [
{
"id": 1,
"service": "Electricity",
"tier": "B1",
"rate": "0.084",
"start_date": "2012-10-01T15:00:00-04:00",
"end_date": "2030-12-31T23:59:00-05:00",
"last_mod": "2016-09-12T13:18:13-04:00",
"usage_base_start": 0,
"units": "kWh",
"taxable": true,
"coa": 4005,
"ar_coa": 1102
},
{
"id": 2,
"service": "Electricity",
"tier": "B2",
"rate": "0.072",
"start_date": "2012-10-01T15:01:00-04:00",
"end_date": "2030-12-31T23:59:00-05:00",
"last_mod": "2016-09-12T13:18:13-04:00",
"usage_base_start": 1200,
"units": "kWh",
"taxable": true,
"coa": 4005,
"ar_coa": 1102
}
],
"fixed": {},
"kva_fixed": {
"levy": [
{},
{},
{}
],
"last_mod": "0001-01-01T00:00:00Z"
},
"meter_count": 1
}
]
}
Este punto final devuelve todas las tarifas configuradas en Juice con sus tasas actualmente activas, así como cualquier cargo fijo asociado para cada tarifa.
Solicitud HTTP
GET /tariff/fetch-current?portal=<portal>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal de Juice para obtener detalles de tarifas | Yes |
Obteniendo detalles para una tarifa única
curl --request GET \
--url 'api.utiliflex.com:8080/tariff/get/current?portal=example&tariff=RESIDENTIAL'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/get/current?portal=example&tariff=RESIDENTIAL');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": {
"id": 1,
"portal": "test",
"tariff": "RESIDENTIAL",
"desc": "Residential rate",
"muni": "Chattanooga",
"rate": [
{
"id": 1,
"service": "Electricity",
"tier": "B1",
"rate": 0.084,
"start_date": "2012-10-01T15:00:00-04:00",
"end_date": "2030-12-31T23:59:00-05:00",
"last_mod": "2016-09-12T13:18:13-04:00",
"usage_base_start": 0,
"units": "kWh",
"taxable": true,
"coa": 4005,
"ar_coa": 1102
},
{
"id": 2,
"service": "Electricity",
"tier": "B2",
"rate": 0.072,
"start_date": "2012-10-01T15:01:00-04:00",
"end_date": "2030-12-31T23:59:00-05:00",
"last_mod": "2016-09-12T13:18:13-04:00",
"usage_base_start": 1200,
"units": "kWh",
"taxable": true,
"coa": 4005,
"ar_coa": 1102
}
],
"fixed": {},
"kva_fixed": {
"levy": [
{},
{},
{}
],
"last_mod": "0001-01-01T00:00:00Z"
},
"meter_count": 1
}
}
Este punto final devuelve la tarifa solicitada con sus tasas actualmente activas, así como cualquier cargo fijo asociado a la tarifa.
Solicitud HTTP
GET /tariff/get/current?portal=<portal>&tariff=<tariff>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal “Juice” para obtener detalles de tarifas | Yes |
| tariff | El nombre de la tarifa a buscar | Yes |
Añadir un plan de tarifas futuras a una tarifa
curl --request POST \
--url 'api.utiliflex.com:8080/tariff/create/future-rateplan' \
--data '{
"portal":"test",
"tariff":"SBT",
"start_date":"2019-05-01T00:00:00Z",
"end_date":"2040-12-31T23:59:59Z",
"service":"Electricity",
"tier":"B1",
"rate":0.3572,
"usage_base_start":0,
"units":"kWh",
"coa":4005,
"ar_coa":1102
}'
<?php
$data = '{
"portal":"test",
"tariff":"SBT",
"start_date":"2019-05-01T00:00:00Z",
"end_date":"2040-12-31T23:59:59Z",
"service":"Electricity",
"tier":"B1",
"rate":0.3572,
"usage_base_start":0,
"units":"kWh",
"coa":4005,
"ar_coa":1102
}';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/tariff/create/future-rateplan');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": [
{
"id": 56,
"service": "Electricity",
"tier": "B1",
"rate": 0.3572,
"start_date": "2019-05-01T00:00:00Z",
"end_date": "2040-12-31T23:59:59Z",
"last_mod": "2019-04-05T13:30:00-04:00",
"usage_base_start": 0,
"units": "kWh",
"coa": 4005,
"ar_coa": 1102
}
]
}
Este punto final permite programar un plan de tarifas futuras en Juice. Si ya existe un plan de tarifas actualmente activo en la tarifa para el nivel dado, entonces la fecha final para el plan de tarifas actual se actualiza para que expire cuando el nuevo plan deba entrar en vigor. Si el plan de tarifas que se está añadiendo es un nuevo nivel/bloque de la tarifa entonces se programará para que entre en vigor en la fecha de inicio sin cambiar el otro niveles.
Solicitud HTTP
POST /tariff/create/future-rateplan
POST Campos del cuerpo
El cuerpo de la publicación debe ser una cadena codificada json con los siguientes campos:
| Field | Type | Description | Required |
|---|---|---|---|
| portal | string | El portal “Juice” para la tarifa | Yes |
| tariff | string | El nombre de la tarifa para programar el nuevo plan de tarifas | Yes |
| start_date | datetime | La fecha y hora en que el plan de tarifas debe estar activo, la marca de tiempo está en el formato RFC3339 format. |
Yes |
| end_date | datetime | La fecha y hora en que el plan de tarifas debe expirar, la marca de tiempo está en formato RFC3339 |
Yes |
| service | string | El tipo de servicios públicos para el que es válida esta tarifa, por ejemplo, “Electricidad”. | Yes |
| tier | string | El nivel/bloque de la tasa, los niveles válidos son “B1” a “B8”, “A” y “L” | Yes |
| rate | float | El tipo que debe usarse al aplicar el arancel durante una compra | Yes |
| usage_base_start | int | El punto, en unidades, en el que esta tasa debería ser efectiva | Yes |
| units | string | Las unidades que se compran, por ejemplo, “kWh”, “kL” | Yes |
| coa | int | El libro de cuentas (COA Ledger ) que se debe utilizar cuando se usa la tarifa durante una compra. Por defecto 4005 | Yes |
| ar_coa | int | El libro de cuentas (COA Ledger )que debe utilizarse para los atrasos en el pago de los aranceles. Por defecto 1102 | Yes |
Transacciones
JuiceAPI expone varios puntos finales y métodos para trabajar con los datos de las transacciones de Juice.
Exportación de los datos de las transacciones
curl --request GET \
--url 'api.utiliflex.com:8080/transactions/dump?portal=example&end_date=2019-03-08T23:59:59-04:00'
<?php
$endDate = '2019-03-08T23:59:59-04:00';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, "api.utiliflex.com:8080/transactions/dump?portal=example&end_date=$endDate");
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": [
{
"vendor_number": "CEC",
"login": "cashier1",
"customer": {
"account": "03284",
"contract": "5004000",
"name": "Palmer Guy",
"serial_number": "14155008478"
},
"transaction": {
"id": 230,
"type": "cash",
"trans_date": "2019-03-08T15:32:43-05:00",
"arrears_payment": 10,
"amount": 10,
"kwh": 27.996,
"check": {
"number": 0,
"name": ""
}
}
},
{
"vendor_number": "",
"login": "auto",
"customer": {
"account": "03283",
"contract": "03283",
"name": "Fred Fredburger",
"serial_number": "AMI1234"
},
"transaction": {
"id": 233,
"type": "wallet",
"trans_date": "2019-03-08T16:32:59-05:00",
"arrears_payment": 0,
"amount": 0.45,
"kwh": 5.102,
"check": {
"number": 0,
"name": ""
}
}
}
]
}
Es posible conseguir un volcado de todas las transacciones en un plazo de 24 horas de una fecha y hora determinadas utilizando el punto final de volcado de la transacción. Este punto final espera dos parámetros de URL, el nombre del portal de Juice para obtener datos y la hora de la fecha final en formato ISO-8601, la fecha de inicio se calcula automáticamente.
Para obtener el valor de un día completo de datos de transacciones utilice una fecha de finalización similar a la de 2019-03-25T23:59:59-04:00, esto devolverá todas las transacciones entre 2019-03-25 00:00:00 y 2019-03-25 23:59:59.
Solicitud HTTP
GET /transactions/dump?portal=<portal>&end_date=<date>
Parámetros de la Consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El portal de Juice para obtener las transacciones | Yes |
| end_date | La fecha límite para el volcado de transacciones en formato ISO-8601 format | Yes |
Ajuste del saldo de la cuenta del cliente
curl --request POST \
--url 'api.utiliflex.com:8080/transactions/adjust?portal=example' \
--data 'account,startdate,amount,paid,payplan
03284,,10.25,,
03285,2019-04-04T10:14:00-04:00,-100,0,25%'
<?php
$data = 'account,startdate,amount,paid,payplan
03284,,10.25,,
03285,2019-04-04T10:14:00-04:00,-100,0,25%';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, "api.utiliflex.com:8080/transactions/adjust?portal=example");
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
{
"error": 0,
"data": {
"processed": [
"account 03284 credited $10.25",
"account 03284 new arrears for -$100.00"
],
"arrears_data": [
{
"account": "03284",
"arrears_id": 298,
"arrears_amount": "$100.00",
"start_date": "2019-04-29T10:14:00-04:00",
"arrears_type": "FundsRecovery"
}
],
"error": null
}
}
Mediante este punto final es posible acreditar o debitar la cuenta de un cliente, en forma de créditos de cartera de divisas o la emisión de atrasos.
Este punto final toma un archivo CSV con el mismo diseño definido en el I Bulk Balance Adjustment File Importer de este documento. La única diferencia en el formato de archivo en la especificación del archivo es que el campo de amount puede tener un número negativo para indicar que el registro es para una creación de atrasos en lugar de un crédito de cartera.
Solicitud HTTP
POST /transactions/adjust?portal=<portal>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | Envío de ajustes para el portal Juuce | Yes |
Reversing Transactions
curl --request POST \
--url 'api.utiliflex.com:8080/transactions/reverse' \
--data '{"portal":"example","id":100,"life_note":"Transaction preformed on wrong account"}'
<?php
$data = '{"portal":"example","id":100,"life_note":"Transaction preformed on wrong account"}';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, "api.utiliflex.com:8080/transactions/reverse");
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close($chx);
{
"data": {
"account": "03280",
"amount": "$10.00",
"id": 595,
"original_created":"2020-07-15T12:50:08-04:00",
"type": "cash"
},
"error": 0
}
Este punto final permite revertir las transacciones en Juice. La transacción que se debe revertir para un portal debe ser enviada como JSON.
Solicitud HTTP
POST /transactions/reverse
Solicitud JSON
| Key | Type | Description | Required |
|---|---|---|---|
| portal | string | El portal de Juice en el que se encuentra la transacción | Yes |
| id | int | La ID de transacción de Juice que se anulará | Yes |
| life_note | string | La razón por la que la anulación debe hacerse | Yes |
Gestión de usuarios del sistema
Generación de un token de API para un usuario
curl --request GET \
--url 'api.utiliflex.com:8080/systemuser/token/generate?portal=example&user=jsmith'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/token/generate?portal=example&user=jsmith');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
El comando anterior devuelve un JSON estructurado de esta manera::
{
"error": 0,
"data": {
"portal": "example",
"user": "jsmith",
"token": "7bac4120-8b8d-4c55-b47a-57349b8bd3c2"
}
}
Este punto final genera un nuevo token API para el usuario dado.
Solicitud HTTP
GET /systemuser/token/generate?portal=<PORTAL>&user=<USER>
Parámetros de la consulta
| Parameter | Description | Required |
|---|---|---|
| portal | El nombre del portal del sistema para actuar | Yes |
| user | El inicio de sesión para que el usuario del sistema genere un token | Yes |
Creating a New System User
curl --request POST \
--url 'api.utiliflex.com:8080/systemuser/create' \
--data '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":100000,"currency":"USD"},"blocked_accounts":""}'
<?php
$data = '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":100000,"currency":"USD"},"blocked_accounts":""}';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/create');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close();
The above command return JSON structured like this:
{
"data": {
"active": true,
"blocked_accounts": "",
"email": "swarren@example.com",
"external_vendor": false,
"login": "swarren",
"name": "Sarah Warren",
"phone_1": "15558765309",
"phone_2": "",
"portal": "example",
"sec_level": 60,
"sms_1": "15558765309",
"sms_2": "",
"special_limit": {
"amount": 100000,
"currency": "USD"
},
"system_role": "VENDOR",
"vending_limit": {
"amount": 1000000,
"currency": "USD"
},
"vendor_number": "CEC"
},
"error": 0
}
This endpoint allows creating new system users in Juice, upon creation it returns basic user information similar to the Get Basic Information for User.
HTTP Request
POST /systemuser/create
Request Parameters
The request should be sent as a JSON encoded string with the following fields.
| Field | Type | Description | Required |
|---|---|---|---|
| portal | string | The Juice portal for the new user | Yes |
| login | string | The login for the new Juice user | Yes |
| name | string | The name for the new Juice user | Yes |
| phone_1 | string | The primary phone number for the user. This field should only contain digits only no formatting | No |
| phone_2 | string | The secondary phone number for the user. This field should only contain digits only no formatting | No |
| sms_1 | string | The primary mobile number for the user. This field should only contain digits only no formatting | No |
| sms_2 | string | The secondary mobile number for the user. This field should only contain digits only no formatting | No |
| string | The email address for the user. | No | |
| system_role | string | The system role for the new user. See Default System Roles for a list of supported roles. | Yes |
| external_vendor | bool | If set to true the new user will be created as an external vendor, otherwise it will be created as an internal user |
Yes |
| vendor_number | string | The Juice vendor number the user belongs to. | Yes |
| vending_limit | Limit | The total amount that a user can vend to customers before needing to close out their batch | Yes |
| special_limit | Limit | The max amount the user can write off, reverse, debit/credit per action | Yes |
| blocked_accounts | string | A list of customer account numbers separated by commas (,). A wildcard (*) can be used to block access to all accounts. |
Yes |
Limit Object
| Field | Type | Description | Required |
|---|---|---|---|
| amount | int | The limit amount in the smallest denomination for the currency e.g. $1,000.00 -> 100000 | Yes |
| currency | string | The 3 character ISO 4217 code for the currency | Yes |
Fetching Basic Information for a User
curl --request GET \
--url 'api.utiliflex.com:8080/systemuser/get?portal=example&user=swarren'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/get?portal=example&user=swarren');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close($chx);
The above command returns JSON structured like this:
{
"data": {
"active": true,
"blocked_accounts": "",
"email": "swarren@example.com",
"external_vendor": false,
"login": "swarren",
"name": "Sarah Warren",
"phone_1": "15558765309",
"phone_2": "",
"portal": "example",
"sec_level": 60,
"sms_1": "15558765309",
"sms_2": "",
"special_limit": {
"amount": 100000,
"currency": "USD"
},
"system_role": "VENDOR",
"vending_limit": {
"amount": 1000000,
"currency": "USD"
},
"vendor_number": "CEC"
},
"error": 0
}
This endpoint fetches basic information for a system user in Juice.
HTTP Request
GET /systemuser/get?portal=<PORTAL>&user=<LOGIN>
Query Parameters
| Parameter | Description | Required |
|---|---|---|
| portal | The name of the system portal to act on | Yes |
| user | The login for the system user to fetch information for | Yes |
Updating User Information
curl --request POST \
--url 'api.utiliflex.com:8080/systemuser/update' \
--data '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":1000000,"currency":"USD"},"blocked_accounts":""}'
<?php
$data = '{"portal":"example","login":"swarren","name":"Sarah Warren","phone_1":"15558675409","phone_2":"","sms_1":"15558675409","sms_2":"","email":"swarren@example.com","system_role":"CSR","external_vendor":false,"vendor_number":"CEC","vendor_limit":{"amount":1000000,"currency":"USD"},"special_limit":{"amount":1000000,"currency":"USD"},"blocked_accounts":""}';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/update');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close();
The above command return JSON structured like this:
{
"error": 0
}
This endpoint allows updating system users in Juice.
HTTP Request
POST /systemuser/update
Request Parameters
The request should be sent as a JSON encoded string with the following fields.
| Field | Type | Description | Required |
|---|---|---|---|
| portal | string | The Juice portal for the user | Yes |
| login | string | The login for the Juice user | Yes |
| name | string | The name for the Juice user | Yes |
| phone_1 | string | The primary phone number for the user. This field should only contain digits only no formatting | No |
| phone_2 | string | The secondary phone number for the user. This field should only contain digits only no formatting | No |
| sms_1 | string | The primary mobile number for the user. This field should only contain digits only no formatting | No |
| sms_2 | string | The secondary mobile number for the user. This field should only contain digits only no formatting | No |
| string | The email address for the user. | No | |
| system_role | string | The system role for the user. See Default System Roles for a list of supported roles. | Yes |
| external_vendor | bool | If set to true the user will be created as an external vendor, otherwise it will be created as an internal user |
Yes |
| vendor_number | string | The Juice vendor number the user belongs to. | Yes |
| vending_limit | Limit | The total amount that a user can vend to customers before needing to close out their batch | Yes |
| special_limit | Limit | The max amount the user can write off, reverse, debit/credit per action | Yes |
| blocked_accounts | string | A list of customer account numbers separated by commas (,). A wildcard (*) can be used to block access to all accounts. |
Yes |
Limit Object
| Field | Type | Description | Required |
|---|---|---|---|
| amount | int | The limit amount in the smallest denomination for the currency e.g. $1,000.00 -> 100000 | Yes |
| currency | string | The 3 character ISO 4217 code for the currency | Yes |
Lista de permisos para el usuario actual
curl --request GET \
--url 'api.utiliflex.com:8080/systemuser/perms/get?login=jsmith'
<?php
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/perms/get?login=jsmith');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, false);
curl_exec($chx);
curl_close();
El comando anterior devuelve un JSON estructurado de esta manera:
{
"error": 0,
"data": [
{
"category": "Account",
"name": "passwd",
"description": "Change Password"
},
{
"category": "Account",
"name": "balance",
"description": "Drawer Balance and Batch"
},
{
"category": "Account Screen",
"name": "tabcoms",
"description": "Coms: SMS/Email/IVR/Issues",
"long_description": "Allows access to Com tab showing all Juice generated customer communications."
},
{
"category": "Account Screen",
"name": "tabcontrol",
"description": "Control Tab",
"long_description": "Allows access to manage tariff, location, meter, vending, and more. Commercial services agents and customer service managers should have access and review training documents before using."
}
]
}
Este punto final devuelve una lista detallada de todos los permisos habilitados para el usuario autenticado actual.
Solicitud HTTP
GET /systemuser/perms/get?login=<LOGIN>
Query Parameters
| Parameter | Description | Required |
|---|---|---|
| login | The login for the system user to fetch permissions for | Yes |
Updating Permission List for User
curl --request POST \
--url 'api.utiliflex.com:8080/systemuser/perms/update' \
--data '{"portal":"example","login":"jsmith","vendor_number":"CEC","perms":[{"name":"passwd","action":"keep"},{"name":"balance","action":"keep"},{"name":"tabcoms","action":"remove"},{"name":"tabcontrol","action":"keep"},{"name":"vendcash","action":"add"}]}'
<?php
$data = '{"portal":"example","login":"jsmith","vendor_number":"CEC","perms":[{"name":"passwd","action":"keep"},{"name":"balance","action":"keep"},{"name":"tabcoms","action":"remove"},{"name":"tabcontrol","action":"keep"},{"name":"vendcash","action":"add"}]}';
$chx = curl_init();
curl_setopt($chx, CURLOPT_URL, 'api.utiliflex.com:8080/systemuser/perms/update');
curl_setopt($chx, CURLOPT_RETURNTRANSFER, true);
curl_setopt($chx, CURLOPT_POST, true);
curl_setopt($chx, CURLOPT_POSTFIELDS, $data);
curl_exec($chx);
curl_close();
The above command returns JSON structured like this:
{
"error": 0,
"data": {
"role": "VENDOR",
"perms": [
{
"category": "Account",
"name": "passwd",
"description": "Change Password"
},
{
"category": "Account",
"name": "balance",
"description": "Drawer Balance and Batch"
},
{
"category": "Account Screen",
"name": "tabcontrol",
"description": "Control Tab",
"long_description": "Allows access to manage tariff, location, meter, vending, and more. Commercial services agents and customer service managers should have access and review training documents before using."
},
{
"category": "Vending",
"name": "vendcash",
"description": "Vend Cash",
"long_description": "Allows user to vend power with cash payment."
}
]
}
}
This endpoint allows updating the set permissions for the user. After the update is done, it returns the new list of permissions.
HTTP Request
POST /systemuser/perms/update
Request Parameters
The request should be sent as a JSON encoded string with the following fields.
| Field | Type | Description | Required |
|---|---|---|---|
| portal | string | The Juice portal the user belongs to. | Yes |
| login | string | The login for the system user to update permissions for. | Yes |
| vendor_number | string | The Juice vendor number the user belongs to. | Yes |
| perms | []Perm | Array of perms to enact on. | Yes |
Perm Object
| Field | Type | Description | Required |
|---|---|---|---|
| name | string | Name of the permission. | Yes |
| action | string | Action to take for the perm. Valid options are: add, remove, keep |
Yes |
Default System Roles
Juice has the following system roles:
| Role | Description |
|---|---|
| CSR | Standard Customer Service Representative / Cashier |
| CSR2 | Customer Service Representative / Cashier level 2 |
| CSR3 | Customer Service Representative / Cashier level 3 |
| ComMGR | Commercial Manager |
| VENDOR | Standard External Vendor |
| VENDORADM | External Vendor Admin |
| Engineer | Standard Utility Engineer |
| Accounting | Accounting / Finance Team Member |
| SysAdmin | Juice System Admin |
Códigos de error del cliente
JuiceAPI uiliza los siguientes códigos de error del JSON devuelto. Estos códigos de error se usan en conjunto con el código de error HTTP apropiado..
| Error Code | Meaning |
|---|---|
| 100 | Credenciales no válidas o no pasadas al sistema. |
| 101 | User lacks the required permissions for action. |
| 200 | Método o punto final desconocido o inválido |
| 201 | Parámetro no válido o faltante dado, se proporcionan más detalles en el campo. |
| 300 | Error de aplicación general, más detalles en el campo error_message. |
Errores
JuiceAPI utiliza los siguientes códigos de error::
| Error Code | Meaning |
|---|---|
| 400 | Solicitud incorrecta – su solicitud no es válida.. |
| 401 | No autorizado – Su clave API está equivocada. |
| 403 | Prohibido – No tiene los permisos necesarios para acceder al recurso solicitado. |
| 404 | No encontrado – No se pudo encontrar el recurso especificado. |
| 405 | Método no permitido – El método de solicitud no está permitido para este punto final. |
| 406 | No aceptable – La solicitud o los parámetros dados son inválidos. |
| 410 | Desaparecido – El recurso solicitado ya no existe. |
| 418 | I’m a teapot. |
| 429 | Demasiadas solicitudes – ¡Estás haciendo muchas peticiones en un corto período de tiempo! Despacio!. |
| 500 | Error interno del servidor – Tuvimos un problema con nuestro servidor. Inténtalo de nuevo más tarde.. |
| 503 | El servicio no está disponible – Estamos temporalmente fuera de línea por mantenimiento. Por favor, inténtelo de nuevo más tarde. |
Métodos HTTP
Siempre que sea posible, API se esfuerza por usar métodos HTTP apropiados para cada acción..
| Verb | Description |
|---|---|
| HEAD | Se puede emitir contra cualquier recurso para obtener solo la información del encabezado HTTP. |
| GET | Se utiliza para la recuperación de recursos |
| POST | Se utiliza para crear recursos |
| PATCH | Se utiliza para actualizar los recursos con datos parciales de JSON. Por ejemplo, un recurso de Issue tiene atributos de título y cuerpo. Una solicitud PATCH puede aceptar uno o más de los atributos para actualizar el recurso. PATCH es un método HTTP relativamente nuevo y poco común, por lo que los puntos finales de los recursos también aceptan solicitudes POST . |
| PUT | Se usa para reemplazar recursos o colecciones. Para las solicitudes PUT sin atributo body, asegúrese de establecer el encabezado Content-Length en cero. |
| DELETE | Se usa para eliminar recursos |
Nota: Actualmente, solo los métodos POST y GET son totalmente compatibles con la API. Los métodos PUT, PATCH, HEAD y DELETE pueden no ser compatibles o implementados por el punto final específico. Esto es así por diseño, ya que no todos los puntos finales admitirán los métodos PUT, PATCH y DELETE, el soporte para el método HEAD está actualmente pendiente y es posible que no se implemente en la versión 1 de la API.
Redirecciones HTTP
JuiceAPI utiliza la redirección HTTP cuando es apropiado. Los clientes deben asumir que cualquier solicitud puede resultar en una redirección. Recibir una redirección HTTP no es un error y los clientes deben seguir esa redirección. Las respuestas de redireccionamiento tendrán un campo de encabezado de Ubicación que contiene la URI del recurso al que el cliente debe repetir las solicitudes.
| Status Code | Description |
|---|---|
| 301 | Redirección permanente. La URI que usaste para hacer la solicitud ha sido reemplazada por la especificada en el campo de cabeceraLocation. Esta y todas las futuras solicitudes a este recurso deben ser dirigidas a la nueva URI. |
| 302 - 307 | Redirección temporal. La solicitud debe repetirse textualmente al URI especificado en el campo de encabezado pero los clientes deben continuar usando el URI original para futuras solicitudes. |