Documentaciónv2.0

Bienvenido al API de Reportes de UTP. Aquí encontrará información detallada sobre el API. Este contiene documentación e instrucciones paso a paso de cada endpoint y la información detallada que se debe enviar y que se recibirá en cada petición.

Ambientes

Sandbox. UTP mantiene un sandbox que permite a los desarrolladores probar el API utilizando datos simulados. Tener en cuenta que la lista de productos no está sincronizada con producción.

Para realizar solicitudes al entorno sandbox, utilice la siguiente URL: https://dev.reports.api.utelecard.com
Producción. Una vez que haya completado todas las pruebas necesarias en el sandbox, contáctenos para recibir sus claves de producción.

Para realizar solicitudes al entorno de producción, utilice la siguiente URL: https://reports.api.utelecard.com

Nota: El tiempo máximo de espera para todas las solicitudes es de 45 segundos.

Seguridad

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

Nota: Por razones de seguridad, nuestro 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:

Accept el tipo MIME que sea aceptable para la respuesta. Para todas sus solicitudes, siempre enviará application/json
Content-Type Indica el tipo MIME del cuerpo de la entidad enviado al destinatario. Ejemplo application/x-www-form-urlencoded
Date Representa la fecha y la hora en que se originó el mensaje. Este formato de encabezado se especifica en RFC 822 Sección 5. Por ejemplo: Wed, 12 Jan 2022 150409 GMT
Authorization Credenciales de autenticación, este encabezado tiene la siguiente forma:

Bearer <usuario>:<checksum>

Nota: Las solicitudes son válidas durante 15 minutos, por lo tanto, configure el encabezado de fecha con la fecha y hora actual.

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 un checksum construida a partir del endpoint, los encabezados HTTP y su clave secreta.

En la siguiente sección, aprenderá a calcular <checksum> para todas sus solicitudes de API.

Cálculo de checksum

Paso 1

El <checksum-string> se crea utilizando las siguientes cabeceras HTTP

Content-Type
Date

Y el Endpoint que desea acceder. Este checksum tiene la forma:

<checksum-string> = "<Content-Type>,<Endpoint>,<Date>"

Por ejemplo:

<Content-Type> = "application/x-www-form-urlencoded"
<Endpoint> = "/v2/account"
<Date> = "Wed, 12 Jan 2022 15:04:09 GMT"

Esto produce:

<checksum-string> = "application/x-www-form-urlencoded,/v2/account,Wed, 12 Jan 2022 15:04:09 GMT"

Paso 2

<checksum> es un HMAC codificado en Base64. El HMAC utiliza SHA-1 como función hash y <tu-clave-secreta> como llave criptográfica.

Puede usar OpenSSL para calcular la comprobación en el shell:

echo -n "<checksum-string>" | openssl dgst -sha1 -binary -hmac '<tu-clave-secreta>' | base64

Por ejemplo:

<checksum-string> = "application/x-www-form-urlencoded,/v2/account,Wed, 12 Jan 2022 19:00:51 GMT"
<tu-clave-secreta> = "clave-muy-secreta"

Produce: `tLqh8GwxMqVj56388mPulXecRiI=`

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/x-www-form-urlencoded.

Como hacer una llamada API

El endpoint /account mostrará la información de su cuenta. Es una excelente manera de aprender a realizar solicitudes. Para este ejemplo, vamos a utilizar la herramienta curl.

Genere un shell script, escriba los pasos 1 y 2:

1. Genere el checksum reemplazando <su-clave-secreta> con la clave secreta que se le proporcionó.

CURRENT_DATE=`date -Ru | sed 's/+0000/GMT/'`
CHECKSUM=$(echo -n "application/x-www-form-urlencoded,/v2/account,$CURRENT_DATE" \
  | openssl dgst -sha1 -binary -hmac "<su-clave-secreta>" \
  | base64)

2. Envíe su solicitud al entorno deseado. Reemplace <usuario> con el proporcionado.

curl -X GET "https://reports.api.utelecard.com/v2/account" \
  -H "Accept: application/json" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Date: $CURRENT_DATE" \
  -H "Authorization: Bearer <usuario>:$CHECKSUM"

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

{
  "id":963,
  "name":"SUPERVENTAS S.R.L.",
  "status":"ACTIVE",
  "ctry":"DO",
  "ccy":"DOP",
  "balance":"463659.18",
  "credit": "10000000"
}

Paginación

Algunos endpoints como /txns, /products tienen resultados extensos y estos resultados se dividen en páginas. Maneje la paginación usando el encabezado X-Pagination y solicitando páginas subsiguientes.

El objeto X-Pagination contiene la estructura:

Propiedad	Tipo	Descripción
entries	int	Total de entradas en el resultado
page.count	int	Total de páginas
page.prev	int	Número de la página anterior
page.current	int	Número de la página actual
page.next	int	Número de la página siguiente

Resultado de ejemplo:

{
  "entries":6745,
  "page":{
    "count":7,
    "prev":2,
    "current":3,
    "next":4
  }
}

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

Endpoints

Account

`GET` /v2/account - Retorna las propiedades de tu cuenta.

Devuelve las propiedades de su cuenta. Esto incluye el nombre de tu empresa y tanto el balance actual que nos debe como la cantidad máxima de crédito permitida en su cuenta en su moneda local.

Parámetros:

ninguno

Respuesta:

Propiedad	Tipo	Descripción
id	int	ID númerico de tu cuenta
name	string	Nombre de tu cuenta
status	string	Estado de tu cuenta [ACTIVE \| DISABLED]
country	string	ISO 3166-1 alpha-2 del país de la cuenta
currency	string	ISO 4217 de la moneda de tu cuenta
balance	string	Balance actual de tu cuenta
credit	string	Límite de Crédito de tu cuenta

Ejemplo de respuesta:

{
  "id":963,
  "name":"SUPERVENTAS S.R.L.",
  "status":"ACTIVE",
  "country":"DO",
  "currency":"DOP",
  "balance":"463659.18",
  "credit": "10000000"
}

Productos

`GET` /v2/products - Lista de productos de tu cuenta.

Devuelve la lista de productos de su cuenta. Esto incluye el ID, nombre y tipo de producto.

Parámetros:

ninguno

Respuesta:

Propiedad	Tipo	Descripción
id	int	ID númerico del producto
name	string	Nombre del producto
typeId	int	ID del tipo de producto
type	string	Nombre del tipo de producto

Ejemplo de respuesta:

[
  {
    "id": 2944,
    "name": "DATA PACKAGE ORANGERD"
    "type": "DATA PACKAGE"
    "typeId": 14
  },
  {
    "id": 143,
    "name": "DOMINICAN REPUBLIC TRICOM ALTICE"
    "type": "LOCAL PIN"
    "typeId": 6
  },
  {
    "id": 1743,
    "name": "DOMINICAN REPUBLIC ORANGE"
    "type": "RECHARGE"
    "typeId": 1
  },
  .
  .
  .
  {
    "id": 121,
    "name": "HAITI DIGICEL"
    "type": "RECHARGE"
    "typeId": 1
  }
]

Tipos de Producto

`GET` /v2/products/types - Lista de tipos de producto de tu cuenta.

Devuelve la lista de los tipos de producto de su cuenta. Esto incluye el ID y nombre.

Parámetros:

ninguno

Respuesta:

Propiedad	Tipo	Descripción
id	int	ID númerico del tipo de producto
name	string	Nombre del tipo de producto

Ejemplo de respuesta:

[
  {
    "id": 6,
    "name": "LOCAL PIN"
  },
  {
    "id": 14,
    "name": "DATA PACKAGE"
  },
  {
    "id": 1,
    "name": "RECHARGE"
  }
]

Transacciones

`GET` /v2/txns - Reporte de transacciones por rango de fecha

Devuelve una lista de transacciones procesadas en una página de 100 resultados. Puede proporcionar varios criterios de búsqueda, incluida la referencia y el rango de tiempo. Debe proporcionar los parámetros timeframe ó (since y until), debe seguir uno de los siguientes formatos:

YYYY-MM-DDThh:mm:ss
YYYY-MM-DD - Si este formato es enviado en since este será completado como YYYY-MM-DDT00:00:00, si es usado en until, será completado como YYYY-MM-DDT23:59:59.

Parámetros:

Nombre	Tipo	Requerido	Descripción
ref	string	No	Consulta una transacción usando la referencia proporcionada.
page	int	No	Muestra la página seleccionada.
timeframe	string	No	Rango de tiempo pre establecido. `today \| yesterday \| thisWeek \| lastWeek \| thisMonth \| lastMonth`
since	string	No	Fecha y hora de inicio de reporte en formato ISO 8601. `YYYY-MM-DDThh:mm:ss`
until	string	No	Fecha y hora de fin de reporte en formato ISO 8601. `YYYY-MM-DDThh:mm:ss`
groupBy	string	No	Agrupa las transacciones. `date`: por fecha (día) `denom`: por denominación de compra `product`: por producto `productType`: por tipo de producto `store`: por merchant ó comercio
productId	int	No	Muestra las transacciones de este ID de producto.
productTypeId	int	No	Muestra las transacciones de este tipo de producto.
showAll	boolean	No	Muestra todas las transacciones. (exitosas y fallidas)
csv	boolean	No	Genera el reporte solicitado en formato CSV

