BITE API functions descriptions

Device Port 1.1

Operation getDeviceInfo
Description Get device properties for specified account or specified device (using User Agent). Contains additional parameter to pass 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.
Notes Currently this function resolves device info using UA only. Account ID may be zero. This will change in future.
Input Parameters accountId [may be anything for now] - customer identificator (string)
userAgent – device user agent (string)
UAProfile – device user agent profile URL(string)
Return value cabalities list – a map of key and values, where keys contain names of capabilities and values contain capabilities' values.
Operation getDeviceProperty
Description Get specific device property (capability) for specified account, or specified device (using User Agent). Contains additional parameter to pass 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.
Notes Currently this function resolves device info using UA only. Account ID may be zero. This will change in future.
Input Parameters accountId [may be anything for now] - customer identificator (string)
userAgent – device user agent (string)
UAProfile – device user agent profile URL(string)
property - capability key (string)
Return value capability value (string)
Operation getDeviceModel
Description Get device model (including manufacturer). Contains additional parameter to pass 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.
Notes Currently this function resolves device info using UA only. Account ID may be zero. This will change in future.
Input Parameters accountId – customer identificator (string)
userAgent – device user agent (string)
UAProfile – device user agent profile URL(string)
Return value Model name (string). For example, "Nokia 6100"
Operation getDeviceProperty
Description Get specific device property (capability) for specified account, or specified device (using User Agent). Contains additional parameter to pass 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.
Notes Currently this function resolves device info using UA only. Account ID may be zero. This will change in future.
Input Parameters accountId [may be anything for now] - customer identificator (string)
userAgent – device user agent (string)
UAProfile – device user agent profile URL(string)
property - capability key (string)
Return value capability value (string)
Operation getDeviceModelsList
Description Gets list of devices information about which is available on the system.
Input Parameters N/A
Return value Models list. An array of maps, where keys are brand names and values are model names.
Operation getDeviceModelsProperty
Description Gets list of devices model names with a capability value defined in a parameter.
Input Parameters property – capability key (string)
Return value Models list. An array of maps, where keys are brand and model string and values are capability values.

Device Port

Operation getDeviceInfo
Description Get device properties for specified account or specified device (using User Agent).
Notes Currently this function resolves device info using UA only. Account ID may be zero. This will change in future.
Input Parameters accountId [may be anything for now] - customer identificator (string)
userAgent – device user agent (string)
Return value cabalities list – a map of key and values, where keys contain names of capabilities and values contain capabilities' values.
Operation getDeviceProperty
Description Get specific device property (capability) for specified account, or specified device (using User Agent)
Notes Currently this function resolves device info using UA only. Account ID may be zero. This will change in future.
Input Parameters accountId [may be anything for now] – customer identificator (string)
userAgent – device user agent (string)
property - capability key (string)
Return value capability value (string)
Operation getDeviceModel
Description Get device model (including manufacturer).
Notes Currently this function resolves device info using UA only. Account ID may be zero. This will change in future.
Input Parameters accountId – customer identificator (string)
userAgent – device user agent (string)
Return value Model name (string). For example, "Nokia 6100"
Operation getDeviceModelsList
Description Gets list of devices information about which is available on the system.
Input Parameters N/A
Return value Models list. An array of maps, where keys are brand names and values are model names.
Operation getDeviceModelsProperty
Description Gets list of devices model names with a capability value defined in a parameter.
Input Parameters property – capability key (string)
Return value Models list. An array of maps, where keys are brand and model string and values are capability values.

Billing Port 1.2

