Wind-Proxy

The WIND-PROXY is a new REST service that exposes various WIND public services (e.g. worklight, datapower, SPAI) with a simple REST interface available to internal MONK services.

Acronyms and document referrals

SPAI

Service Provider Application Interface

Architectural design

<we’ll place a nice picture here>

All services are running under a tomcat7 with jre1.8 on the server wind-proxy. As usual you can login using your employee account and your rsa public key. The Tomcat user runs the service on port 8443 and is reachable from the outside, for the only purpose of deploying/undeploying the WAR on the server. The BOFH could from time to time disable the manager for security purposes.

All wind-proxy services are reachable only from the internal MONK infrastructure. (i.e. only from 172.16.0.0/12 network)

Environment	Private address	Public address
Production	wind-proxy01 wind-proxy02 wind-proxy03	telco-proxy01.monksoftware.it telco-proxy02.monksoftware.it telco-proxy03.monksoftware.it
Development	wind-proxy-preprod	wind-proxy-preprod.monksoftware.it

Production wind-proxy is round-robin resolved by DNS. When contacting it, just use the DNS name keeping to try resolving and contacting the port until the server answers. In order to contact the various endpoints for the services, please use:

http://wind-proxy:8080

or

http://wind-proxy-preprod:8080

As a basic URL: simply add the endpoint listed in each of the endpoints below to consume the service. It’s not possibile to use the internal services using the public address.

“wind-proxy” is the balancer host for the three backends for wind-proxy01,02,03.

All traffic on 8080 port is unencrypted and in clear, and the 8080 port is listening and available only on the private network, so only clients calling from a server installed in the Application Cluster. This maximizes throughput, at a loss of security - but this is handled by the MONK infrastructure. Heck, if someone can sniff the traffic it means it already got in, and seeing WIND operator numbers is the last of our problems.

In the future, we could implement a SSL interface also in the private network.

GITHUB REPOSITORY

The github repository under which the project is stored is

git@git.webmonks.org:wind/WindProxy.git

WINDPROXY LOGS

You can find wind-proxy logs on the centralized storage server, in the path

/var/log/windproxy

SPAI

In the SPAI section of the proxy, there is a scheduled job, running every hour, which fetches a new token from SPAI to accomodate for all new requests that are getting in. This means that the same token is used for ALL the incoming requests, until the token is no more valid. The first call the gets an error will then get a new token that will be stored automatically.

Following is a list of all the implemented interfaces. This list WILL change from time to time, so stay tuned for new information.

Number portability (Deprecated)

SPAI method: NumberPortability Operation name: checkMSISDNOperator Endpoint: /spai/checkmnpr

This is a method that returns the user current operator. It is deprecated in favor of Datapower getMnprData.

• Call it using a POST call on /spai/checkmnpr, sending a JSON

• Request input:

  {"msisdn" : "<msisdn>"}
  

  Msisdn must be in the format +39xxxxxx

• It returns application/json

  If you’re eager to integrate here is an example, successful response:

  {
    "result": "OK",
    "resultDescription": "Request successful",
    "data": "WIN"
  }
  

Here is an explanation of the fields:

Field	Content	Enumeration of values
result	Call result	OK, or KOx, where x is a number
resultDescription	Result description	A textual representation of the above
data	MSISDN operator	WIN, H3G, OPI, TIM, ERR

If you’re lucky, data will contain the operator for the received MSISDN. If there is an error, data field will not be present!

Msisdn check

SPAI method: MSISDNCheck Operation name: checkMsisdnType Endpoint: /spai/msisdncheck

This method returns both the segment and sim type for a WIND and (maybe) for a H3G user. E.g. you can discover if he is prepaid, postpaid, corporate, consumer, microbusiness, etc.

• Call it using a POST call on /spai/msisdncheck, sending a JSON

• Request input:

  {"msisdn" : "<msisdn>"}
  

  Msisdn must be in the format +39xxxxxx

