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.
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. |
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. |
A continuación se describen los objetos JSON que se manejan a nivel general en la plataforma:
status
|
Campo |
Tipo |
Requerido |
Descripción |
|
String |
Obligatorio |
Indica si la operación salió OK o no. Valores posibles: OK, NOK |
|
|
Objeto |
Obligatorio |
Detalle del error |
error_data
|
Campo |
Tipo |
Requerido |
Descripción |
|
String |
Obligatorio |
Nombre identificador del error |
|
|
String |
Obligatorio |
Descripción del error |
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:
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.