Operation billAccount
Description Bill customer account for service by action.
Input Parameters accountId – account identificator or MSISDN (if SMS-based service) (string)
serviceId – service identificator (integer)
actionId – action identificator (integer)
amount – amount for billing (float)
currency – currency for billing (string) (LTL or LVL)
serviceData - additional transaction information (max 250 characters), eg. what was purchased (string)
Return value Transaction Id or faultcode ( -1: system error, -2: insufficient balance, -3: account/service not found, -4: account blocked exception, -5: account unresolved, -6: account is suspended, -7: USSD failure, -8: subscription not found)
Operation openBillingTransaction
Description Open billing transaction which can be rollbacked or commited later.
Input Parameters accountId – account identificator or MSISDN (if SMS-based service) (string)
serviceId – service identificator (integer)
actionId – action identificator (integer)
amount – amount for billing (float)
currency – currency for billing (string) (LTL or LVL)
serviceData - additional transaction information (max 250 characters), eg. what was purchased (string)
Return value Transaction Id or error code ( -1: system error, -2: insufficient balance, -3: account/service not found, -4: account blocked exception, -5: account unresolved, -6: account is suspended)
Operation commitTransaction
Description Commit billing transaction.
Input Parameters transactionId – transaction identificator (integer)
Return value N/A
Operation rollbackTransaction
Description Rollback billing transaction.
Input Parameters transactionId – transaction identificator (integer)
Return value N/A

Billing Port 1.1

Operation billAccount
Description Bill customer account for service by action.
Input Parameters accountId – account identificator or MSISDN (if SMS-based service) (string)
serviceId – service identificator (integer)
actionId – action identificator (integer)
amount – amount for billing (float)
currency – currency for billing (string) (LTL or LVL)
Return value Transaction Id or faultcode ( -1: system error, -2: insufficient balance, -3: account/service not found, -4: account blocked exception, -5: account unresolved, -6: account is suspended)
Operation openBillingTransaction
Description Open billing transaction which can be rollbacked or commited later.
Input Parameters accountId – account identificator or MSISDN (if SMS-based service) (string)
serviceId – service identificator (integer)
actionId – action identificator (integer)
amount – amount for billing (float)
currency – currency for billing (string) (LTL or LVL)
Return value Transaction Id or error code ( -1: system error, -2: insufficient balance, -3: account/service not found, -4: account blocked exception, -5: account unresolved, -6: account is suspended)
Operation commitTransaction
Description Commit billing transaction.
Input Parameters transactionId – transaction identificator (integer)
Return value N/A
Operation rollbackTransaction
Description Rollback billing transaction.
Input Parameters transactionId – transaction identificator (integer)
Return value N/A

Billing Port

Operation billAccount
Description Bill customer account for service by action.
Input Parameters accountId – account identificator or MSISDN (if SMS-based service) (string)
serviceId – service identificator (integer)
actionId – action identificator (integer)
amount – amount for billing (float)
currency – currency for billing (string) (LTL or LVL)
Return value N/A
Operation openBillingTransaction
Description Open billing transaction which can be rollbacked or commited later.
Input Parameters accountId – account identificator or MSISDN (if SMS-based service) (string)
serviceId – service identificator (integer)
actionId – action identificator (integer)
amount – amount for billing (float)
currency – currency for billing (string) (LTL or LVL)
Return value Transaction identificator (integer)
Operation commitTransaction
Description Commit billing transaction.
Input Parameters transactionId – transaction identificator (integer)
Return value N/A
Operation rollbackTransaction
Description Rollback billing transaction.
Input Parameters transactionId – transaction identificator (integer)
Return value N/A

Provider port

Operation getServices
Description Return partner's services.
Input Parameters N/A
Return value List of provider's services. An array of maps. Each map contains a value which is service name for key – service identificator.
Operation getFunctions
Description Return a list of actions (functions) available for specific provider's service.
Input Parameters serviceId - service identificator (integer)
Return value List of actions. Each item of the list is a map, which contains these properties for each action: {action_id, provider_id, service_id, provider_currency, provider_price, user_currency, user_price, valid_from, user_billing_data}.
Operation getAccountByIP
Description Resolves account identificator by IP address.
Input Parameters headerIpAddress – current dynamic IP address of mobile device (string)
ipAddress – remote IP address (GW) (string)
Return value Account identificator (string)
Status Deprecated. Will be removed. Account id can be acquired from HTTP header Bite-Account-Id.
Operation getMsisdn
Description Resolves account msisdn either by IP address or account id.
Input Parameters headerIpAddress – current dynamic IP address of mobile device (string) (can be null, ipaddress should also be null then, accountId cannot be null then)
ipAddress – remote IP address (GW) (string) ( can be null, headerIpAddress should also be null then,accountId cannot be null then)
accountId – account ID (can be null, ipAddress and headerIpAddress cannot be null then)
Attention! To resolve msisdn using IP address is not possible in Latvia, in the near future this function will not work in Lithuania either. To resolve msisdn please use account id.
Return value Account msisdn (long)