• It returns application/json

  If you’re eager to integrate here is an example, successful response:

  {
    "result": "OK",
    "resultDescription": "Request successful",
    "sim_type": "corporate",
    "segment_type": "prepagato"
  }
  

Here is an explanation of the fields:

Field	Content	Enumeration of values
result	Call result	OK, or KOx, where x is a number
resultDescription	Result description	A textual representation of the above
sim_type	Type of SIM!	consumer,corporate,microbusiness
segment_type	Contract type	prepagato,postpagato

If there is an error, neither the sim_type nor the segment_type will be present!

SMS Delivery

SPAI method: SMSFree/SMSDeliveryVoiceChat Operation name: deliverySMS Endpoint: /spai/sendfreesms

Caution

Yes, you can freely send SMS to users. Be careful though, because the preproduction IS sending real SMS! If you need to simulate a sending, ask wind-proxy developers to add a dry-run flag.

• Call it using a POST call on /spai/sendfreesms, sending a JSON

• Request input:

  { "msisdn" : "<msisdn>", "body": "body to send" }.
  

  Msisdn must be in the format +39xxxxxx

• It returns application/json

  Please remember that the above parameters (msisdn and body) are the minimum requested parameters to be sent to sendfreesms. All the other parameters are not compulsory and are filled automatically, both from configuration and constants coded in the application (example, the message type, always 4 for SMS). The actual configuration sends SMS using sender “Wind”.

  If you want to send additional parameters and customize your request, here is what you can send:

  Field	Meaning
  msisdn	The target of your message!
  body	The full body of the message you want to send
  from	The sender. Can be anything less than 16 characters
  providerId	The provider used by wind for logging/revenue sharing
  serviceId	The SKU used by wind for logging/revenue sharing
  msgContId	The message content. Can be anything less than 16 chars
  msgContDescr	A description of the content. As above

  If you’re eager to integrate here is an example, successful response:

  {
    "result": "OK",
    "resultDescription": "Request successful",
    "transactionId": "232523252"
  }
  

Here is an explanation of the fields:

Field	Content	Enumeration of values
result	Call result	OK, or KOx, where x is a number
resultDescription	Result description	A textual representation of the above
transactionId	SDI Transaction ID	An alphanumeric unique identifier for the message
info	Additional info	Used to express info on KO6 error. See below

If you’re lucky, data will contain the operator for the received MSISDN. If there is an error, data field will not be present!

Error list for SPAI

Following the list of possible KOs and KOs description:

Field	Content
KO1	Wrong MSISDN format
KO2	Missing compulsory parameter (e.g. msisdn)
KO3	SPAI token is null. Normal for 1 second after server start
KO4	Backend error or timeout. Something went wrong on SPAI
KO5	Wrong configuration. Call a BOFH and pray
KO6	Could not send SMS. It could be a SPAI error, or a BE error
KO9	Could not retrieve sim_type or segment_type for user. Msisdn could be missing from SPAI. It can happen in preproduction environment….

Special notes regarding SMS

If the SPAI BE throws a “backend error”, that prevents the wind-proxy from sending the SMS, the info field will be present, along with an error code that (hopefully) can clear up doubts regading the nature of the error. The code will follow the below scheme. Please notice that this is a SPAI backend error and can be subject to changes. The list below is the most accurate we can provide at the moment.

Info	Meaning
NB0	The corporate MSISDN cannot access the WIND SPAI services for the service provider specified in the request.
NB1	The consumer MSISDN cannot access the WIND SPAI services for the service provider specified in the request.
NB2	The MSISDN, with a null customer type, is not enabled to integrate with the specified service provider.
NB8	The MSISDN is not enabled to receive the specified content.
B0	The specified MSISDN is expired.
B1	The MSISDN is not a WIND user.
B2	The MSISDN is in a suspended state.
B3	The MSISDN does not exist!
B4	The MSISDN is not present on WIND internal platforms.
SNA	Wrong parameters passed to a SPAI BE method.

