API de Consumo de Recargas y Pagos - v1.0.0

Unión Telecard Dominicana

Contenido

  1. Ambientes
  2. HTTP Headers
  3. Seguridad
  4. Autenticación
  5. Como hacer una llamada API
  6. Tiempo de Ejecución
  7. Obteniendo el BALANCE actual de su cuenta
  8. Obteniendo lista de Códigos de Respuesta del Servicio
  9. Obteniendo lista de Productos
  10. Obteniendo lista de Grupos de Producto
  11. Obteniendo lista de Tipos de Producto
  12. Obteniendo lista de Carriers (portadores de los productos)
  13. Consultando datos de Producto
  14. Comprando/Pagando un Producto
  15. Cancelando una compra/pago previa
  16. Consultando transacciones
  17. HTTP Codes
  18. Casos de Prueba



Map

Ambientes



HTTP Headers

Para realizar los requests, los encabezados HTTP utilizados deben ser:



Seguridad

Para realizar solicitudes a nuestros endpoints, debe utilizar el protocolo HTTPS, independientemente del entorno que esté utilizando.

Nota: Por razones de seguridad, nuestra API solo admite TLS v1.2 o posterior.



Autenticación

El API tiene una forma especial de autenticación, que se basa en la ruta y los encabezados HTTP de cada solicitud que se realiza. Cada solicitud debe contener los siguientes encabezados:

Como lo indica su descripción, el encabezado de autenticación es la forma de autenticarse en el API, está compuesto por el siguiente par: su usuario API y su llave secreta.

Nota: al crear un URL con parámetros, no olvide codificarla (consulte RFC1738 Sección 2.2). Las llaves y los valores deben estar codificados en formato MIME application/json.



Como hacer una llamada API

El endpoint /v1/account/balance mostrará el balance actual de su cuenta. Es una excelente manera de aprender a realizar solicitudes. Para este ejemplo, vamos a utilizar la herramienta curl.

1. Envíe su solicitud al entorno deseado. Reemplace <usuario> y <llava-secreata> con los proporcionados.

curl -X GET "https://dev.jsonapi.utelecard.com/v1/account/balance" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Date: $CURRENT_DATE" \
  -H "Authorization: APIKey <usuario>:<llave-secreta>"

2. Ejecute el script. El servidor responderá con un objeto JSON. Utilice esta información de acuerdo a sus necesidades.

{
  "payload": "868254.89"
}

Nota: tome en cuenta como se envían las credenciales en el header Authorization.



Tiempo de Ejecución

Todas las respuestas contienen la cabecera X-Runtime, la cual permite saber el tiempo que tomó la solicitud.

Ejemplo:
X-Runtime: 248.184375ms



Obteniendo el BALANCE actual de su cuenta

GET /v1/account/balance - balance actual

Parametros request:

Ninguno

Response:

{
  "payload": "868254.89"
}

Parametros response:

param type desc
payload decimal Balance de la Cuenta



Obteniendo lista de Códigos de Respuesta del Servicio

GET /v1/response-codes - lista códigos de respuesta

Parametros request:

Ninguno

Response:

{
  "payload": [
    {
      "code": "DB27",
      "message": "UTP TRANSACTION REJECTED, PHONE RATE LIMIT EXCEEDED",
    },
    {
      "code": "132",
      "message": "INVALID TRANSACTION DATE TIME",
    },
    {
      "code": "133",
      "message": "INVALID USERNAME OR PASSWORD"
    },
    {
      "code": "086",
      "message": "INSUFFICIENT FUNDS FOR RECHARGE"
    },
    {
      "code": "087",
      "message": "INVALID ACCOUNT NUMBER OR INCORRECT BILLER"
    },
    ...
  ]
}

Parametros response:

param type desc
payload array Diccionario de códigos y descripción
payload.code string Código de la respuesta
payload.message string Descripción de la respuesta



Obteniendo lista de Productos

GET /v1/products - lista productos asignados

Parametros request:

Ninguno

Response:

