BiteAPI User's Guide

BiteAPI is a HTTP/SOAP interface to Bite Plus mobile internet system, which allows third parties to perform WAP billing and other functions needed by third parties developing premium WAP products. It is oriented towards a mini-wap-site type of product, but can also be used for SMS or MMS based services.

The guide is written for developers writing applications using BiteAPI web services interface. It includes general information and overview of operations which can be performed using BiteAPI web services interface. For a complete functional specification please consult the reference.

The principal elements involved in building a mobile Internet premium service from provider perspective are Your mobile www/wap SITE, the user phone which displays the pages, and BITE API which helps your site perform billing and messaging actions towards the user phone/account.

BITE API is accessible via Internet using SOAP over HTTP.

Few things are important when using the BiteAPI web services interface. First, the provider authentication is done using basic HTTP authentication method. Therefore, the interface expects properly encoded username and password within the HTTP headers. All major SOAP client APIs on different platforms and programing languages include the programmatic method to set the HTTP authentication headers within the SOAP request. Second, all SOAP requests to BiteAPI web services interface require appropriate SOAP headers which include provider and service information. Each call must be associated with some service to be properly identified. The system will not allow any requests without this information. Finally, each SOAP call must be accompanied by a proper value of SOAPAction HTTP header which is empty by default on some platforms ( e.g. PHP ). See appendix for a list of SOAPAction header values for each operation.

Note:
SOAPAction header values are non-physical URI's which just describe the SOAP action itself. Real URIs for each port are listed in the appendix. Many clients will be happy using port WSDL files which are located at http://soap.bite.lt/biteapi/axisinfo. General concepts

Each content provider (i.e. a legal entity) has his own user name and password which must be used to autenthicate to the API system.

Each Provider can operate many premium services, for example “Weather reports” and “Adult mini-site”. A service is something which is understood by the user as a single premium service, and has a human understandable descripion and an URL to it’s home.

A service is supplied for a given market. Therefore, running the same service in Lithuania and Latvia still requires to set up 2 separate services to reflect currency and accounting differences.

Each service is delivered to the user via paid Actions, such as “Java File download” or “Payment for WAP site access”, or “SMS to the user”. Each action has one or more prices that the end-user can be charged, and may have an associated cost for the provider too (in case of sending SMS to the user). Please consult appendix for a list of billable actions and their descriptions.

All configuration of the API including partner account setup, service setup, price setup and other administrative activities are performed by a person responsible of managing the partners services, their actions and prices. Email: partner_support@bite.lt.

All end users are identified by their unique Account ID. When the user passes through the Internet Gateway, the Account ID becomes available. All other persons who are browsing your site and who are not BITE network users will not have the Account ID.

Account ID is never reused, it is unique to the very phone number and person using it.

Account ID along with other account information (such as country and language) is available through special HTTP headers (added when the request passes Bite gateway; automatically for all Bite accounts). For account ID - “Bite-Account-Id” header value, for country - “Bite-Account-Country” header value, for language - “Bite-Account-Language” header value.

Warning:
Provider should never use the Account ID which was acquired outside Bite network. Only those which have been collected from the user request passing the Bite gateway are allowed. Check the appendix for a list of Bite gateway's for a time of writing.

BiteAPI interface defines several web service ports:

• Device port.
• Billing port
• Subscription port
• Messaging port
• Provider port

Each port groups several functions similar by their nature and context of use. WSDL files for all ports are provided at the following address: http://soap.bite.lt/biteapi/axisinfo.

Device port contains functions to get information about mobile equipment devices known to the system. These functions expect device User Agent as input parameter.

Note:
Future versions of BiteAPI will accept the account ID as an input parameter to substitute the User Agent parameter which will become optional.

Device information functions are useful to identify the capabilities for a concrete device to, for example, adapt the content to be properly handled. Check the appendix for a list of available device properties.

Note:
An updated version of Device Port (version 1.1) contains additional parameter to pass the user agent profile URL, in case it's available and/or user agent is not available. Profile is used to fetch and store the capabilities information for later use and additionally uniquily identify the device if user agent is not available. Some latest mobile equipment software doesn't include their user agent information into WAP request headers, instead only the user agent profile URL is provider.

BiteAPI allows partners to perform billing transactions to bill their users (accounts). Transaction opening, committing, and roll backing is supported along with plain untransactional billing, which allows to perform single step billing in cases where transactions are not feasible. To bill or open a billing transaction several input parameters have to be supplied. They identify an account to bill, a service and associated account action to be billed for as well as price and currency.