Piksel

Piksel is an external provider for WINDTRE that provides various APIs to retrieve information regarding users.

checkJwt

Endpoint: /piksel/checkJwt

This functionality is used to check a given Jwt validity. If valid, the Jwt can then be used on other methods for Piksel endpoints.

• Call it using a POST call.

No arguments are required, but you have to put the Jwt in the Authorization: Bearer header in order for it to be checked. Any error (wrong Jwt, bad Jwt, expired Jwt) will return a 401 UNAUTHORIZED error.

Here is a sample, successful response:

{"result":"OK","resultDescription":"Request successful.", "tokenValidity": true}

Field	Content
KO4	Backend error or timeout
KO5	Wrong configuration. Call a BOFH and pray
KO12	The JWT is not valid

companyName

Endpoint: /piksel/companyName

This functionality is exposed to return a companyName which is tied to a given msisdn or VAT number. You can call this endpoint with either the msisdn (for TRE users) or the VAT number (for WIND users). Remember that also the stack type (TRE or WIND) must be sent along with the appropriate parameter, or the call will fail. This endpoint is also JWT protected: you must pass, in the header, a valid JWT in order for the call to pass through the appropriate backend API. The JWT is not verified in its content, but it’s checked to be a valid one, i.e with a valid header, a body and a signature.

• Call it using a POST call on /piksel/companyName. Example for a TRE user:

{ "msisdn": "1234567", "stackType": "TRE" }

• Example for a WIND user:

{ "vat": "asduahsdiuh828", "stackType": "WIND" }

• The service returns an application/json response.

These are the allowed parameters:

Field	Meaning
msisdn	The msisdn to return the companyName for
vat	The VAT number to return the companyName for
stackType	Either TRE or WIND are valid values. Identifies the stack

Here is a sample, successful response:

{"result":"OK","resultDescription":"Request successful.", "companyName":"Monksoftware"}

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO1	Msisdn format is not valid
KO2	Missing a compulsory parameter
KO4	Backend error or timeout
KO5	Wrong configuration. Call a BOFH and pray
KO6	The given parameter does not return a valid companyName from the backend
KO10	Something went wrong on backend and no response can be returned
KO12	The JWT is not valid

Please notice that, in case of the KO10 error, you could find additional information on what happened in the “resultDescription” field. You can also pass a special parameter: mockupData and set it to true value. This is available only in preproduction/development environment, and will always return a valid companyName for any data you pass to WindProxy. Just be sure to use a valid JWT.

Datapower

Datapower is a WIND service which in practice is a proxy to WIDE and various internal services used by wind. Datapower uses both SOAP and REST interfaces, and hopefully all will be implemented in wind-proxy sooner or later. Like Worklight (below), there is a client authentication using SSL client certificates, and it’s all managed by wind-proxy. Please bear in mind that certificates DO expire, so please keep an eye on the logs near client certificate expiration.

CheckTriplettaVA

Endpoint: /datapower/checkTriplettaVA

This functionality expects a base64 encoded string which is the “triplet”, which uniquely identifies a certain contract code, customer code and msisdn. This can be useful for many purposes. Wind-proxy simply builds the request according to input, creates a local keystore to do the client authentication, and returns an OK result if the triplet could be verified successfully on WIND premises, or KO result if something went wrong. The full list of KO is available in the wind-proxy error list.

• Call it using a POST call on /datapower/checkTriplettaVA, sending a JSON request:

{ "triplettaVA": "KBWj0ycVbBbLdO8dIQpRb7BXpl8QHFC4xFXGRF6ZhXt4tIQEc6lgYbmWvF6T7o3eYWQIhahxgulSbSc8cJiXVgyBcdPZKPQiVuOM8eOFwtt0t/NMWHjkQiG4Lmlb9yvI8cWaBr6iGJFjP9C3ui/w==" }