Ejemplo de solicitud:

/txns?since=2022-01-11T00:00:00&until=2022-01-12T19:00:00&page=3
/txns?timeframe=last-week&page=1
/txns?timeframe=last-week&groupBy=product
/txns?ref=8075560024012307130

Respuesta:

La respuesta es una colección o arreglo del objeto

Propiedad	Tipo	Descripción
ref	string	Referencia de la transacción.
mer	string	ID del comercio.
begin	string	Fecha y hora de inicio de la transacción.
end	string	Fecha y hora de final de la transacción.
type	string	Tipo de producto.
productID	int	ID del producto.
product	string	Nombre del producto.
tel	string	Teléfono o cuenta afectado en la transacción.
amount	decimal string	Monto de la transacción.
discountPct	decimal string	Porciento de Descuento.
discount	decimal string	Monto de Descuento.
country	string	ISO 3166-1 alpha-2 del país de la cuenta
currency	string	ISO 4217 de la moneda de tu cuenta
isVoided	bool	Es una venta cancelada?
code	string	Código de respuesta del proveedor.
msg	string	Mensaje con descripción de la respuesta.

Ejemplo de respuesta:

Cabeceras importantes:

X-Pagination: {"entries":8160,"page":{"count":9,"prev":2,"current":3,"next":4}}
X-Runtime: 328.934916ms

Contenido:

[
  {
    "ref":"6347472975263999717",
    "mer":"42725",
    "begin":"2022-01-11T13:21:55",
    "end":"2022-01-11T13:21:56",
    "type":"RECHARGE",
    "productID":39101,
    "product":"ORANGE",
    "tel":"8099807148",
    "amount":"100",
    "discount": "8.75",
    "discountPct": "8.75",
    "country":"DO",
    "currency":"DOP",
    "code":"00",
    "msg":"Success"
  },
  .
  .
  .
  {
    "ref":"6347994898481833925",
    "mer":"26565",
    "begin":"2022-01-12T09:58:06",
    "end":"2022-01-12T09:58:08",
    "type":"DATA PACKAGE",
    "productID":45587,
    "product":"CLARORD",
    "tel":"8093941320",
    "amount":140,
    "discount": "12.25",
    "discountPct": "8.75",
    "country":"DO",
    "currency":"DOP",
    "code":"349",
    "msg":"Error en CLARO consultando Numero de Telefono"
  }
]

Códigos de Error

El API usa los siguientes códigos de error HTTP.

Código	Status	Descripción
200	OK	La solicitud fue exitosa.
400	Bad Request	Algo está mal con la solicitud.
401	Unauthorized	Su usuario o checksum son inválidos, o su IP no se encuentra en la lista de acceso.
403	Forbidden	No está autorizado para acceder al recurso solicitado.
404	Not Found	El recurso especificado no pudo encontrarse.
429	Too Many Requests	Está enviando demasiadas solicitudes! Frene!
500	Internal Server Error	Tenemos un problema con nuestros servidores. Trate mas tarde.
503	Service Unavailable	Por favor trate mas tarde.

Documentaciónv2.0

Ambientes

Seguridad

Autenticación

Cálculo de checksum

Paso 1

Por ejemplo:

Esto produce:

Paso 2

Por ejemplo:

Produce: tLqh8GwxMqVj56388mPulXecRiI=

Como hacer una llamada API

Paginación

Resultado de ejemplo:

Tiempo de Ejecución

Ejemplo:

Endpoints

Account

GET /v2/account - Retorna las propiedades de tu cuenta.

Parámetros:

Respuesta:

Ejemplo de respuesta:

Productos

GET /v2/products - Lista de productos de tu cuenta.

Parámetros:

Respuesta:

Ejemplo de respuesta:

Tipos de Producto

GET /v2/products/types - Lista de tipos de producto de tu cuenta.

Parámetros:

Respuesta:

Ejemplo de respuesta:

Transacciones

GET /v2/txns - Reporte de transacciones por rango de fecha

Parámetros:

Ejemplo de solicitud:

Respuesta:

Ejemplo de respuesta:

Códigos de Error

1.1.0 - 2023-12-08

2.0.0 - 2024-01-10

Actualizado el 2024-01-10T10:46:45-04:00 por deferbot.

Actualizado el 2024-01-22T12:18:23-04:00 por deferbot.

Produce: `tLqh8GwxMqVj56388mPulXecRiI=`

`GET` /v2/account - Retorna las propiedades de tu cuenta.

`GET` /v2/products - Lista de productos de tu cuenta.

`GET` /v2/products/types - Lista de tipos de producto de tu cuenta.

`GET` /v2/txns - Reporte de transacciones por rango de fecha