Web Services use the REST technology through POST Method (https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST).
If the client identifies itself as the supporting via the header HTTP Accept-Encoding : gzip,deflate, the response will be compressed.
The header Content-Type: application/json is also required for POST requests, so the request body should match JSON format (https://www.json.org/)
For GET requests, the body is not needed and won't be processed.
Please check this page API rate limits
Messages security is guaranteed by the complementary use of the TLS and using JWT as authentication method in the request ( https://tools.ietf.org/html/rfc7519 ).
To authenticate the calling system, we use the JWT as Bearer token in the HTTP Authorization request header. Check https://developer.mozilla.org/es/docs/Web/HTTP/Authentication and https://tools.ietf.org/html/rfc6750 for more info.
Example of security HTTP header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT1NBIiwiYXVkIjoiTU9TQV9CMkMiLCJpc3MiOiJQYXJ0bmVyIDEiLCJpYXQiOjE2MDA2OTU0ODUsImV4cCI6MTYzMjIzMTQ4MH0.jMQIXbXdswPj-_-x2C2xhhR6Wtieq5JcVfCW4ndSr1oImportant notice:
The login and passwords provided by S-360 are confidential and need to be secured by the partner to whom they are provided.
The authentication is done by forging a JWT following these specs:
alg): HS256typ): JWTsub): Institution Codeaud): Virtual Operatoriss): Partner Nameiat): Forge datetime in epoch millis. This timestamp should be less than 1 second when S-360's endpoint receives the callexp): Expiration time of the token in epoch millis. Each token can have an expiration time of 30 seconds after the issued time.To generate a valid JWT, you should call to the auth endpoint described in the documentation
For testing purposes, you can use our tool here
To decode and debug the JWT, you can use the tool in https://jwt.io/
Encoded JWT
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJNT1NBIiwiYXVkIjoiTU9TQV9CMkMiLCJpc3MiOiJQYXJ0bmVyIDEiLCJpYXQiOjE2MDA2OTU0ODUsImV4cCI6MTYzMjIzMTQ4MH0.jMQIXbXdswPj-_-x2C2xhhR6Wtieq5JcVfCW4ndSr1oHeader
{
"alg": "HS256",
"typ": "JWT"
}Payload
{
"sub": "MOSA",
"aud": "MOSA_B2C",
"iss": "Partner 1",
"iat": 1600949809,
"exp": 1600949829
}Secret key
your-256-bit-secretThe use of TLS guarantees the confidentiality and integrity of the data transmitted on the internet. From of client standpoint, the only need is to have an http client able to call Web Services via https://
Mostly REST Web Services are accessible via the following URL:
https://<institCode>.ws.secutix.com/<module>/backend-apis/<serviceName>/<version>/<method>
Example: https://mosa.demo-ws.secutix.com/tnco/backend-apis/contactInformationPublicService/v2_22/getContactData
Please note: the service’s version is part of the path
Other services can be found at Swagger Documentation
All services follow the same convention. An answer always includes a technical status as well as “business” data when those can be sent back.
Unless otherwise specified, all methods are transactionnal and idempotent.
The response will be served in JSON format with HTTP headers Content-type: application/json and Content-Encoding: UTF-8
Every response will include a HTTP status code with the following meanings:
A correct response (status 200) always includes the following elements (WebMethodResult):
| Name | Type | Description |
|---|---|---|
| statusCode | String |
This status code tells whether the request has been correctly implemented. List of codes here. |
| statusDetail | String |
Error message that explains the cause of the problem. |
| requestId | Integer |
Request identifier. Is only useful when the response indicates statusCode=in_progress |
When statusCode is success, the request is complete. The requested data are included in the response. Most of the calls are always synchronous.
result = secuTixWebService.callOneMethod(null,param1,param2);
if(result.getStatusCode().equals("success")) {
//process normal behavior
} else {
//process error.
}When executing a call which duration exceed 30s, S-360 may return in_progress as status code along with a requestId. In that case, the calling code must wait a few seconds and call again passing along the requestId.
result = secuTixWebService.callOneMethod(null,param1,param2);
while(result.getStatusCode().equals("in_progress")){
wait(30); //wait 30 secondes
result = secuTixWebService.callOneMethod(result.getRequestId(),param1,param2);
}
if(result.getStatusCode().equals("success")) {
//process normal behavior
} else {
//process error.
}If the response includes some fields that are defined as multilingual values in the system’s configuration, then:
For catalogue’s methods (which reflect the configuration), the multilingual value will be returned
For action methods where the value is returned to avoid having to look into the configuration before responding to the client, only a chain of characters is being returned in the default locale being chosen (in order):
By the HTTP header Accept-Language according to the RFC
The default language of the institution.
This document presents “conceptual” descriptions of “business” data returned by a service, in the sense that they represent the semantics of the methods and objects. Syntax is voluntarily simplified in order to ease the reading and understanding. The real syntax is described in the generated WSDL.
All numerical Ids have to be considered, by default, as being on 64bits.
Monetary amounts are provided as longs, hence they must be divided by 1000 to get the actual value.
Each service’s version is made of a major and minor number: X.Y
X is incremented in a non-backward-compatible change Y is incremented in a backward-compatible change (adding methods, etc.) The version number is directly included in the service’s URL.