Do not escape the triplet string, apart from, of course, the quotes. - The service returns an application/json response.

The only parameter you can send to the service is as follows:

Field	Meaning
triplettaVA	The triplet to check on WIND systems

Here is a sample, successful response:

{"result":"OK","resultDescription":"Request successful.","data":"OK"}

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending anything!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray
KO10	The triplet could not be verified on wind servers, so it’s wrong or expired!

Please notice that, in case of the KO10 error, you will find additional information on what happened in the “resultDescription” field. You can also pass a special parameter: mockupData and set it to true value. This is available only in preproduction/development environment, and will always return a OK result for any triplettaVA you pass to WindProxy.

isPremiumToken

Endpoint: /datapower/isPremiumToken

This functionality expects a base64 encoded string which is the “triplet”, which uniquely identifies a certain contract code, customer code and msisdn. This can be useful for many purposes. Wind-proxy simply builds the request according to input, creates a local keystore to do the client authentication, and, in the isPremium field for the response, returns whether the specified token has the premium flag set to true or false.

• Call it using a POST call on /datapower/isPremiumToken, sending a JSON request:

{ "triplettaVA": "KBWj0ycVbBbLdO8dIQpRb7BXpl8QHFC4xFXGRF6ZhXt4tIQEc6lgYbmWvF6T7o3eYWQIhahxgulSbSc8cJiXVgyBcdPZKPQiVuOM8eOFwtt0t/NMWHjkQiG4Lmlb9yvI8cWaBr6iGJFjP9C3ui/w==" }

Do not escape the triplet string, apart from, of course, the quotes. - The service returns an application/json response.

These are the parameters you can to the service is as follows:

Field	Meaning
triplettaVA	The triplet to check on WIND systems
tripletVersion	The triplet version. If not sent, the default is v2.

Here is a sample, successful response:

{"result":"OK","resultDescription":"Request successful.","isPremium":true}

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending anything!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray
KO10	The triplet could not be verified on wind servers, so it’s wrong or expired!

Please notice that, in case of the KO10 error, you will find additional information on what happened in the “resultDescription” field. You can also pass a special parameter: mockupData and set it to true value. This is available only in preproduction/development environment, and will always return a OK result with the isPremium flag set to true.

getTokenMsisdn

Endpoint: /datapower/getTokenMsisdn

This functionality expects a base64 encoded string which is the “triplet”, which uniquely identifies a certain contract code, customer code and msisdn. This can be useful for many purposes. Wind-proxy simply builds the request according to input, calls checkTriplettaVA on the backend, and extracts just the MSISDN part of the triplet, returning it in the “data” field. If something went wrong, the result field will be filled with a “KOXX” code, and the resultDescription will contain the details for the error.

• Call it using a POST call on /datapower/getTokenMsisdn, sending a JSON request:

{ "triplettaVA": "KBWj0ycVbBbLdO8dIQpRb7BXpl8QHFC4xFXGRF6ZhXt4tIQEc6lgYbmWvF6T7o3eYWQIhahxgulSbSc8cJiXVgyBcdPZKPQiVuOM8eOFwtt0t/NMWHjkQiG4Lmlb9yvI8cWaBr6iGJFjP9C3ui/w==" }

Do not escape the triplet string, apart from, of course, the quotes. - The service returns an application/json response.

The only parameter you can send to the service is as follows:

Field	Meaning
triplettaVA	The triplet to check on WIND systems

Here is a sample, successful response:

{"result":"OK","resultDescription":"Request successful.","data":"3801284920"}

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending anything!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray
KO10	The triplet could not be verified on wind servers, so it’s wrong or expired!

Please notice that, in case of the KO10 error, you will find additional information on what happened in the “resultDescription” field. You can also pass a special parameter: mockupData and set it to true value. This is available only in preproduction/development environment, and will always return a fake msisdn result for any triplettaVA you pass to WindProxy.

getCategoryListFull