Subscriptions port 1.1

Operation subscribeAccount
Description Subscribes customer account to specified service.

Note: To use renewal in several days, service must have certain actions with proper prices.
Using function subscribeAccount actions: renewDay (action_id = 111) and renewCustom (action_id = 114) must be defined.
renewCustom should have price that will be used to bill customer every "X" days. Max term in days is 35.
renewDay price is used to calculate renewCustom price.
Example: If renewal in 3 days with price 3.0 (LTL or LVL) is needed, prices should be calculated like this: 1.0 (renewDay) * 3 (number of days) = 3.0 (renewCustom).
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
term – subscription term (string). Allowed values are: “HOUR”,”DAY”, “WEEK”, “MONTH”, “UNDEF”.
termUnit - parameter is used when needed term is several days (string). Allowed values are: ”D”, “null”.
renewal – renewal term (string). Allowed values are: “N” - None, “D” - day, “W” - week, “M” - month.
Example: If renewal is needed in several (“X”) days, use such parameters values: term "X", termUnit “D”, renewal "X".
Return value N/A
Operation subscribeAndDefineFirstBill
Description Subscribes customer account to specified service and lets to define the first subscription billing amount, which may be different from the subscription renewal price.

Note: To use renewal in several days, service must have certain actions with proper prices.
Using function subscribeAccount actions: renewDay (action_id = 111), renewCustom (action_id = 114) and billAccount (usually, action_id = 350) must be defined.
renewCustom should have price that will be used to bill customer every "X" days.
renewDay price is used to calculate renewCustom price.
Example: If renewal in 3 days with price 3.0 (LTL or LVL) is needed, prices should be calculated like this: 1.0 (renewDay) * 3 (number of days) = 3.0 (renewCustom).
Selection of price for billAccount is unconstrained.

Note (2): Operation subscribeAndDefineFirstBill do not check if subscription exists for specified account.
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
term – subscription term (string). Allowed values are: “HOUR”,”DAY”, “WEEK”, “MONTH”, “UNDEF”.
renewal – renewal term (string). Allowed values are: “N” - None, “D” - day, “W” - week, “M” - month.
actionId – action identificator of the first subscription billing amount (integer); (usually 350).
amount – the first subscription billing amount (float).
currency – a currency code to bill the subscriber (LVL, LTL); (string).
termUnit - parameter is used when needed term is several days (string). Allowed values are: ”D”, “null”.
Example: If renewal is needed in several (“X”) days, use such parameters values: term "X", renewal "X", termUnit “D”.
Return value N/A
Operation unsubscribeAccount
Description Unsubscribes customer account from specified service
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
Return value N/A
Operation checkSubscription
Description Return subscription status
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
Return value Subscription information along with status code(integer): { account_id, created, expiration, status, renewal }. Available values are for status: 0 – Active, 1 – Expired, 2 - Inactive, 4 – Terminated, -1 – status not available.
Operation getSubscribers
Description Return service subscriptions
Input Parameters serviceId - service identificator (integer)
page – page number (every page consists of 50000 subscribers, pages are numbered from 1)
Return value List of service subscripions. Array of maps. Each list item is a map which contains following properties for each subscription: { account_id, created, expiration, renewal}

Subscriptions port

