Submenu desarrolladores

API REST de Servicios

A continuación se especifica la API de Servicios Adicionales de Tuidd, que será consumida por los proveedores de servicios a en sus sitios o aplicaciones.

Son los servicios adicionales al servicio de autenticación de un usuario, cuya especificación se puede consultar en API REST de Autenticación . En detalle:

  • Micropagos

  • Publicidad

  • Encuestas

  • Cupones

  • Notificaciones

Esta lista no es definitiva, y nuevos servicios podrán agregarse en el futuro.

 

Consumo de un Servicio

Los servicios se consumen mediante un punto de acceso común. Dependiendo de la configuración enviada, es el servicio que se efectuará.

 

Requerimiento

HTTP Method:

POST

URI:

service

Ejemplo:

POST https://idgw.tuidd.com/service

Headers:

Header

Valor

Requerido

Descripción

Authorization

Bearer $pass

Obligatorio

Base64( client_id:client_secret ) obtenido en el Discovery. Ver API REST de Autenticación

Content-type

Application/ json

Obligatorio

 

 

Body:

Campo

Tipo

Requerido

Descripción

service_token

String

Obligatorio

UUID recibido por la API de autenticación. Para determinados servicios, puede ser un token propio del sitio o emprendimiento.

seq_num

Int

Obligatorio

Se utiliza en caso de que una transacción requiera enviar más de un mensaje al usuario. Toma valores de 0 - 1000. El primer valor es ramdom, los siguientes secuenciales.

state

String

Obligatorio

String definidos por el proveedor de servicios, como valor de contexto para identificar una transacción al recibir una notificación (ver Notificación de Servicio ).

notification_uri

String

Condicional

Url donde se reciben las notificaciones (ver Notificación de Servicio ). Sólo se requiere para los servicios de tipo: payment, notification . Debe coincidir con la URL de Retorno, configurada en el sitio de administración de Tuidd.

login_hint

String

Obligatorio

Indica al servidor que ID del destinario del servicio. El formato es el siguiente:

PCR:<valor del PCR>

Ejemplo:

PCR: d5f38a8fcc52e931d4fb4da47b2f2bb0

service_type

String

Obligatorio

Tipo del servicio a consumir. Los valores posibles son:

     advertising : Publicidad.

    notification : Notificación.

    payment : pago.

    survey : Encuestas.

    coupon : Cupón.

service_info

Object

Obligatorio

Objeto JSON con los detalles del servicio a consumir. Ver Definición de Objetos de Servicios .

display

String

Opcional

Indica de qué manera se mostrarán al usuario las pantallas con la información del servicio:

    push : se enviará un mensaje al PUSH al usuario, de acuerdo al canal definido por el operador.

    url_redirect : se hará un redirect al usuario a una página WEB

constraints

Arreglo

Opcional

Indica un conjunto de restricciones o condiciones forzadas que el servicio tendrá que tener en cuenta a la hora de ejecutarse.

El listado de los valores posibles que puede tomar este campo, dependerá de cada servicio.

Ejemplo: ["no-repeat", "force-filter", ...]

 

Respuesta

Se devuelve un código de respuesta HTTP, según el resultado, de acuerdo a lo definido en Códigos de Respuesta .

 

Adicionalmente, se incluye en el body, información en formato JSON con una estructura común a todos los servicios:

 

Campo

Tipo

Requerido

Descripción

status

Objeto

Obligatorio

Objeto compuesto con la información de status. Ver definición de objeto status .

service_id

Int

Obligatorio

Id del servicio consumido.

transaction_id

String

Obligatorio

Identificación de la transacción en la plataforma MCG.

seq_num

Int

Obligatorio

Valor del 0-1000. Es el mismo pasado en el requerimiento.

url_redirect

String

Opcional

Es la URL a la cual se va a redirigir al usuario para mostrarle las pantallas del servicio.

 

 

Notificación de Servicio

 

Cuando se consume un servicio que genera un proceso asíncrono (por ejemplo: Micropago), el proveedor genera un requerimiento a la plataforma mediante la presente API de servicios, y se le retorna un ID de transacción ( transaction_id ).

 

Una vez finalizado el proceso del lado del servidor, de manera asíncrona, se le notifica a la plataforma del proveedor que dicha transacción terminó y cuál fue el estado de la misma. Para ello, se le envía de tipo JSON al endpoint de notificaciones que indicó el proveedor en el requerimiento del servicio original, en el campo notification_uri .

 

En caso de falla en la recepción de la notificación (sin respuesta), la misma se reintentará tan solo 1 vez a los 2 minutos, y posteriormente se descartará. En caso de recibir cualquier otra respuesta de error, no se reintentará.

Requerimiento

HTTP Method:

         POST

Endpoint:

notification_uri pasado en el requerimiento del consumo del servicio

 

Headers:

 

Header

Valor

Requerido

Descripción

Authorization

Bearer $pass

Obligatorio

$pass = base64(<client_id>:< client_secret>)

Content-type

Application/json

Obligatorio

 

 

Body:

 

Campo

Tipo

Requerido

Descripción

state

String

Obligatorio

String definidos por el proveedor de servicios, como valor de contexto pasado en el requerimiento original del servicio.

transaction_id

String

Obligatorio

Identificación de la transacción en la plataforma MCG.

service_type

String

Obligatorio

Tipo del servicio consumido. Los valores posibles son:

advertising : Publicidad.

notification : Notificación.

payment : pago.

survey : Encuestas.

coupon : Cupón.

authentication : Autenticación

status

Objeto

Obligatorio

Detalle del estado de finalización del proceso. Ver en Definición de Objetos Generales .

notification_data

Objeto

Obligatorio

Respuesta especifica del servicio consumido.

 

Respuesta

 