Endpoint: /datapower/getCategoryListFull

This method lets the user retrieve a list of categories for the new WIND features, with campaigns recursively shown in a tree.

• Call it using a POST call on /datapower/getCategoryListFull, sending a JSON request:

{ "clientName": "your-client-name" }

These are the parameters you can send to the method:

Field	Meaning
clientName	The client name used to identify yourself. Compulsory
clientela	Optional. Default is “consumer”
mercato	Optional. Default is “PRE”
channel	Optional. Default is “MOBILE”

Here is a sample, successful response:

{"result":"OK","resultDescription":"Request successful","data":"OK","categories":[{"id":"21464","codice":"","type":"TAB","title":"Aggiungi SMS","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":[{"id":"21446","codice":"","type":"FOLDER","title":"","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":null}]},{"id":"1","codice":"","type":"TAB","title":"Aggiungi GIGA","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":[{"id":"21448","codice":"OFFERTA","type":"FOLDER","title":"","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":null}]},{"id":"3","codice":"","type":"TAB","title":"Offerte verso l'Estero","viewOrder":"2","imageURI":"","subTitle":"","flagCampaign":"N","categories":[{"id":"1007","codice":"","type":"FOLDER","title":"","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":null}]},{"id":"11","codice":"","type":"TAB","title":"Aggiungi Minuti","viewOrder":"3","imageURI":"","subTitle":"","flagCampaign":"N","categories":[{"id":"21474","codice":"OFFERTA","type":"FOLDER","title":"","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":null}]},{"id":"4","codice":"","type":"TAB","title":"Offerte se sei all'ESTERO","viewOrder":"4","imageURI":"","subTitle":"","flagCampaign":"N","categories":[{"id":"21346","codice":"","type":"FOLDER","title":"","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":null}]},{"id":"6","codice":"","type":"TAB","title":"Cambia offerta","viewOrder":"6","imageURI":"","subTitle":"","flagCampaign":"N","categories":[{"id":"21835","codice":"OFFERTA","type":"FOLDER","title":"","viewOrder":"1","imageURI":"","subTitle":"","flagCampaign":"N","categories":null},{"id":"48","codice":"","type":"FOLDER","title":"","viewOrder":"2","imageURI":"","subTitle":"","flagCampaign":"N","categories":null},{"id":"49","codice":"","type":"FOLDER","title":"","viewOrder":"3","imageURI":"","subTitle":"","flagCampaign":"N","categories":null},{"id":"22034","codice":"OFFERTA","type":"FOLDER","title":"","viewOrder":"4","imageURI":"","subTitle":"","flagCampaign":"N","categories":null}]},{"id":"5","codice":"","type":"TAB","title":"+","viewOrder":"7","imageURI":"","subTitle":"","flagCampaign":"N","categories":[{"id":"21221","codice":"","type":"FOLDER","title":"","viewOrder":"5","imageURI":"","subTitle":"","flagCampaign":"N","categories":null}]}]}

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending anything!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray

Please notice that, in case of the KO04 error, you will find additional information on what happened in the “resultDescription” field.

GetCustomerDetails

Endpoint: /datapower/getCustomerDetails

This functionality expects a base64 encoded string which is the “triplet”, which uniquely identifies a certain contract code, customer code and msisdn, as the endpoint above. What this endpoint does is that it can, given a triplet string, return all metadata regarding the user the triplet is

• Call it using a POST call on /datapower/getCustomerDetails, sending a JSON request:

{ "triplettaVA": "KBWj0ycVbBbLdO8dIQpRb7BXpl8QHFC4xFXGRF6ZhXt4tIQEc6lgYbmWvF6T7o3eYWQIhahxgulSbSc8cJiXVgyBcdPZKPQiVuOM8eOFwtt0t/NMWHjkQiG4Lmlb9yvI8cWaBr6iGJFjP9C3ui/w==" }

