Sophisticated Simplicity In Mobile Interaction Technical Guide Number Information Services - Asynchronous SOAP Version 1.3
Table of Contents Page 1. Introduction to Number Information Services 3 2. Requirements for Number Information Services Implementation 4 3. Technical Overview 5 3.1. General Interface Information 3.2. Specific Interface Information for Global Number Portability 3.3. Specific Interface Information for Global Number Verification 4. Detailed Communication Process 6 4.1. Global Number Portability 4.1.1 Example Request 4.2. Global Number Verification 4.2.1.Example Request 5. Features of Number Information Services 17 5.1. GSM Return codes 5.2. Flexible Respond-Back-URL 5.3. AlertSC Notification 6. Glossary of Terms 18 7. Frequently Asked Questions 19 8. Contact Information 20
1. Introduction to Number Information Services tyntec s Number Information Services enable companies to perform number portability resolution, subscriber database cleaning, compile statistical data, implement anti-fraud procedures and ID verification. These services provide network information from databases, from the mobile network and from other sources. In the Number Information Services family, tyntec offers two products: Global Number Portability and Global Number Verification. Global Number Portability Output: Subscription network IMSI and HLR network information (MCC/MNC) IMSI and HLR country IMSI and HLR timezone Global Number Verification Output: Number range holder (NRH) NRH info (MCC/MNC) NRH country NRH timezone Subscription network IMSI and HLR network information (MCC/MNC) IMSI and HLR country IMSI and HLR timezone Servicing network MSC network information (MCC/MNC) MSC country MSC timezone Porting information (true/ false) Roaming information (true/ false) Presence information (true/ false) SS7 network error code 3
Figure 1: The Global Number Portability Communication Process Step 1 Sending check request (number) Customer Step 2 Acknowledge check response (msg-ref ) Step 3 Sending check delivery request (msg-ref, result) Step 4 Acknowledge delivery response Figure 2: The Global Number Verification Communication Process Step 1 Sending check request (number) Step 2 Acknowledge check request (msg-ref ) Customer Step 3 Sending check delivery request (msg-ref, result) Step 4 Acknowledge check delivery response Step 5 Optional alertsc delivery request Step 6 Optional alertsc delivery response The arrows show the direction of the data flow. Each arrow is labelled with the SOAP message type carrying the data. The essential data that is transported appears in brackets following the SOAP message type. A detailed overview of the communication process is provided in section 4 of this document. 2. Requirements for Number Information Services Implementation To implement and use Number Information Services, the customer should have certain resources available that are not provided by tyntec. For example, a Web Services Developer must be available to plan and implement: The call of a Web Service as defined by the SOAP specification (http://www.w3.org/tr/soap12-part1/) with the help of the provided WSDL file. A receiving Web Service on the server-side in order to accept requests to deliver the results (CheckDeliverRequest, defined in the WSDL file). This is only necessary for the asynchronous interface. 4
Furthermore, the customer needs a computer system with a fixed IP address from where the SOAP call is initiated, and where the Web Service runs and which accepts the results if using the asynchronous interface (Check Delivery Requests). This computer system must be reachable from the tyntec IP. For the fastest implementation and expert support from tyntec, it is strongly recommended that the Number Information Services are is implemented using: The call of a Web Service as defined by the SOAP specification (http://www.w3.org/tr/soap12-part1/) with the help of the provided WSDL file. Java Axis2 1.3 Web Services framework: http://ws.apache.org/axis2/ http://java.sun.com/webservices/docs/1.6/tutorial/doc/ Tomcat 5.5 or higher for hosting the axis framework: http://tomcat.apache.org/ The following documents are useful in implementing the Number Information Services with the above components: http://ws.apache.org/axis2/1_3/userguide.html http://ws.apache.org/axis2/1_3/installationguide.html http://www.onjava.com/pub/a/onjava/2001/10/24/xmldatabind.html 3. Technical Overview 3.1. General Interface Information SOAP and Web Services are very convenient for setting up proprietary interfaces in a quickly developing market. The process of writing the code to call a Web Service and accessing the Web Service to receive results from tyntec is a straightforward task. SOAP is a protocol used for exchanging messages over a computer network. The messages that are sent do not rely on the underlying transport protocol, which is in most cases (and in the specific case of the tyntec infrastructure) HTTP-Post. The messages themselves are structured as XML documents and are defined in two parts: the SOAP standard and the tyntec WSDL file. The SOAP standard describes elements necessary for communication, such as the SOAP Envelope which encloses the actual content to be sent. This content is application-specific and is in this case defined by the WSDL file provided by tyntec. A simple XML parser can be used for extracting the data from the soap response. The WSDL file can be accessed on one of the URLs below, depending if HTTP or HTTPS is used. The files are compatible with both Global Number Portability and Global Number Verification. http://78.110.226.174:8977/soap/services/superqueryservice?wsdl https://78.110.226.174:9477/soap/services/superqueryservice?wsdl 3.2. Specific Interface Information for Global Number Portability As previously mentioned, tyntec s SOAP implementation uses HTTP as its transport layer. The initial request consists of the number to be queried, in international format. The result will hold: 5
Subscription network information IMSI network info (MCC/MNC) IMSI country IMSI timezone HLR network info (MCC/MNC) HLR country HLR timezone 3.3. Specific Interface Information for Global Number Verification As previously mentioned, tyntec s SOAP implementation uses HTTP as its transport layer. The initial request consists of the number to be queried, in international format. The result will hold: Number range holder network information (MCC/MNC) o Number range holder country o Number range holder timezone Subscription network information o IMSI network info (MCC/MNC) o IMSI country o IMSI timezone o HLR network info (MCC/MNC) o HLR country o HLR timezone Servicing network information o MSC network information (MCC/MNC) o MSC country o MSC timezone Presence information of the handset (true/ false) Roaming information (true/ false) Porting information (true/ false) SS7 network error code 4. Detailed Communication Process 4.1. Global Number Portability Step 1 - Sending Check Request (number) The communication protocol is HTTP, whereby a request is submitted to a URL specified by tyntec. A sample request is shown below. <tyn:checkrequest xmlns:tyn= http://www.tyntec.biz/ > <tyn:allnetworkquery> <tyn:destination> <tyn:number tyn:ton= Unknown tyn:npi= Unknown >+491239876543</tyn:Number> 6
</tyn:destination> </tyn:allnetworkquery> </tyn:checkrequest> Please note that the XML request must be surrounded by a proper SOAP-body in a proper SOAP-envelope Step 2 - Acknowledge Check Response tyntec will acknowledge the receipt of a Check Request. Please note that this response will be delivered via the HTTP response to the previous HTTP request. If the Check Request has been received successfully, tyntec will acknowledge the Check Request with a MessageRef which should be stored within the customer s implementation of the interface: <tyn:checkresponse xmlns:tyn= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> </tyn:checkresponse> If the Check Request has been received but contains an error, tyntec will acknowledge the Check Request with an error code. One of the possible return codes is shown here: <tyn:checkresponse xmlns:tyn= http://www.tyntec.biz/ > <tyn:errorcode>invaliddata</tyn:errorcode> </tyn:checkresponse> The full list of return codes can be seen in the following table: Error Code Description HTTP 401 (unauthorized) Invalid Data RespondBackURL invalid Internal Error This error is returned when the number of queries exceeds the previously agreed amount of queries, or the username and password are wrong or do not match. This error is not transmitted in a SOAP envelope but as a direct response to the HTTP request. This error is returned if the number transmitted is wrong (e.g., there are spaces or letters in the number). This error is returned if (1) the Respond-Back-URL given is not a valid one (2) the IP that is used is a local one (if it starts with 192.168., 10. or 127. ) (3) the host part is localhost or empty (4) any other error occurs when handling the URL This error should be reported to tyntec Support together with the message ID. Step 3 - Sending Check Delivery Request tyntec employs 3 response codes to determine the outcome of a message. The table below shows the Response Codes and their associated Check State values. Check State Response Code Description Success 0 Success The requested MSISDN information is returned Failure 1 No Response Temporarily not connected to the network or the network is not covered by tyntec Failure 2 Error Network has confirmed that MSISDN does not exist 7
A response code is only returned when the Check State value = Failure. Response Code 0 Success A successful Check Delivery Request will return all data regarding the subscription network, e.g.: <tyn:checkdeliverrequest xmlns:tyn= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> <tyn:checkstate value= Success /> <tyn:allnetworkinfo> <tyn:subscriptionnetwork> <tyn:imsiinformation> <tyn:networkinfo> <tyn:mcc>262</tyn:mcc> <tyn:mnc>07</tyn:mnc> <tyn:tyntecid>1099</tyn:tyntecid> <tyn:operatorname>o2 (Germany) GmbH & Co. OHG</tyn:OperatorName> <tyn:country> <tyn:countryname isoalpha3code= DEU >Germany</tyn:CountryName> <tyn:timezone> <tyn:daylightsavingtime> <tyn:hasdst>true</tyn:hasdst> <tyn:dstcurrentlyactive>false</tyn:dstcurrentlyactive> <tyn:dstoffset>3600000 ms</tyn:dstoffset> </tyn:daylightsavingtime> <tyn:name>europe/berlin</tyn:name> <tyn:gmtoffset>3600000 ms</tyn:gmtoffset> </tyn:timezone> </tyn:country> </tyn:networkinfo> </tyn:imsiinformation> <tyn:hlrinformation> <tyn:networkinfo> <tyn:mcc>262</tyn:mcc> <tyn:mnc>07</tyn:mnc> <tyn:tyntecid>1099</tyn:tyntecid> <tyn:operatorname>o2 (Germany) GmbH & Co. OHG</tyn:OperatorName> <tyn:country> <tyn:countryname isoalpha3code= DEU >Germany</tyn:CountryName> <tyn:timezone> <tyn:daylightsavingtime> <tyn:hasdst>true</tyn:hasdst> <tyn:dstcurrentlyactive>false</tyn:dstcurrentlyactive> <tyn:dstoffset>3600000 ms</tyn:dstoffset> </tyn:daylightsavingtime> <tyn:name>europe/berlin</tyn:name> <tyn:gmtoffset>3600000 ms</tyn:gmtoffset> </tyn:timezone> </tyn:country> </tyn:networkinfo> 8
</tyn:hlrinformation> </tyn: SubscriptionNetwork> </tyn:allnetworkinfo> </tyn:checkdeliverrequest> Although the response code 0 is not explicitly returned, success is implied when the network operator information is returned. With the delivery of MCC + MNC we ensure uniqueness in the transmission of the network operator information, regardless of any changes that may have taken place regarding the name of the operator. Response Code 1 No Response Response code 1 indicates that the network did not return a response, e.g.: <tyn:checkdeliverrequest xmlns:tyn= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> <tyn:checkstate tyn:value= Failure /> <tyn:networkerrorcode tyn:networktype= GSM tyn:value= 1 /> </tyn:checkdeliverrequest> There are a number of reasons why a network may not return a response. Often poor number quality results in the network being unable to respond. Check the quality of the number to ensure that it consists only of the + sign and decimal digits - no other characters or spaces are permitted. If number quality is good, there may be a problem with the network, and it is recommend that you query again at a later time. Another possibility is that the number belongs to an operator that is not reachable by tyntec. Response Code 2 Error Response code 2 indicates that the network has confirmed that the MSISDN does not exist, e.g.: <tyn:checkdeliverrequest xmlns:tyn= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> <tyn:checkstate tyn:value= Failure /> <tyn:networkerrorcode tyn:networktype= GSM tyn:value= 2 /> </tyn:checkdeliverrequest> 4.1.1 Example Request This example shows a Check Request enclosed in a SOAP Envelope with a full HTTP POST Header. Authorization information for user:testpassword is encoded in the Authorization header (to be found in RFC 2617, chapter 2 http://www.ietf.org/rfc/rfc2616.txt). Please note that the login user with password testpassword is not valid on the tyntec system and the host given in the example may differ from the host that is valid for you. Please refer to your BIO in the Customer Lounge for the correct host. HTTP-Post-Header and SOAP-Envelope: ============= begin =============== POST /soap/services/enhancedcheckservice HTTP/1.0 Content-Type: text/xml; charset=utf-8 9
Accept: application/soap+xml, application/dime, multipart/related, text/* User-Agent: Axis/1.2alpha Host: 78.110.226.164:8972 Cache-Control: no-cache Pragma: no-cache SOAPAction: Content-Length: 583 Authorization: Basic dxnlcjp0zxn0cgfzc3dvcmq= <?xml version= 1.0 encoding= UTF-8?> <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ xmlns:xsd= http://www.w3.org/2001/xmlschema xmlns:xsi= http://www.w3.org/2001/xmlschema-instance xmlns:tyn= http://www.tyntec.biz/ > <soapenv:body> <tyn:checkrequest> <tyn:allnetworkquery> <tyn:destination> <tyn:number tyn:ton= Unknown tyn:npi= Unknown >+491239876543</tyn:Number> </tyn:destination> </tyn:allnetworkquery> </tyn:checkrequest> </soapenv:body> </soapenv:envelope> =============== end ================ 4.2. Global Number Verification Step 1 - Sending Check Request (number) The communication protocol is HTTP, whereby a request is submitted to a URL specified by tyntec. A sample request is shown below. <tyn:checkrequest xmlns:tyn= http://www.tyntec.biz/ > <tyn:allnetworkquery> <tyn:destination> <tyn:number tyn:ton= Unknown tyn:npi= Unknown >+491239876543</tyn:Number> </tyn:destination> </tyn:allnetworkquery> </tyn:checkrequest> Please note that the XML request must be surrounded by a proper SOAP-body in a proper SOAP- envelope. Step 2 - Acknowledge Check Response tyntec will acknowledge the receipt of a Check Request. Please note that this response will be delivered via the HTTP 10
response to the previous HTTP request. If the Check Request has been received successfully, tyntec will acknowledge the Check Request with a MessageRef which should be stored within the customer s implementation of the interface: <tyn:checkresponse xmlns:tyn= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> </tyn:checkresponse> If the Check Request has been received but contains an error, tyntec will acknowledge the Check Request with an error code. One of the possible return codes is shown here: <tyn:checkresponse xmlns:tyn= http://www.tyntec.biz/ > <tyn:errorcode>invaliddata</tyn:errorcode> </tyn:checkresponse> The full list of return codes can be seen in the following table: Error Code Description HTTP 401 (unauthorized) Invalid Data RespondBackURL invalid Internal Error This error is returned when the number of queries exceeds and the previously agreed amount of queries, or the username and password are wrong or do not match. This error is not transmitted in a SOAP envelope but as a direct response to the HTTP request. This error is returned if the number transmitted is wrong (e.g., there are spaces or letters in the number) This error is returned if - the RespondBack-URL is a local one (if it starts with 192.168., 10. or 127. ) - the host part is localhost or empty - any other error occurs when handling the URL This error should be reported to tyntec Support together with the message ID. Step 3 - Sending Check Delivery Request tyntec employs three response codes to determine the outcome of a message. The table below shows the response codes and their associated Check State values. Check State Response Code Description Success 0 Success The requested MSISDN information is returned Failure Failure 1 No Response 2 Error Temporarily not connected to the network or the network is not covered by tyntec Network has confirmed that MSISDN does not exist A response code is only returned when the Check State value = Failure. tyntec employs three response codes to determine the outcome of a message. The table below shows the response codes and their associated Check State values. 11
Response Code 0 Success A successful Check Delivery Request will return all data regarding the MSISDN. The data is delivered in the AllNetworkInfo and will contain information regarding number range holder network, the subscription network (composed of IMSIInformation and HLRInformation) and if available the servicing network. <tyn:allnetworkinfo> <tyn:numberrangeholderinfo /> <tyn:subscriptionnetworkinfo /> <tyn:servicingnetworkinfo /> <tyn:presence /> <tyn:ported /> <tyn:roaming /> <tyn:ss7errorcode /> </tyn:allnetworkinfo> // if available //optional // optional For each network a NetworkInfo tag will contain the mobile country code(mcc) defining the country, the mobile network code(mnc) defining the network, the tyntecid (a unique ID for each operator) and the OperatorName (the name of the carrier). The NetworkInfo tag will look like this: <tyn:networkinfo> <tyn:mcc /> <tyn:mnc /> <tyn:tyntecid /> <tyn:operatorname /> <tyn:country /> </tyn:networkinfo> Each Country will contain information about the country name, the isoalpha3code and if available the timezone. <tyn:country> <tyn:countryname /> <tyn:timezone> <tyn:daylightsavingtime> <tyn:hasdst /> <tyn:dstcurrentlyactive /> <tyn:dstoffset /> </tyn:daylightsavingtime> <tyn:name /> <tyn:gmtoffset /> </tyn:timezone> </tyn:country> // if available // if country is usingdaylightsavingtime // if country is using DayLightSavingTime //if country using DayLightSavingTime An example, containing all information would look like this: <tyn:checkdeliverrequest xmlns= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> <tyn:checkstate value= Success /> <tyn:allnetworkinfo> <tyn:numberrangeholderinfo> <tyn:networkinfo> 12
<tyn:mcc>262</tyn:mcc> <tyn:mnc>03</tyn:mnc> <tyn:tyntecid>17</tyn:tyntecid> <tyn:operatorname>e-plus Mobilfunk</tyn:OperatorName> <tyn:country> <tyn:countryname isoalpha3code= DEU >Germany</tyn:CountryName> <tyn:timezone> <tyn:daylightsavingtime> <tyn:hasdst>true</tyn:hasdst> <tyn:dstcurrentlyactive>false</tyn:dstcurrentlyactive> <tyn:dstoffset>3600000 ms</tyn:dstoffset> </tyn:daylightsavingtime> <tyn:name>europe/berlin</tyn:name> <tyn:gmtoffset>3600000 ms</tyn:gmtoffset> </tyn:timezone> </tyn:country> </tyn:networkinfo> </tyn:numberrangeholderinfo> <tyn:subscriptionnetwork> <tyn:imsiinformation> <tyn:networkinfo> <tyn:mcc>262</tyn:mcc> <tyn:mnc>03</tyn:mnc> <tyn:tyntecid>17</tyn:tyntecid> <tyn:operatorname>e-plus Mobilfunk</tyn:OperatorName> <tyn:country> <tyn:countryname isoalpha3code= DEU >Germany</tyn:CountryName> <tyn:timezone> <tyn:daylightsavingtime> <tyn:hasdst>true</tyn:hasdst> <tyn:dstcurrentlyactive>false</tyn:dstcurrentlyactive> <tyn:dstoffset>3600000 ms</tyn:dstoffset> </tyn:daylightsavingtime> <tyn:name>europe/berlin</tyn:name> <tyn:gmtoffset>3600000 ms</tyn:gmtoffset> </tyn:timezone> </tyn:country> </tyn:networkinfo> </tyn:imsiinformation> <tyn:hlrinformation> <tyn:networkinfo> <tyn:mcc>262</tyn:mcc> <tyn:mnc>03</tyn:mnc> <tyn:tyntecid>17</tyn:tyntecid> <tyn:operatorname>e-plus Mobilfunk</tyn:OperatorName> <tyn:country> <tyn:countryname isoalpha3code= DEU >Germany</tyn:CountryName> <tyn:timezone> <tyn:daylightsavingtime> <tyn:hasdst>true</tyn:hasdst> <tyn:dstcurrentlyactive>false</tyn:dstcurrentlyactive> <tyn:dstoffset>3600000 ms</tyn:dstoffset> </tyn:daylightsavingtime> 13
<tyn:name>europe/berlin</tyn:name> <tyn:gmtoffset>3600000 ms</tyn:gmtoffset> </tyn:timezone> </tyn:country> </tyn:networkinfo> </tyn:hlrinformation> </tyn:subscriptionnetwork> <tyn:servicingnetwork> <tyn:networkinfo> <tyn:mcc>262</tyn:mcc> <tyn:mnc>03</tyn:mnc> <tyn:tyntecid>17</tyn:tyntecid> <tyn:operatorname>e-plus Mobilfunk</tyn:OperatorName> <tyn:country> <tyn:countryname isoalpha3code= DEU >Germany</tyn:CountryName> <tyn:timezone> <tyn:daylightsavingtime> <tyn:hasdst>true</tyn:hasdst> <tyn:dstcurrentlyactive>false</tyn:dstcurrentlyactive> <tyn:dstoffset>3600000 ms</tyn:dstoffset> </tyn:daylightsavingtime> <tyn:name>europe/berlin</tyn:name> <tyn:gmtoffset>3600000 ms</tyn:gmtoffset> </tyn:timezone> </tyn:country> </tyn:networkinfo> </tyn:servicingnetwork> <tyn:presence>true</tyn:presence> <tyn:ported>false</tyn:ported> <tyn:roaming>false</tyn:roaming> <tyn:ss7errorcode>0</tyn:ss7errorcode> </tyn:allnetworkinfo> </tyn:checkdeliverrequest> Response Code 1 No Response Response code 1 indicates that the network did not return a response, e.g.: <tyn:checkdeliverrequest xmlns:tyn= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> <tyn:checkstate tyn:value= Failure /> <tyn:networkerrorcode tyn:networktype= GSM tyn:value= 1 > <tyn:networkerrorcodedescription hexerrorcode= 0xe040 > DIALOGUE TIMED OUT </tyn:networkerrorcodedescription> </tyn:networkerrorcode> </tyn:checkdeliverrequest> There are a number of reasons why a network may not return a response. Often poor number quality results in the network being unable to respond. Check the quality of the number to ensure that it consists only of the + sign and decimal digits - no other characters or spaces are permitted. If number quality is good, there may be a problem with the network and it is recommend that you query again at a later time. Another possibility is that the number belongs to an operator that is not reachable by tyntec. 14
Response Code 2 Error Response code 2 indicates that the network has confirmed that the MSISDN does not exist, e.g.: <tyn:checkdeliverrequest xmlns:tyn= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> <tyn:checkstate tyn:value= Failure /> <tyn:networkerrorcode tyn:networktype= GSM tyn:value= 2 > <tyn:networkerrorcodedescription hexerrorcode= 2 > UNKNOWN_ADDRESS </tyn:networkerrorcodedescription> </tyn:networkerrorcode> </tyn:checkdeliverrequest> Step 4 - Acknowledge Check Delivery Response The receipt of the Check Delivery Request must be acknowledged to tyntec. Please note that this response must be delivered via the HTTP response to the previous HTTP request. To acknowledge successful delivery, please send back a response in the following format: <tyn:checkdeliverresponse xmlns:tyn= http://www.tyntec.biz/ > </tyn:checkdeliverresponse> If there is an issue in the processing of the response from tyntec, a message indicating an error will be returned. For example, returning the following message will trigger a retry from tyntec: <tyn:checkdeliverresponse xmlns:tyn= http://www.tyntec.biz/ > <tyn:errorcode>error while Processing</tyn:ErrorCode> </tyn:checkdeliverresponse> Step 5 AlertSC Delivery Request (optional) This feature will inform you when the handset associated to to the requested MSISDN is switched on again. This feature can be requested from tyntec Support. The notification contains the AlertSCReceiver, the AlertSCDate and the HLRInformation (for details see step 3) and will look like this: <tyn:alertscdeliverrequest xmlns= http://www.tyntec.biz/ > <tyn:messageref>15-21088981464922+491239876543</tyn:messageref> <tyn:alertscinfo> <tyn:alertscreceiver>+491239876543</tyn:alertscreceiver> <tyn:alertscdate>2009-02-2514:28:27.0</tyn:alertscdate> <tyn:hlrinformation> <tyn:networkinfo> <tyn:mcc>262</tyn:mcc> <tyn:mnc>03</tyn:mnc> <tyn:tyntecid>17</tyn:tyntecid> <tyn:operatorname>e-plus Mobilfunk</tyn:OperatorName> <tyn:country> <tyn:countryname isoalpha3code= DEU >Germany</tyn:CountryName> <tyn:timezone> <tyn:name>europe/berlin</tyn:name> 15
<tyn:gmtoffset>3600000 ms</tyn:gmtoffset> <tyn:daylightsavingtime> <tyn:hasdst>true</tyn:hasdst> <tyn:dstcurrentlyactive>false</tyn:dstcurrentlyactive> <tyn:dstoffset>3600000 ms</tyn:dstoffset> </tyn:daylightsavingtime> </tyn:timezone> </tyn:country> </tyn:networkinfo> </tyn:hlrinformation> </tyn:alertscinfo> </tyn:alertscdeliverrequest> Step 6 AlertSC Delivery Response The receipt of the AlertSC Delivery Request must be acknowledged to tyntec. Please note that this response must be delivered via the HTTP response to the previous HTTP request. To acknowledge successful delivery, please send back a response in the following format: <tyn:alertscdeliverresponse xmlns:tyn= http://www.tyntec.biz/ > </tyn:alertscdeliverresponse> If there is an issue in the processing of the response from tyntec, a message indicating an error will be returned. For example, returning the following message will trigger a retry from tyntec: <tyn:alertscdeliverresponse xmlns:tyn= http://www.tyntec.biz/ > <tyn:errorcode>error while Processing</tyn:ErrorCode> </tyn:alertscdeliverresponse> The receipt of successful results must be acknowledged by your HTTP server by terminating the stream. Failure to terminate the stream will result in a re-delivery from tyntec. Generally a Web Services framework will automatically close the stream. It is recommended that you do not use a hand-written parser for processing SOAP-Messages, but rather an automated system such as Castor or any other XML parsing technology. 4.2.1.Example Request This example shows a Check Request enclosed in a SOAP Envelope with a full HTTP POST Header. Authorization information for user:testpassword is encoded in the Authorization header (to be found in RFC 2617 Chapter 2). HTTP-Post-Header and SOAP-Envelope: ============= begin =============== POST /soap/services/checkservice HTTP/1.0 Content-Type: text/xml; charset=utf-8 Accept: application/soap+xml, application/dime, multipart/related, text/* User-Agent: Axis/1.2alpha Host: http2.tyntec.biz:8968 Cache-Control: no-cache Pragma: no-cache SOAPAction: Content-Length: 583 16
Authorization: Basic dxnlcjp0zxn0cgfzc3dvcmq= <?xml version= 1.0 encoding= UTF-8?> <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ xmlns:xsd= http://www.w3.org/2001/xmlschema xmlns:xsi= http://www.w3.org/2001/xmlschema-instance xmlns:tyn= http://www.tyntec.biz/ > <soapenv:body> <tyn:checkrequest> <tyn:allnetworkquery> <tyn:destination> <tyn:number tyn:ton= Unknown tyn:npi= Unknown >+491239876543</tyn:Number> </tyn:destination> </tyn:allnetworkquery> </tyn:checkrequest> </soapenv:body> </soapenv:envelope> =============== end ================ 5. Features of Number Information Services 5.1. GSM Return codes The GSM Return Codes are provided in addition to one of the three tyntec response codes. A list of GSM Return Code values and their associated descriptions is available in the Customer Lounge. The following example shows the error for an unknown subscriber: <soapenv:envelope xmlns:soapenv= http://schemas.xmlsoap.org/soap/envelope/ xmlns:xs d= http://www.w3.org/2001/xmlschema xmlns:xsi= http://www.w3.org/2001/xmlschema-instance > <soapenv:body> <CheckDeliverRequest xmlns= http://www.tyntec.biz/ > <MessageRef>15-21088981464922+491239876543</MessageRef> <CheckState value= Failure /> <NetworkErrorCode networktype= GSM value= 1 > <NetworkErrorDescription hexerrorcode= 1 > UNKNOWN_SUBSCRIBER </NetworkErrorDescription> </NetworkErrorCode> </CheckDeliverRequest> </soapenv:body> </soapenv:envelope> 17
5.2. Flexible Respond-Back-URL The Flexible Respond-Back-URL feature is used to change the address that is used for delivering the results of each request. This feature can be used at any time without any additional action by the customer. The given URL is used for only the accompanying request and does not change the general URL transmitted to tyntec upon setup of the account. This feature is only available on the asynchronous interface. The following shows an example: <tyn:checkrequest xmlns:tyn= http://www.tyntec.biz/> <tyn:allnetworkquery> <tyn:destination> <tyn:number>+491239876543</tyn:number> </tyn:destination> </tyn:allnetworkquery> <tyn:respondbackurl>http://www.yourserver.com/yourservice</tyn:respondbackurl> </tyn:checkrequest> 5.3. AlertSC Notification For additional information regarding this feature look at Step 5 in the message sending process. For the AlertSC feature the flexible respond-back-url feature is not available. A fix respond-back URL is needed. 6. Glossary of Terms Asynchronous: An interaction is said to be asynchronous when the associated messages are chronologically and procedurally decoupled. HLR: Home Location Register. IMSI: International Mobile Subscriber Identity. MSC: Mobile Switching Center. MSISDN: Mobile Subscriber ISDN Number. RFC: Request for Comments (RFC) documents are a series of memoranda encompassing new research, innovations, and methodologies applicable to Internet technologies. RFC documents are issued with a unique serial number. SOAP: Simple Object Access Protocol an XML-based protocol used for the exchange of information. It consists of three parts: an envelope that defines a framework for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined data types, and a convention for representing remote procedure calls and responses. SOAP Application: A software entity that produces, consumes or otherwise acts upon SOAP messages in a manner conforming to the SOAP processing model. SOAP Body: The body element of a SOAP document acts as a container for the data being delivered by the SOAP message. The data within the SOAP body is often referred to as the payload. SOAP Envelope: The Envelope is the top element of the XML document representing the message. SOAP Header: The Header element is encoded as the first immediate child element of the SOAP Envelope XML element. All immediate child elements of the Header element are called header entries. Synchronous: An interaction is said to be synchronous when the participating agents must be available to receive and process the associated messages from the time the interaction is initiated until all messages are 18
actually received or some failure condition is determined. The exact meaning of available to receive the message depends on the characteristics of the participating agents (including the transfer protocol it uses); it may, but does not necessarily, imply tight time synchronization, blocking a thread, etc. Web Service: A Web Service is a software system designed to support interoperable machine-to-machine interaction over a network. It has an interface described in a machine-processable format (specifically WSDL). Other systems interact with the Web Service in a manner prescribed by its description using SOAP-messages, typically conveyed using HTTP with an XML serialization in conjunction with other Web-related standards. WSDL: Web Services Description Language is an XML format for describing network services as a set of endpoints operating on messages containing either document-oriented or procedure-oriented information. The operations and messages are described abstractly, and then bound to a concrete network protocol and message format to define an endpoint. Related concrete endpoints are combined into abstract endpoints (services). WSDL is extensible to allow description of endpoints and their messages regardless of what message formats or network protocols are used to communicate. It consolidates earlier proposals in this area including NASSL, SCL and SDL. XML: Extensible Markup Language. It is an extensible document language for specifying document content (i.e. data). XML is not a single, predefined markup language: it is a meta language -- a language for describing other languages -- which lets you design your own markup. A predefined markup language like HTML defines a way to describe information in one specific class of documents only: XML lets you define your own customized markup languages for limitless different classes of documents. It can do this because it is written in SGML, the international standard meta language for text markup systems. 7. Frequently Asked Questions Q - The URL provided by tyntec for Global Number Portability or Global Number Verification doesn t work. A - Check firewall settings to ensure that requests to URLs with a port number other than 80 are indeed permitted. If in doubt, please connect to the following URL (http://support.tyntec.biz:8968) and report to tyntec Support the date and time of the attempted connection. Q - I am able to send the request, but I do not receive a response. A - The IP address from which the request originates must be the same as the IP address you have provided to tyntec, otherwise you will not receive a response from tyntec. If you are using tyntec s Flexible-Respond-Back- URL feature, verify that the IP address of the Respond-Back-URL has been registered with tyntec. If the IP address has not been registered with tyntec, the request may have been intercepted by the customer s firewall as an unrecognized IP address. The IP addresses of all Respond-Back-URLs must be registered with tyntec s Support Team. tyntec Support must also be notified of all changes to IP addresses. Q - Why do I receive multiple Check Delivery Requests with the same ID? A - In the event that your server is unable to process a request, e.g. an error generating the XML document, the Check Delivery Request will be resent. Please check your processes for receiving Check Delivery Requests. Q - I can send a request and receive back a message ID, but I do not get any results A - The URL to which results are to be directed must be registered at tyntec. Please check that the URL has the same IP address as the originating request (see also the second question in this FAQ section). Also, please ensure that your SOAP-Service that accepts the results is running. The service must be kept running even if you have sent all requests, since there is a time delay between request and receipt of result. If you use a firewall, please ensure that tyntec s IP address (i.e., the IP address you sent the requests to) is accepted. Q - I do not receive results for operator xyz any more. 19
A - The operator s name may have changed, while you are still using a transcription table based on the names of operators. Please now refer to a transcription table containing MCC +MNC or the TynTecID parameter. Q - Why do I receive an authorization failure? A - An authorization failure can be caused by an incorrect username and/or password. Please contact tyntec Support to verify your user details. If you have a test account and have previously been able to send requests successfully you may have reached your test message limit. Q - How do I know when my test message limit has been reached? A - If you attempt to send messages beyond your test account limit, you will receive an HTTP 401 Error (Unauthorized). Q - I receive the same Check Delivery Request repeatedly, or results come in very slowly. What can I do? A - There are two possibilities for receiving multiple Check Delivery Requests: 1) tyntec received a Check Delivery Response with an error message included, or 2) There was a problem in the communication process. In the case of an error message in a Check Delivery Response, the Check Delivery Request will be resent, regardless of the content of the error message. If for some reason you no longer wish to receive a certain Check Delivery Request, please return a Check Delivery Response without an error message. A communication problem is most frequently caused by an improperly structured Check Delivery Response. The Check Delivery Response may have incorrect syntax which could not be parsed by the XML compiler. Alternatively, a Check Delivery Response may never have been successfully sent. In either case, the Check Delivery Request will be resent, since it cannot be determined whether the Check Delivery Request has been successfully received. Please make sure that your receiving service returns a proper SOAP-Envelope with a proper Check Delivery Response included in the SOAP-Body. Q - I send Check Requests but always get an error back. A - This can be caused by a number of reasons: 1) You have not supplied a username and/or password: Please make sure that you supply both in the HTTP Header in the Basic Authorization Scheme (Refer to RFC 2616). 2) The supplied username and/or password are invalid: Please check if you have mistyped the username and/or password provided to you. 3) The supplied number is not a valid phone number: the number must only consist of digits (except a leading +). Any other characters including spaces will not be accepted. 4) The Check Request cannot be parsed by our service: Please verify that the Check Request is equivalent to the example request given in this interface guide (refer to Section 4, Step 1). If you have created your program/ service with an automatic tool and the WSDL file supplied by tyntec, this should not happen. 8. Contact Information Please contact tyntec s Customer Relations for the enabling of features and for commercial conditions: Email: customer-relations@tyntec.com Phone: +49 700 TYNTECBIZ or +49 89 202 451 200 Fax: +49 89 202 451 101 20
Munich +49 (89) 202 451 100 London +44 (207) 436 0283 Singapore +65 6478 3020 San Fransisco +1.415.608.6127 E-Mail sales@tyntec.com www.tyntec.com Sophisticated Simplicity In Mobile Interaction