Se devuelve un código de respuesta HTTP, sin ninguna información adicional. Ver Códigos de respuesta .

 

Códigos de Respuesta

 

Código

Status

Descripción

200

OK

Código de respuesta exitoso de uso general. Es el código más común. Es usado para indicar le éxito de la operación.

400

BAD REQUEST

Error general para cuando se genera un estado inválido procesando la petición. Por ejemplo, errores en las validaciones del dominio, falta de información obligatoria, etc.

401

UNAUTHORIZED

Error generado cuando no se encontró el token de autenticación o el mismo es inválido, o bien las credenciales client_id:client_secret son inválidas.

500

INTERNAL SERVER ERROR

Error inesperado en el servidor. Posiblemente deba reintentar la operación en otro momento, y en caso de persistir el error, contactarse con el soporte de la plataforma.

 

 

Objetos Generales

 

A continuación se describen los objetos JSON que se manejan a nivel general en la plataforma:

status  

Campo

Tipo

Requerido

Descripción

result

String

Obligatorio

Indica si la operación salió OK o no. Valores posibles: OK, NOK

error_data

Objeto

Obligatorio

Detalle del error

 

error_data

Campo

Tipo

Requerido

Descripción

error

String

Obligatorio

Nombre identificador del error

error_description

String

Obligatorio

Descripción del error


   

Objetos de Servicios

 

A continuación se describen los objetos JSON que representan los datos de los servicios.

 

En todos los casos, existen 2 formas de pasar los detalles de un servicio:

1. Indicando el identificador de un servicio cargado en la plataforma por el proveedor de servicio.

2. Indicando todos los parámetros que tendrá el servicio.

 

advertisement

Representa una publicidad.

Los campos son:

Campo

Tipo

Requerido

Descripción

service_id

String

Obligatorio

Es el identificador de una publicidad registrada por el proveedor.

title

String

Opcional

Titulo de la Publicidad no mayor a 32 caracteres.

message

String

Opcional

Texto del mensaje de publicidad. No mayor a 166 caracteres.

link

String

Opcional

URL del sitio a donde redirigir al usuario en caso de hacer click en la publicidad.

link_text

String

Opcional

Texto que figura en el botón que lleva al usuario a la URL configurada en el parámetro “link”.

image_link

String

Opcional

URL de la imagen que aparecerá en la publicidad. Debe ir en URL Encoding.

Dependiendo del canal, puede estar disponible o no.

redirect_link

String

Opcional

URL del sitio a donde redirigir al usuario luego de que se muestre la publicidad.

source

String

Opcional

Restringe el origen de la publicidad, para indicar si se desea recibir publicidad propia solamente o también de terceros.

Los valores posibles son:

  • own : Publicidad propia.
  • third-party : Publicidad de terceros.
  • any : Cualquier tipo de publicdad (own o third-party).
  • service_id : Especificamente la publicidad indicada en el service_id.

Si no se especifica este campo el valor por defecto es any

 

 

payment

Es el cuerpo de la solicitud de pago que se le enviara al usuario:

Campo

Tipo

Requerido

Descripción

price

Number

Obligatorio

Monto a pagar. Separador de decimales con punto y hasta dos decimales.

Ejemplo: 2.99

detail

String

Obligatorio

Una breve descripción de que se está pagando.

concept

String

Obligatorio

El concepto que generó la solicitud de pago.

currency

String

Obligatorio

Código de la moneda con la que opera en formato ISO 4217 alfa-3.

Ejemplo: USD

 

notification

Representa una notificación.

Los campos son:  

Campo

Tipo

Requerido

Descripción

service_id

String

Obligatorio

Es el identificador de la notificación registrada por el proveedor.

title

String

Opcional

Titulo de la notificación no mayor a 32 caracteres.

message

String

Opcional

Contenido de la notificación. No mayor a 166 caracteres.

need_confirm

String

Opcional

Indica si debe o no recibir confirmación de parte del usuario. Valores posibles: "true" / "false"

confirm_text

String

Opcional

Texto del botón de confirmación que se mostrará al usuario.

link

String

Opcional

Link a donde se quiere dirigir al usuario en caso de aceptar la notificación. Dependiendo del canal, este link puede ser parte del mensaje

 

 

coupon

  Representa un cupón de beneficios:

Campo

Tipo

Requerido

Descripción

service_id

String

Obligatorio

Es el identificador de un cupón registrado por el proveedor.

title

String

Opcional

Titulo del cupón mayor a 32 caracteres.

message

String

Opcional

Texto del mensaje del cupón. No mayor a 166 caracteres.

coupon_type

String

Opcional

Indica el tipo de cupón a utilizar. Los valores posibles son:

qr_code : lo que se le debe enviar al usuario es un código QR.

pin_code : lo que se le debe enviar al usuario es un PIN. Los pines generados son alfanuméricos.

 

link

String

Opcional

URL dle sitio a donde se quiere redirigir al usuario en caso de hacer click en el cupón.

image_link

String

Opcional

URL de la imagen que aparecerá en el cupón. Debe ir en URL Encoding. Dependiendo del canal, esta imagen puede estar disponible o no.

action

String

Obligatorio

Indica el tipo de acción:

generate: generar un nuevo cupón.

consume:consumir un cupón

coupon_code

String

Condicional

Indica el PIN o código QR que el proveedor quiere consumir. Es obligatorio si “action” = “consume”

 

 

survey

 Representa una encuesta. Los campos son:

Campo

Tipo

Requerido

Descripción

service_id

String

Condicional

Es el identificador de una encuesta registrada por el proveedor.

 

Nota: para este servicio, a diferencia de los otros, no se pueden enviar encuestas que no estén registradas previamente.

 

 

Orden: 
11

Entity Pager Example