Do not escape the triplet string, apart from, of course, the quotes. - The service returns an application/json response.

The only parameter you can send to the service is as follows:

Field	Meaning
triplettaVA	The triplet to use to fetch customer data
userType	This optional parameter can be used to tell windProxy if the user is “legacy” or “digital”, in order to circumvent wrong provisioning problems on domains.

Here is a sample, successful response. You will find all you need in the “customerDetails” field:

{"result":"OK","resultDescription":"Request successful","data":"OK", "lineType": "LEGACY", "loginType": "CREDENTIALS", "msisdn": "3248747270", "customerDetails":{"customerCode":"3000182435","profile":"Consumer","firstName":"AGRIPPA","lastName":"GRECO","gender":"M","fiscalCode":"GRCGPP80L02A952Q","vatNumber":"","birthDate":"07/02/1980","birthCity":"BOLZANO","birthProvince":"BZ","birthCountry":"ITALIA","email":"NOMECOGNOMEDATA@TESTTEST.IT","address":{"cap":"39100","city":"BOLZANO","province":"BZ","street":"VIA PONTE RESIA,3","country":null},"faxPrefix":null,"faxNumber":"065080008","phonePrefix":null,"phoneNumber":"0471121600","turistaFlg":"","validazioneCfPiva":"OK","billingAccountList":[{"billingAccountName":"GRECO AGRIPPA","codiceCdF":"3000182567","comInvoiceProfileList":[{"cid":"","pec":""}]}]}}

Notice that in the getCustomerDetails response, you will also find the lineType, loginType and msisdn from the decrypt token API. And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending anything!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray
KO10	The triplet could not be verified on wind servers, so it’s wrong or expired!
KO11	The verified triplet returned both customerCodes as null: so no data available

Please notice that, in case of the KO10 and KO11 error, you will find additional information on what happened in the “resultDescription” field. You can also pass a special parameter: mockupData and set it to true value. This is available only in preproduction/development environment, and will always return a customerDetails response, with all necessary metadata, for any triplettaVA you pass to WindProxy.

GetContact

Endpoint: /datapower/getContact

This endpoint expects a msisdn in internal format, returning all campaigns where the msisdn is subscribed to.

• Call it using a POST call on /datapower/getContact, sending a JSON request:

{ "msisdn": "+393291234567" }

• The service returns an application/json response.

The only parameter you can send to the service is as follows:

Field	Meaning
msisdn	The msisdn to check
channel	An optional channel to use when sending data. If not present, the configured default will be used (ask admin)
very	if true, the calls will go to a specialized VeryMobile endpoint

Here is a sample, successful response. You will find all you need in the “contactOutput” field:

{"result":"OK","resultDescription":"Request successful","data":"OK","contactOutput":[{"campaignCode":"1000ltw59hbt","leadkeyid":"11219712577491000ltw59hdd","msisdn":"3290509014","output1":"1000ltw59hdd","output2":"30","output3":"","output4":"","output5":""}]}

Please notice that the result will always be OK if there are not backend errors: but, if there are no results for the given msisdn, the “data” field will be filled with the string “KO”. If the “data” field is “OK”, you can be sure there are results in the contactOutput field.

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending the msisdn!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray

getMnprData

Endpoint: /datapower/getMnprData

This endpoint expects a msisdn in internal format, and it returns a code identifying the mobile operator that the msisdn is currently subscribed to.

• Call it using a POST call on /datapower/getMnprData, sending a JSON request:

{ "msisdn": "+393291234567" }

• The service returns an application/json response.

The only parameter you can send to the service is as follows:

Field	Meaning
msisdn	The msisdn to check
channel	An optional channel to use when sending data. If not present, the configured default will be used (ask admin)

Here is a sample, successful response. You will find all you need in the “contactOutput” field:

{"result":"OK","resultDescription":"Request successful","data":"WIN"}