To open transaction openBillingTransaction function is used. It returns an ID of transaction being opened. If an error occurred during operation a soap fault is generated providing error information. Having an opened transaction the partner can now operate within current transaction context and use a commit function in case of successful partner operation or rollback the transaction in case of failure. Both commit and rollback functions use the same transaction ID returned when transaction was opened.

There are cases when it's not possible to perform operation or a group of operations within transactional context due to the limitations posed by the nature of these operations. In such cases billAccount function should be used. It accepts the same parameters as transactional openBillingTransaction function. Each account action is associated with a list of allowed prices (with specified currencies). It's disallowed to perform billing operation with prices outside these values. Prices and actions are managed by system manager.

Billing Port 1.1 functions billAccount and openBillingTransaction after successful billing process returns transaction id, on the other case returns such negative value:

-1: system error;
-2: insufficient balance;
-3: account/service not found;
-4: account blocked exception;
-5: account unresolved.

Provider web services port contains functions to retrieve information for partners about their services and actions associated with concrete services which also includes prices information. To get a list of their services partners should use getServices function. Function getFunctions returns a list a allowed chargeable actions (for a specified service) partner can use and strictly informational actions showing other charging information. Each action returned by getFunctions contains a map with provider price, user price, currency and other properties containing appropriate values. Please consult the reference for a full list of properties returned by this function.

BiteAPI contains functions to manage subscriptions of partners' services. These can be used to subscribe and unsubscribe account as well as to get a list of subscribers for a specific service and check subscription status.

Subscriptions are renewed based on renewal policy defined in subscribe function which accept subscription term and renewal period parameters. Term parameter defines when subscription should be terminated after it was created. For example, after an hour, day, week or month. Renewal parameter defines when subscription should be renewed, for example, after an hour, one day, week or month. It's possible to pass special UNDEF or NONE values to these parameters to indicated undefined term and/or nonrenewable subscription. Please consult the reference guide for precise parameter values.

Note:
It's not allowed to pass UNDEF value to term parameter when renewal is not NONE ('N').

Initial subscription billing is performed according to term parameter and subscription renewal billing is performed according to renew parameter.

If renewal is needed in several (“X”) days, use Subscriptions port 1.1 functions subscribeAccount or subscribeAndDefineFirstBill. For these functions you must pass such term and renewal parameters values: term „X“, renewal „X“, termUnit “D”.

To get a list of all subscribers for a specific service a getSubscribers function should be used.

To check subscription status a checkSubscription function should be used. It returns an integer value which corresponds to a specific status. Please consult the reference guide for more detailed information of these values.

Billing subscriber on a regular basis (specified with renewal parameter) is performed automatically. Each service subscription renewal period (month, day, etc.) is assigned a price by the system administrator. This price is used to bill the account automatically. Therefore Bite API provides a convenient interface to manager subscriptions without taking care of routine billing.

It's possible to use BiteAPI web services interface to provider messaging-based services. BiteAPI web services interface provides several useful functions to send SMS and MMS messages as well as WAP pushes and bookmarks.

Note:
Messaging port is not fully implemented at the time of writing. Future versions will allow sending MMS messages using a provided client library.

To send SMS message to recipient or a group of recipients sendSMS function is used. Recipients are determined by an array of account Ids (which may also contain a single account id) and by an array of MSISDNs. Final list of message recipients contains both. Account Ids array should be null if message is intended for service subscribers. Passing null value to account ids array parameter will result message being sent to the subscribers of a current service (determined from a SOAP header. see 1.2 Request Scheme.). This is common to all messaging functions. Also all messaging functions accept parameters for billing purposes, bill amount and bill currency to bill the message recipient for. All billing operation s are transactional, therefore any message sending failure will result billing operation to be rollbacked.

Billing amount and currency should be in tune with a list of prices for the particular action (in this case , action is “send sms/mms/other”). Provider is not allowed to bill the recipient for an amount/currency if such a price is not created for that provider, service and action.

It's allowed to specify when the message should be actually sent as well as when the message becomes obsolete. Use startDeliveryTime and endDeliveryTime parameters.

Bite API provides a simplified version of MM7 protocol interface for accepting MMS messages for delivery to the real MMSC. Please consult 3GPP website, for a specification of MM7 protocol. Currently Bite API supports version 5.3.0 of MM7 protocol and additionally requires users to submit Bite API specific information in the SOAP headers of MM7 request message. Bite API MM7 port will not provide any MMSC debug responses other than error messages specific to Bite API, such as invalid or insufficient service or billing information.