{
  "payload": [
    {
      "amount": "50",
      "carrierId": 9,
      "countryId": "332",
      "currencyId": "DOP",
      "id": 121,
      "maxAmount": "1500",
      "name": "HAITI DIGICEL$ $50-1500",
      "typeId": 1
    },
    {
      "amount": "50",
      "carrierId": 255,
      "countryId": "332",
      "currencyId": "DOP",
      "id": 182,
      "maxAmount": "1500",
      "name": "HAITI NATCOM$ $50-1500",
      "typeId": 1
    },
    {
      "amount": "25",
      "carrierId": 1,
      "countryId": "214",
      "currencyId": "DOP",
      "id": 357,
      "maxAmount": "1500",
      "name": "DOMINICAN REPUBLIC CLARO$ $25-1500",
      "typeId": 1
    },
    {
      "amount": "30",
      "carrierId": 10,
      "countryId": "214",
      "currencyId": "DOP",
      "id": 3149,
      "maxAmount": "2000",
      "name": "DATA PACKAGE CLARORD",
      "typeId": 14
    },
    ...
  ]
}

Parametros response:

param type desc
payload array Lista de Productos asignados
payload.amount dedimal Monto mínimo del producto
payload.carrierId int ID de Compañía portadora del servicio
payload.countryId string ISO-3166-1 númerico del país al que pertenece el producto
payload.currencyId string ISO-4217 numérico de la moneda del producto
payload.maxAmount decimal Monto máximo del producto
payload.name string Nombre del producto
payload.typId int ID del tipo de producto



Obteniendo lista de Grupos de Producto

GET /v1/products/groups - lista grupos de producto

Parametros request:

Ninguno

Response:

{
  "payload": [
    {
      "id": 17,
      "name": "UTILITIES"
    },
    {
      "id": 1,
      "name": "POSTPAGO"
    },
    {
      "id": 2,
      "name": "TELEFONIA FIJA"
    },
    {
      "id": 3,
      "name": "ELECTRICIDAD"
    },
    {
      "id": 4,
      "name": "ACUEDUCTO"
    },
    {
      "id": 5,
      "name": "TELECABLE"
    },
    {
      "id": 6,
      "name": "SEGUROS"
    },
    ...
  ]
}

Parametros response:

param type desc
payload array Lista de Grupos de Producto
payload.id int Id del grupo
payload.name string Nombre del grupo



Obteniendo lista de Tipos de Producto

GET /v1/products/types - lista tipos de producto

Parametros request:

Ninguno

Response:

{
  "payload": [
    {
      "id": 7,
      "name": "BILL PAYMENT"
    },
    {
      "id": 14,
      "name": "DATA PACKAGE"
    },
    {
      "id": 6,
      "name": "LOCAL PIN"
    },
    {
      "id": 1,
      "name": "RECHARGE"
    },
    ...
  ]
}

Parametros response:

param type desc
payload array Lista de Tipos de Producto
payload.id int Id del tipo
payload.name string Nombre del tipo



Obteniendo lista de Carriers (portadores de los productos)

GET /v1/carriers - lista portadores asignados

Parametros request:

Ninguno

Response:

{
  "payload": [
    {
      "id": 255,
      "name": "Natcom"
    },
    {
      "id": 1,
      "name": "Claro"
    },
    {
      "id": 9,
      "name": "Digicel"
    },
    {
      "id": 10,
      "name": "Clarord"
    },
    {
      "id": 11,
      "name": "Orangerd"
    },
    {
      "id": 37,
      "name": "Viva"
    }
    ...
  ]
}

Parametros response:

param type desc
payload array Lista de Carriers (portadores) asignados
payload.id int ID de Compañía portadora del servicio
payload.name string Nombre del Carrier



Consultando datos de Producto

GET /v1/query - consulta info

Parametros request:

param component type data type desc
productId query required int ID del Producto a consultar
accountNumber query required string Tel/Contrato/Número de Cuenta a consultar

Ejemplo:

Consulta de Paquetes de Datos disponible:

Request:

/v1/query?productId=3149&accountNumber=8095551212

Response:

{
  "payload": [
    {
      "description": "150MB CHAT Y REDES - 1 DIA",
      "detail": "150MB - 7 DIAS - CHAT&REDES",
      "duration": "1 DIA",
      "id": "10169",
      "price": "40",
      "type": "CHAT Y REDES"
    },
    {
      "description": "LIBRE+ 1 DIA",
      "detail": "LIBRE 2 GB",
      "duration": "1 DIA",
      "id": "11215",
      "price": "65",
      "type": "PAQUETES LIBRES PLUS"
    },
    {
      "description": "40MB - 3 HORAS",
      "detail": "40MB - 3 HORAS",
      "duration": "3 HORAS",
      "id": "10160",
      "price": "20",
      "type": "NAV. HORAS"
    },
    {
      "description": "100MB - 7 HORAS",
      "detail": "100MB - 7 HORAS",
      "duration": "7 HORAS",
      "id": "10161",
      "price": "30",
      "type": "NAV. HORAS"
    }
    ...
  ]
}

Consulta de Deuda pendiente de una factura:

Request:

/v1/query?productId=2023&accountNumber=5010345

Response:

{
  "payload": {
    "holderName": "PEREZ MARTINEZ, PEDRO MANUEL",
    "invoiceAmount": "1144.99",
    "invoiceDate": "2024-08-19",
    "minAmount": "1144.99",
    "txnId": "582821456"
  }
}

Parametros response:

param type desc
payload objeto Respuesta de la consulta dependiendo del tipo de producto



Comprando/Pagando un Producto

POST /v1/buy - compra de producto

Parametros request:

param component type data type desc
reference json required string referencia del consumidor API
accountNumber json required string Tel/Contrato/Número de Cuenta a pagar
productId json required int ID del producto a comprar
packageId json optional string ID del paquete de datos a comprar
amount json required decimal Monto a pagar

Ejemplo:

Compra de un TOPUP:

Request:

{
  "reference":"7035922672877862680",
  "accountNumber":"8095551212",
  "productId":357,
  "amount":200,
  "merchant": "21234"
}

Response:

{
  "payload": {
    "authNumber": "644208",
    "txnDatetime": "7/28/2024 10:25:04 AM",
    "txnId": "583307823"
  }
}

Compra de un PIN:

Request:

{
  "reference":"7035922659791649500",
  "productId":201,
  "amount":100,
  "merchant": "21234"
}

Response:

{
  "payload": {
    "authNumber": "1316582",
    "txnDatetime": "7/28/2024 10:25:04 AM",
    "txnId": "583307818",
    "pin": "395614126912",
    "serial": "000005703956227",

  }
}

Compra de Paquete de Datos:

Request:

{
  "reference":"1721827596810",
  "accountNumber":"8292685939",
  "productId":3149,
  "packageId":"10611",
  "amount":50
}

Response:

{
  "payload": {
    "authNumber": "082208",
    "txnDatetime": "20240724092421",
    "txnId": "784877850"
  }
}

Compra de Recarga de Energía:

Request:

{
  "reference":"1721828310130",
  "accountNumber":"6643418",
  "productId":3503,
  "amount":5
}

Response:

{
  "payload": {
    "authNumber": "144984",
    "data": {
      "blk1des": "(0~200kwh)...6.05RD$/kwh",
      "blk1val": "8.3kwh",
      "blk2des": "(201~300kwh)...8.59RD$/kwh",
      "blk2val": "0kwh",
      "blk3des": "(301~700kwh)...12.89RD$/kwh",
      "blk3val": "0kwh",
      "blk4des": "(701~701kwh)...1951.09RD$/kwh",
      "blk4val": "0kwh",
      "blk5des": "(702~...kwh)...13.09RD$/kwh",
      "blk5val": "0kwh",
      "codTarifa": "BTS1",
      "comercio": "UNION TELECARD DOMINICANA",
      "contrato": "6643418",
      "fecha": "2024-07-24 09:36:06.956272905 -0400 BOT m=+85411.293938367",
      "lote": "144984",
      "mode": "Efectivo",
      "monto": "5",
      "montoUnidadRec": "8.3",
      "msg": "Gracias por su recarga",
      "serialMedidor": "014290163493",
      "sumMes": "33.2",
      "titular": "JUAN FRANCISCO CELESTINO DE LA CRUZ",
      "token": "2163-8573-9682-3801-3660",
      "unidadRec": "kWh"
    },
    "txnDatetime": "2024-07-24 09:36:06.956267735 -0400 BOT m=+85411.293933197",
    "txnId": "814246941"
  }
}