Please notice that the result will always be OK if there are not backend errors: but, if there are no results for the given msisdn, the “data” field will be filled with the string “KO”.

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending the msisdn!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray
KO10	Internal datapower error. Check the resultDescription for details

InCampaign

Endpoint: /datapower/inCampaign

This endpoint expects a msisdn in internal format, returning a flag, Y or N, depending on the fact the given msisdn has at least one active campaign for the configured channel. Presently the channel is a backend configuration with the MYWIND value.

• Call it using a POST call on /datapower/inCampaign, sending a JSON request:

{ "msisdn": "+393291234567", "input1": "asid23ui23i09", "input2": "iasjdioajsdi2i" }

• The service returns an application/json response.

The parameters you can send to the service are as follows:

Field	Meaning
msisdn	The msisdn to check
channel	An optional channel to use when sending data. If not present, the configured default will be used (ask admin)
very	if true, the calls will go to a specialized VeryMobile endpoint
input1	The campaign code
input2	The “collateral” code

Here is a sample, successful response. The flag is in the field “flagInCampaign”

{"result":"OK","resultDescription":"Request successful","data":"OK","flagInCampaign": "Y"}

Please notice that the result will always be OK if there are not backend errors: but, if there are no results for the given msisdn, the “data” field will be filled with the string “KO”. If the “data” field is “OK”, you can be sure there are results in the contactOutput field.

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending the msisdn!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray

SetEsito

Endpoint: /datapower/setEsito

This endpoint expects a msisdn in internal format, and other fields to update the esito of a given campaign/leadKeyid.

• Call it using a POST call on /datapower/setEsito, sending a JSON request:

{ "msisdn": "+393291234567", "campaignCode": "1000ltw59hbt", "leadKeyId": "11219712577491000ltw59hdd", "dataEsito": "20191003111111", "descrizioneEsito": "CTA_CLOSING"   }

• The service returns an application/json response with the result:

{ "result":"KO4","resultDescription":"No valid answer from DP backend!","data":"KO" }

The parameters you have send to the service are the following:

Field	Meaning
msisdn	The msisdn to check
campaignCode	The campaign code associated with the esito you want to set
channel	An optional channel to use when sending data. If not present, the configured default will be used (ask admin)
very	if true, the calls will go to a specialized VeryMobile endpoint
leadKeyId	The leadKeyId associated with the above
dataEsito	The date of the esito: format YYYYMMDDHHMMSS
descrizioneEsito	The description for the esito

You can also send these other parameters, but those are not compulsory:

Field	Meaning
macroEsito	Unknown
esito	Unknown

And here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO2	Missing compulsory parameter (e.g. you are not sending the msisdn!)
KO4	Backend error or timeout. Something went wrong on Datapower
KO5	Wrong configuration. Call a BOFH and pray

Worklight

Worklight is a WIND service used to check for, and activate, various option on a given MSISDN line. All communication is encrypted towards the Worklight service, and in production environment we also have to use a client certificate to be identified. The whole mojo of SSL authentication and so on is being done by the service, so you don’t have to worry about anything.

CheckInOrder

Endpoint: /worklight/checkinorder

The checkInOrder method checks whether an user can activate an option on his MSISDN. The method can also return whicih options must be deactivated in order to activate the new option. In the near future, you could find an outOrder method here (to deactivate the options needed), but, for the time being, it will not be possible using the wind-proxy.

• Call it using a POST call on /worklight/checkinorder, sending a JSON

• Request input:

  { "msisdn" : "<msisdn>", "option": "option to check" }
  

  Msisdn must be in the format +39xxxxxx

• It returns application/json

  Here are the fields you can send in the request:

  Field	Meaning
  msisdn	The msisdn for which you want to check the option
  option	The option that you want to check for (es.TK2323,ROPZ241)

Be wary that the Worklight response can be a bit complex and requires you to act according to it. But, a simple response to get you to integrate faster could be:

{
  "result": "OK",
  "resultDescription": "Request successful",
  "data": "OK_OPTION"
}