This is a sample of SOAP header from a MM7 request message. It illustrate the Bite API specific requirements for message submission:

<soapenv:Header>
<mm7:TransactionID soapenv:mustUnderstand="0" xsi:type="xsd:string" xmlns:mm7="http://www.3gpp.org/ftp/Specs/archive/23_series/23.140/schema/REL-5-MM7-1-2">013A71AE3167C52F517E5D5D654159EB</mm7:TransactionID>
  <provider-service soapenv:mustUnderstand="0" xmlns="">
   <service-id>1055</service-id>
  </provider-service>
  <billing soapenv:mustUnderstand="0" xmlns="">
   <amount>0.1</amount>
   <currency>LTL</currency>
  </billing>
  <subscription soapenv:mustUnderstand="0" xmlns="">true</subscription>
 </soapenv:Header>

The provider-service header is common to all Bite API request messages and is documented elsewhere in this document. Message billing information is supplied in billing header. It includes an amount to bill the account for and currency. Subscription header element indicates if this message should be delivered to the subscribers of specified services or to the list of recipients specified in the body of MM7 request message. In case a text value of this header is “true”, the message will be sent to the subscribers of the service indicated in provider-service header and a recipient list in MM7 request message body will be ignored.

Finally MMS message will be accepted for a delivery (as notified with appropriate SOAP response) in case all Bite API requirements are met and message status can be tracked using delivery report functions in the messaging port.

Note:
Delivery reports function in the messaging port is at the beta stage.

For a typical mini-site, the following API functions may be used:

1. Identifying the end-user AccountID
   • Using Provider Port, getAccountByIP
2. Checking if the AccountID is a subscriber (for subscription services), subscribing/unsubscribing
   • Using Subscriptions Port, checkSubscription
3. Checking the capabilities of AccountID device
   • Using Device Port, getDeviceProperty (passing User Agent as parameter)
4. Charging the AccountID for successful download
   • Using Billing Port, billAccount
5. Charging the AccountID for access to premium areas
   • Using Billing Port, billAccount
6. Sending SMS to all service subscribers
   • Using Messaging port (to be implemented)

This section concentrates on providing instructions to access BiteAPI web services interface using different platforms, in particular PHP and Python. It includes general information on how to properly format SOAP request messages and interpret SOAP responses. BiteAPI web services interfaces strives to support all major platforms. Therefore typing information conceived by SOAP messages should be correctly interpreted by all SOAP client libraries. Collection and vector types were replaced with simple arrays and complex objects (value objects or beans) with maps (dictionaries), where keys contain property names and values - property values. Besides custom SOAP header and basic HTTP authentication BiteAPI web interface doesn't include any custom logic, typing or other constraints.

Depending on which version of PHP is used different SOAP client libraries might be used.

In PHP version 4, nuSOAP client library can be used. Consult it's website ( http://dietrich.ganx4.com/nusoap/index.php ) for more reference information. To access BiteAPI web services interfaces proper HTTP authentication and custom SOAP headers must be constructed and included in a request. Here is a sample PHP 4 class working a facade to the web service interface and using nuSOAP:

class SOAPManager {
 var $s; //SOAP client object
 var $conf; //Configuration file object
 
    function SOAPManager(){
        // READ CONFIGURATION
        $this->conf = new ini_file(dirname(__FILE__).'/../../ini/admlt_ini.php'); 
        $wsdl_url=$this->conf->read_var('soap', 'wsdl');
        $password=$this->conf->read_var('soap', 'password');
        $user=$this->conf->read_var('soap', 'user');
        $service_id=$this->conf->read_var('soap', 'service_id');
 
		// NEW SOAP CLIENT INSTANCE
        $this->s = new soapclient($wsdl_url);
 
		// HTTP BASIC AUTHENTICATION
        $this->s->setCredentials($user,$password);
 
 // CUSTOM SOAP HEADER REQUIRED BY BiteAPI
        $this->s->setHeaders("<provider-service><service-id>$service_id</service-id></provider-service>"); 
    }
    function getDeviceModelsList(&$err) {
        // REQUEST PARAMETERS
        $param = array();
 
		// SOAP CALL. SOAP action is the last parameter.
        $res = $this->s->call('getDeviceModelsList', $param, 'http://biteapi.metasite.net/device','http://biteapi.metasite.net/device/getDeviceModelsList'); 
 
		if (!$err = $this->s->getError()) {                     
            return $res['getDeviceModelsListReturn'];           
        } else {    
            return;                                            
        }
    }
}