Operation subscribeAccount
Description Subscribes customer account to specified service
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
term – subscription term (string). Allowed values are: “HOUR”,”DAY”, “WEEK”, “MONTH”, “UNDEF”.
renewal – renewal term (string). Allowed values are: “N” - None, “D” - day, “W” - week, “M” - month.
Return value N/A
Operation subscribeAndDefineFirstBill
Description Subscribes customer account to specified service and lets to define the first subscription billing amount, which may be different from the subscription renewal price.
Note: Operation subscribeAndDefineFirstBill do not check if subscription exists for specified account.
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
term – subscription term (string). Allowed values are: “HOUR”,”DAY”, “WEEK”, “MONTH”, “UNDEF”.
renewal – renewal term (string). Allowed values are: “N” - None, “D” - day, “W” - week, “M” - month.
actionId – action identificator of the first subscription billing amount (integer).
amount – the first subscription billing amount (float).
currency – a currency code to bill the subscriber (LVL, LTL); (string).
Return value N/A
Operation unsubscribeAccount
Description Unsubscribes customer account from specified service
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
Return value N/A
Operation checkSubscription
Description Return subscription status.
Input Parameters accountId - customer account identificator or MSISDN (if SMS-based service) (string)
serviceId - service identificator (integer)
Return value Subscription information along with status code(integer): { account_id, created, expiration, status, renewal }. Available values are for status: 0 – Active, 1 – Expired, 2 - Inactive, 4 – Terminated, -1 – status not available.
Operation getSubscribers
Description Return service subscriptions
Input Parameters serviceId - service identificator (integer)
Return value List of service subscripions. Array of maps. Returns not more than 50000 items. Each list item is a map which contains following properties for each subscription: { account_id, created, expiration, renewal}

Messaging port

Operation sendSMS
Description Sends SMS to the specified customer, either immediately or at specified time.
Input Parameters acount_ids - array of accounts. If message should be sent to single account, array consists of one element. This can be null to send messages to all of the subscribers of the current service (string[]).
msisdns - array of msisdns. If message should be sent to single msisdn, array consist of one element. Account_ids and msisdns can be provided to this function together or can be provided one of them (long[]).
billAmount – an amount to bill the recipient(s) (float).
billCurrency – a currency to bill the recipient(s) (LVL,LTL); (string).
smsSender – message sender number (string).
smsBody – message body (string).
smsLanguage – message language code (LT,LV,RU,EN); (string), optional.
smsHeaders – sms headers (string), optional.
startDeliveryTime – when to start the delivery (date, ISO 8601), optional.
endDeliveryTime – end time for delivery (date, ISO 8601), optional.
giveNotification – store delivery report (boolean).
Return value message id (string)
Operation sendWAPPush
Description Sends WAP PUSH message (Service Indication) to the specified customer, either immediately or at specified time.
Input Parameters acount_ids - array of accounts. If message should be sent to single account, array consists of one element. This can be null to send messages to all of the subscribers of the current service (string[]).
msisdns - array of msisdns. If message should be sent to single msisdn, array consist of one element. Account_ids and msisdns can be provided to this function together or can be provided one of them (long[]).
URL – service URL to send (string).
title – service title to send (string).
expirationTime – expiration time (date, ISO 8601); optional.
language – message language code (LT,LV,RU,EN); (string), optional.
billAmount – an amount to bill the recipient(s) (float).
billCurrency – a currency code to bill the recipient(s) (LVL,LTL); (string).
startDeliveryTime – when to start the delivery (date, ISO 8601), optional.
endDeliveryTime – end time for delivery (date, ISO 8601), optional.
giveNotification – store delivery report (boolean).
Return value message id (string)
Operation sendSMSDirect
Description Sends SMS to the specified customer without putting it to queue.
Input Parameters unique_id – external unique ID (string).
acount_id – account ID to which the message should be sent (string).
msisdns – msisdn to which the message should be sent (long).
URL – service URL to send (string).
title – service title to send (string).
expirationTime – expiration time (date, ISO 8601); optional.
language – message language code (LT,LV,RU,EN); (string), optional.
billAmount – an amount to bill the recipient(s) (float).
billCurrency – a currency code to bill the recipient(s) (LVL,LTL); (string).
startDeliveryTime – when to start the delivery (date, ISO 8601), optional.
endDeliveryTime – end time for delivery (date, ISO 8601), optional.
giveNotification – store delivery report (boolean).
Return value List of values:
sms_sent_count – the number of SMS messages.
transaction_id – the id of billing transaction. The value of this parameter is “0” if transaction completed with error.

MM7 (MMS) port

Operation submit
Description Sends MMS
Input Parameters MM7 submit request document
Return value MM7 submit response document

 
api_reference_guide.txt · Last modified: 2011/02/23 12:25 by admin