Or a bad response could be:

{
  "result": "KO8",
  "resultDescription": "OptionCode is not valid",
  "data": "KO_OPTION"
}

But finally, you could have an OK, but with some “outorders”. This will mean that the user MUST deactivate the options listed in order to be able to activate the one you asked for. Here is an example:

{
  "result": "OK",
  "resultDescription": "Request successful",
  "data": "OK_OPTION",
  "outorders": [
    {
      "outorderCRM":  "All Inclusive Marzo 2016",
      "name": "All Inclusive",
      "code": "ROPZ4514"
     }
  ]
}

This means that you should message the user regarding this issue, and then have him act accordingly. Or, you could simply say that he cannot activate the request. It’s up to you and your application.

Here is a full explanation of the response fields:

Field	Content	Enumeration of values
result	Call result	OK, or KOx, where x is a number
resultDescription	Result description	A textual representation of the above
data	Result of the check	Will not appear if there is an error, or can be OK_OPTION if the option can be activated, or KO_OPTION if it can’t be activated
outorders	List of OutOrder	See below to understand

Here is the explanation of an OutOrder object:

Field	Content	Enumeration of values
outorderCRM	The label of the ROPZ	for example: “All Inclusive Marzo”
name	The category of it	for example: “All inclusive”
code	The code you have to use to deactivate it	ROPZ2323, ROPZ324, POPZ22, etc….

And finally (whew!) here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO1	Wrong MSISDN format
KO2	Missing compulsory parameter (e.g. msisdn)
KO4	Backend error or timeout. Something went wrong on Worklight
KO5	Wrong configuration. Call a BOFH and pray
KO7	Requested MSISDN is not-existant on BE server
KO8	Something went wrong on Worklight, and this will contain the Worklight error

InOrder

Endpoint: /worklight/inorder

The inOrder method ACTIVATES the option on the given MSISDN. Be careful!

• Call it using a POST call on /worklight/inorder, sending a JSON

• Minimal input:

  { "msisdn" : "<msisdn>", "option": "option to activate" }
  

  Msisdn must be in the format +39xxxxxx

• It returns application/json

  Here are the fields you can send in the request:

  Field	Meaning
  msisdn	The msisdn for which you want to check the option
  option	The option that you want to check for (es.TK2323,ROPZ241)
  popz	The POPZ to send with the option. Not compulsory

The POPZ option is an additional token that is being sent, along with the option, to the WorkLight Servers. Ask your MKTG guy/grampa/girl to get one for you if it’s needed by your application!

Here is a full explanation of the response fields:

Field	Content	Enumeration of values
result	Call result	OK, or KOx, where x is a number
resultDescription	Result description	A textual representation of the above

And finally here is a list of KOs that can be thrown by this endpoint:

Field	Content
KO1	Wrong MSISDN format
KO2	Missing compulsory parameter (e.g. msisdn)
KO4	Backend error or timeout. Something went wrong on Worklight
KO5	Wrong configuration. Call a BOFH and pray
KO7	Requested MSISDN is not-existant on BE server
KO8	Something went wrong on Worklight, and this will contain the Worklight error

Datapower-Node

Use the wide-proxy installed in the same server as wind-proxy, but in port 6594. It runs as user node. Presently it’s offering the following services:

• [EndPaypalRecharge](#endPaypalRecharge)

• [GetAuthentication](#getAuthentication)

• [GetBundleAndServiceCRP](#getBundleAndServiceCRP)

• [GetCustomerInfo](#getCustomerInfo)

• [GetInfoCliente](#getInfoCliente)

• [GetLines](#getLines)

• [GetLineSummary](#getLineSummary)

• [RechargeConfigGAFE](#rechargeConfigGAFE)

• [StartPaypalRecharge](#startPaypalRecharge)

Check the README on the GIT project at git@git.webmonks.org:wind/wide-proxy.git for more details.