For testing purposes you should hardcode the following account ID: 2219983

<provider-service>
    <service-id>1231231</service-id>
</provider-service>

213.226.131.21
213.226.131.132
213.226.131.133
213.226.131.154
213.226.131.141
213.226.131.149
213.226.131.151
84.15.15.4
84.15.15.5
84.15.15.10
84.15.15.11
84.15.15.12

Device Port
http://soap.bite.lt/biteapi/services/DevicePort

Device Port 1.1
http://soap.bite.lt/biteapi/services/1.1/DevicePort

Messaging Port
http://soap.bite.lt/biteapi/services/MessagingPort

Provider Port
http://soap.bite.lt/biteapi/services/ProviderPort

Subscriptions Port 1.1
http://soap.bite.lt/biteapi/services/1.1/SubscriptionsPort

Subscriptions Port
http://soap.bite.lt/biteapi/services/SubscriptionsPort

Billing Port 1.1
http://soap.bite.lt/biteapi/services/1.1/BillingPort

Billing Port
http://soap.bite.lt/biteapi/services/BillingPort

MM7 Port
http://soap.bite.lt/biteapi/services/MM7Port

Device Port 1.1
http://biteapi.metasite.net/device/1.1/getDeviceModelsList
http://biteapi.metasite.net/device/1.1/getDeviceInfo
http://biteapi.metasite.net/device/1.1/getDeviceProperty
http://biteapi.metasite.net/device/1.1/getDeviceModel
http://biteapi.metasite.net/device/1.1/getDeviceModelsProperty

Device Port
http://biteapi.metasite.net/device/getDeviceModelsList
http://biteapi.metasite.net/device/getDeviceInfo
http://biteapi.metasite.net/device/getDeviceProperty
http://biteapi.metasite.net/device/getDeviceModel
http://biteapi.metasite.net/device/getDeviceModelsProperty

Messaging Port
http://biteapi.metasite.net/messaging/sendSMS
http://biteapi.metasite.net/messaging/sendWAPPush
http://biteapi.metasite.net/messaging/sendSMSDirect

Provider Port
http://biteapi.metasite.net/provider/getServices
http://biteapi.metasite.net/provider/getFunctions
http://biteapi.metasite.net/provider/getAccountByIP
http://biteapi.metasite.net/provider/getMsisdn

Subscriptions Port 1.1.
http://biteapi.metasite.net/subscriptions/getSubscribers
http://biteapi.metasite.net/subscriptions/checkSubscription
http://biteapi.metasite.net/subscriptions/unsubscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAndDefineFirstBill

Subscriptions Port
http://biteapi.metasite.net/subscriptions/getSubscribers
http://biteapi.metasite.net/subscriptions/checkSubscription
http://biteapi.metasite.net/subscriptions/unsubscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAccount
http://biteapi.metasite.net/subscriptions/subscribeAndDefineFirstBill

Billing Port 1.1
http://biteapi.metasite.net/billing/billAccount
http://biteapi.metasite.net/billing/openTransaction
http://biteapi.metasite.net/billing/commitTransaction
http://biteapi.metasite.net/billing/rollbackTransaction

Billing Port
http://biteapi.metasite.net/billing/billAccount
http://biteapi.metasite.net/billing/openTransaction
http://biteapi.metasite.net/billing/commitTransaction
http://biteapi.metasite.net/billing/rollbackTransaction

MM7 Port
http://biteapi.metasite.net/messaging/sendMMS

Group:product_info (human readable brand and model name and other generic info)

Group:wml_ui (User Interface for WML browser)

Group:chtml_ui (User Interface for Compact HTML i;Mode browser)

Group:xhtml_ui (User Interface for HTML/XHTML-MP browser)

Group:markup supported mark languages

Group:cache

Group:display

Group: image_format

Group:bugs

Group:wta

Group:security

Group:storage

Group:object_download

Group:drm

Group:streaming

Group:wap_push

Group:mms

Group:sms Binary SMS and SCKL capabilities.

Group:j2me
NOTE: this group has been totally reviewed, old tags don't exist any more, check out the new tags
Group mentors: José Manuel Cantera Fonseca and Cristian Rodriguez from Telefonica I+D

Group:sound_format (supported sound formats)