Services REST API
Next, the Additional Services API of Tuidd is specified, which will be consumed by the service providers in their sites or applications.
They are the additional services to the authentication service of a user, whose specification can be consulted in Authentication REST API . In detail:
-
Micropayments
-
Advertising
-
Surveys
-
Coupons
-
Notifications
This list is not final, and new services may be added in the future.
The services are consumed through a common access point. Depending on the configuration sent, it is the service that will be performed.
Request
HTTP Method:
POST
URI:
service
Example:
POST https://idgw.tuidd.com/service
Headers:
|
Header |
Value |
Required |
Description |
|
Authorization |
Bearer $pass |
Required |
Base64( client_id:client_secret ) obtained at Discovery. Watch Authentication REST API . |
|
Content-type |
Application/ json |
Required |
Body:
|
Field |
Type |
Required |
Description |
|
service_token |
String |
Required |
UUID received by the authentication API. For certain services, it can be a token specific to the site or enterprise. |
|
seq_num |
Int |
Required |
It is used in case a transaction requires sending more than one message to the user. It takes values of 0 â ???? 1000. The first value is ramdom, the following sequential. |
|
state |
String |
Required |
Strings defined by the service provider, as a context value to identify a transaction upon receipt of a notification (see Service Notification ). |
|
notification_uri |
String |
Conditional |
Url where the notifications are received (see Service Notification ). It is only Required for type services: payment, notification . It must match the Return URL, configured on the Tuidd administration site. |
|
login_hint |
String |
Required |
Tells the server which ID of the service recipient. The format is as follows: PCR:<valor del PCR> Example: PCR: d5f38a8fcc52e931d4fb4da47b2f2bb0 |
|
service_type |
String |
Required |
Type of service to consume. The possible values are: advertising : Advertising. notification : Notification payment : payment. survey : Surveys coupon : Coupon |
|
service_info |
Object |
Required |
JSON object with the details of the service to be consumed. Watch Definition of Service Objects . |
|
display |
String |
Optional |
Indicates how the screens with the service information will be shown to the user: push : a message will be sent to the PUSH to the user, according to the channel defined by the operator. url_redirect : a redirect will be made to the user to a WEB page |
|
constraints |
Array |
Optional |
Indicates a set of constraints or forced conditions that the service will have to take into account when executing. The list of possible values that this field can take depends on each service. Exaple: ["no-repeat", "force-filter", ...] |
Answer
An HTTP response code is returned, depending on the result, as defined in Answer Codes .
Additionally, information in JSON format with a structure common to all services is included in the body:
|
Field |
Type |
Required |
Description |
|
status |
Object |
Required |
Object composed with the status information. See object definition status . |
|
service_id |
Int |
Required |
Id of the service consumed. |
|
transaction_id |
String |
Required |
Identification of the transaction in the MCG platform. |
|
seq_num |
Int |
Required |
Value of 0-1000. It is the same last in the requirement. |
|
url_redirect |
String |
Optional |
It is the URL to which the user will be redirected to show the service screens. |
When a service that generates an asynchronous process is consumed (for example: Micropayment), the provider generates a requirement to the platform through this service API, and a transaction ID is returned ( transaction_id ).
Once the server-side process is completed, asynchronously, the provider's platform is notified that the transaction has ended and the status of the transaction. To do this, it is sent as a JSON type to the notifications endpoint indicated by the provider in the original service request, in the field notification_uri .
In case of failure to receive the notification (no response), it will be re-attempted only once in 2 minutes, and then discarded. In case of receiving any other error response, it will not be retried.
Request
HTTP Method:
POST
Endpoint:
notification_uri passed on the requirement of service consumption
Headers:
|
Header |
Value |
Required |
Description |
|
Authorization |
Bearer $ pass |
Required |
$pass = base64(<client_id>:< client_secret>) |
|
Content-type |
Application/json |
Required |
|
Body:
|
Field |
Type |
Required |
Description |
|
state |
String |
Required |
Strings defined by the service provider, as a context value passed in the original service requirement. |
|
transaction_id |
String |
Required |
Identification of the transaction in the MCG platform. |
|
service_type |
Int |
Required |
Type of service consumed. The possible values are: advertising : Advertising. notification : Notification payment : payment. survey : Surveys coupon : Coupon authentication : Authentication |
|
status |
Object |
Required |
Detail of the state of completion of the process. To see in Definition of General Objects . |
|
notification_data |
Object |
Required |
Specific response of the service consumed. |
Answer
An HTTP response code is returned, without any additional information. Watch Answer codes .
Answer Codes
|
Code |
Status |
Description |
|
200 |
OK |
Successful response code for general use. It is the most common code. It is used to indicate the success of the operation. |
|
400 |
BAD REQUEST |
General error for when an invalid state is generated processing the request. For example, errors in domain validations, lack of mandatory information, etc. |
|
401 |
UNAUTHORIZED |
Error generated when the authentication token was not found or the authentication token is invalid, or the client_id: client_secret credentials are invalid. |
|
500 |
INTERNAL SERVER ERROR |
Unexpected error on the server. Possibly you should retry the operation at another time, and in case of persisting the error, contact the support of the platform. |
The following describes the JSON objects that are generally handled in the platform:
status
|
Field |
Type |
Required |
Description |
|
String |
Required |
Indicates whether the operation went OK or not. Possible values: OK, NOK |
|
|
Object |
Required |
Detail of the error |
error_data
|
Field |
Type |
Required |
Description |
|
String |
Required |
Identifier name of the error |
|
|
String |
Required |
Description of the error |
The following describes the JSON objects that represent the data of the services.
In all cases, there are 2 ways to pass the details of a service:
1. Indicating the identifier of a service loaded on the platform by the service provider.
2. Indicating all the parameters that the service will have.
advertisement
It represents an advertisement.
The fields are:
|
Field |
Type |
Required |
Description |
|
service_id |
String |
Required |
It is the identifier of an advertisement registered by the provider. |
|
title |
String |
Optional |
Title of the Advertising no greater than 32 characters. |
|
message |
String |
Optional |
Text of the advertising message. No greater than 166 characters. |
|
link |
String |
Optional |
URL of the site to redirect the user in case of clicking on the advertising. |
|
link_text |
String |
Optional |
Text that appears on the button that takes the user to the URL configured in the "link" parameter. |
|
image_link |
String |
Optional |
URL of the image that will appear in the advertisement. It must go in URL Encoding. Depending on the channel, it may or may not be available |
|
redirect_link |
String |
Optional |
URL of the image that will appear in the advertisement. It must go in URL Encoding. |
|
source |
String |
Optional |
Restrict the origin of the advertising, to indicate whether you want to receive your own advertising or third parties. Possible values are:
If this field is not specified, the default value is any |
payment
It is the body of the payment request that will be sent to the user:
|
Field |
Type |
Required |
Description |
|
price |
Float |
Required |
Amount payable. |
|
detail |
String |
Required |
A brief description of what is being paid. |
|
concept |
String |
Required |
The concept that generated the request for payment. |
|
currency |
String |
Required |
Codes of the currency with which it operates in ISO 4217 alpha-3 format. Example: USD |
notification
Represents a notification.
The fields are:
|
Field |
Type |
Required |
Description |
|
service_id |
String |
Required |
It is the identifier of the notification registered by the provider. |
|
title |
String |
Optional |
Title of the notification not greater than 32 characters. |
|
message |
String |
Optional |
Content of the notification. No greater than 166 characters. |
|
need_confirm |
String |
Optional |
Indicates whether or not to receive confirmation from the user. Possible values: "true" / "false" |
|
confirm_text |
String |
Optional |
Text of the confirmation button that will be shown to the user. |
|
link |
String |
Optional |
Link to where you want to direct the user in case of accepting the notification. Depending on the channel, this link can be part of the message |
coupon
Represents a benefit coupon:
|
Field |
Type |
Required |
Description |
|
service_id |
String |
Required |
It is the identifier of a coupon registered by the provider. |
|
title |
String |
Optional |
Title of the coupon greater than 32 characters. |
|
message |
String |
Optional |
Text of the coupon message. No greater than 166 characters. |
|
coupon_type |
String |
Optional |
Indicates the type of coupon to be used. The possible values are: qr_code : what should be sent to the user is a QR code. pin_code : what should be sent to the user is a PIN. The pins generated are alphanumeric.
|
|
link |
String |
Optional |
URL of the site where you want to redirect the user in case of clicking on the coupon. |
|
image_link |
String |
Optional |
URL of the image that will appear on the coupon. It must go in URL Encoding. Depending on the channel, this image may or may not be available. |
|
action |
String |
Required |
Indicates the type of action: generate: generate a new coupon. consume: consume a coupon |
|
coupon_code |
String |
Conditional |
Indicates the PIN or QR code that the provider wants to consume. It is mandatory if "action" = "consume" |
survey
Represents a survey The fields are:
|
Field |
Type |
Required |
Description |
|
service_id |
String |
Conditional |
It is the identifier of a survey registered by the provider. |
Note: for this service, unlike the others, you can not send surveys that are not previously registered.