Parametros response:

param type desc
payload array Datos de la respuesta
payload.authNumber string Número de autorización del proveedor del servicio
payload.txnDatetime string Fecha de la transacción
payload.txnId string ID generado de la transacción
payload.data object Información adicional con detalles de la compra



Cancelando una compra/pago previa.

POST /v1/txns/cancel - cancelar compra de producto

Parametros request:

param component type data type desc
oldReference json required string referencia de la compra
newReference json required string referencia de cancelación del consumidor API

Request:

{
  "newReference":"1721677185425",
  "oldReference":"1721677154624"
}

Response:

{
  "payload": "Success",
}

Parametros response:

param type desc
payload string Código de respuesta



Consultando transacciones

GET /v1/txns - consulta transacciones

Parametros request:

param component type data type desc
reference query optional int referencia de la transacción a consultar
accountNumber query optional string Tel/Contrato/Número de Cuenta a consultar

Ejemplo:

  • Consulta de transacciones por referencia:
/v1/txns?reference=7017982692562088225
  • Consulta de transacciones por teléfono:
/v1/txns?accountNumber=8095551212

Response:

  • De una consulta por referencia:
{
  "payload": [
    {
      "amount": "60",
      "authNumber": "793931",
      "code": "00",
      "id": 1722344155380855,
      "merchant": 45345,
      "phone": "8095551212",
      "productId": 357,
      "productTypeId": 14,
      "reference": "1722344155031",
      "txnDate": "2024-07-30T16:55:55Z",
      "txnType": "BUY PRODUCT",
      "txnTypeId": 1
    }
  ]
}
  • De una consulta de teléfono:
{
  "payload": [
    {
      "amount": "-60",
      "authNumber": "",
      "code": "00",
      "id": 582629474,
      "merchant": 0,
      "phone": "8095551212",
      "productId": 357,
      "productTypeId": 1,
      "reference": "1721677185425",
      "txnDate": "2024-07-30T16:55:55Z",
      "txnType": "VOID TRASNSACTION",
      "txnTypeId": 2
    },
    {
      "amount": "60",
      "authNumber": "255896",
      "code": "00",
      "id": 582629434,
      "merchant": 0,
      "phone": "8095551212",
      "productId": 357,
      "productTypeId": 1,
      "reference": "1721677154624",
      "txnDate": "2024-07-30T16:55:55Z",
      "txnType": "BUY PRODUCT",
      "txnTypeId": 1
    },
    ...
  ]
}

Parametros response:

param type desc
payload objeto Respuesta de la consulta dependiendo del tipo de producto
payload.amount decimal Monto de la transacción
payload.authNumber string Número de autorización del proveedor del producto
payload.code string Código de respuesta de la transacción
payload.id int ID unico de la transacción
payload.merchant string ID del punto de venta en que se realizó la transacción
payload.phone string Número de cuenta de la transacción (tel/contrato/...)
payload.productId int ID del producto
payload.productTypeId int ID del tipo de producto
payload.reference string referencia del consumidor API
payload.txnDate string Fecha y Hora de la transacción
payload.txnType string Tipo de transacción
payload.txnTypeId int ID del tipo de transacción



HTTP Codes

El sistema usa los códigos de status HTTP para indicar si un request fue exitoso. Si el código HTTP de respuesta es 200, todo funcionó bien. Los siguientes códigos representan otros resultados:

HTTP Code Meaning
200 OK
400 Bad Request, method not supported.
401 Unauthorized, user doesn't have rights.
405 Method not allowed by API. For example, some elements are read-only and cannot accept POST requests.
406 Not acceptable, missing parameters or bad parameters. This is the most common error code when field validation fails for any reason.
409 Conflict, thrown when an API request throws a WARNING and the request was made in strict mode. When not in "strict" mode a WARNING will return a 200. See: Using Extras for Fine-Tuning API Usage for more on strict mode.
422 Unprocessable Entity, thrown when a request couldn't be satisfied.
429 Rate limiting, thrown when an excessive number of requests are made in a short amount of time. Rate limiting is currently applied to the Report Queue and Authentication endpoints.
500 Internal server error, generally problem with the database or system setup.



Casos de Prueba

Estos son casos de prueba espécificos creados para mostrar resultados esperados.

No todos los casos se cubren.


CONSULTA DE DATA PACKAGE

Acción Producto ID No de Cuenta Resultado
query ANY 8095550022 022 - Provider Error
query ANY 8095551313 002 - Cliente NO Tiene Paquetes Disponibles
query ANY 8095559999 NOK - Cliente no encontrado
query ANY 8095558888 TR - UTP TIMEOUT REJECTED
query ANY 8[024]9XXXXXXX 00 - Success

CONSULTA DE FACTURAS

Acción TIPO ID No de Cuenta Resultado
query POST 2023 5010696 00 - Success - 1144.99 - MARTXXX ALCAXXX, MARCOS AUREXXX
query POST 2021 7367899 00 - Success - 543.81 - MILIENNE HILAIRE
query PRE 3503 6643418 00 - Success - 0 - JUAN FRANCISCO CELESTINO DE LA CRUZ
query PRE 3503 6648438 00 - Success - 0 - ISIDRO TRAVIESO NUÑEZ
query PRE 3503 6703389 00 - Success - 0 - MACARRULLA, MARIA MAGDALENA
query ANY ANY XXXXXXX 01 - NIC NO VALIDO

COMPRA DE DATA PACKAGE

Acción ID No de Cuenta Resultado
buy ANY 8095552121 023 - TELEFONO TIENE PRESTAMO PENDIENTE
buy 3149 8095552323 DB2 - UTP INVALID PRODUCT OR AMOUNT FOR THIS ACCOUNT
buy ANY 8095552222 349 - Error en Proveedora consultando Número de Telefono
buy ANY 8[024]9XXXXXXX 00 - Success

PAGO DE FACTURAS

Acción TIPO ID No de Cuenta Resultado
buy POST 2023 5010696 00 - Success
buy POST 2021 7367899 00 - Success
buy PRE 3503 6643418 00 - Success
buy PRE 3503 6648438 00 - Success
buy PRE 3503 6703389 00 - Success
buy PRE 3503 6236683 RP006 - TRANSACCION NO PERMITIDA. (Transaccion repetida)
buy ANY ANY XXXXXXX CP003 - CONTRATO O MEDIDOR NO ENCONTRADO EN EL SISTEMA

COMPRA DE RECARGAS (TOPUP)

Acción ID No de Cuenta Resultado
buy ANY 8095552121 023 - TELEFONO TIENE PRESTAMO PENDIENTE
buy ANY 8095552222 349 - Error en Proveedora consultando número de teléfono
buy ANY 8095552323 DB2 - UTP INVALID PRODUCT OR AMOUNT FOR THIS ACCOUNT
buy ANY 8095552424 020 - Provider Error
buy ANY 8095552525 DB27 - UTP TRANSACTION REJECTED, PHONE RATE LIMIT EXCEEDED

COMPRA DE PINES

Acción ID No de Cuenta Resultado
buy ANY 00 - Success

CANCELACIÓN

Acción oldReference newReference Resultado
cancel xxxxxx 1234567890 1 - Error en Prepago reversando bolsillo:0 Balance Disponible 14.06