Web services 3.5

From Complete Cyclos documentation wiki
Jump to: navigation, search

This page is for Cyclos 3.5. Interfaces have changed slightly in 3.6. For the 3.6 Web services documentation, click here

Cyclos offers several web services, targeted for integration with external applications, using Apache CXF.

Security

In order to use web services, clients should be registered in the application through the Settings > Service clients menu. Here, an IP address or hostname (to allow dynamic ip resolution) should be provided, as well as which permissions does that client have.

Also, a client may be restricted to an specific member, forcing operations made by that client to be related to that member.

Writing client applications

Here are some general guidelines on how to write client applications to access web services in Cyclos. Take a look at the code samples section for some examples.

Java client

It is very easy to create Java clients for web services, since Apache CXF allows creating transparent proxies using Java interfaces, similar to RMI.
In order to create the client, there are several required library files (jars). The first one is located at <cyclos download dir>/ws/cyclos_xxx_ws_client.jar, and is available on the main distribution package. Others dependencies are also required on runtime. They are available in <cyclos download dir>/web/WEB-INF/lib. They are:

  • commons-lang-xxx.jar
  • cxf-xxx.jar
  • jaxb-impl-xxx.jar
  • wsdl4j-xxx.jar
  • xml-resolver-xxx.jar
  • XmlSchema-xxx.jar

The client application should use the CyclosWebServicesClientFactory class, which may be instantiated with the cyclos root url as constructor argument or it may be set through setter method. Also, when the Service Client registered in Cyclos uses an username / password, they can be set either as constructor arguments or setter methods. Then, it provides two ways to retrieve service interface proxies:

  • getAccessWebService(), getAccountWebService(), getAdWebService(), getFieldWebService(), getMemberWebService(), getPaymentWebService(), getWebShopWebService(): return proxies for specific web services
  • proxyFor(Class): Given a web service interface, the result is a proxy for it

The CyclosWebServicesClientFactory should be instantiated only once and reused between calls. It is thread safe.

Clients in other languages

Many web sites are written in other languages, such as PHP, Ruby, Python, .NET... Those languages often provide a SOAP library. The problem is that some of them don't generate compatible XML with the specification, and some interoperability problems may arise. However PHP, which is the most widely used language for dynamic sites, have a native SOAP client since version 5, which plays well with Cyclos. All WSDLs use the document style for calls, and all methods results have a single element named 'return'.

Code samples

Here are some code samples for web service clients:

POS payment (java)
Random advertisements (php)
Complete advertisements search form / result (php)
WebShop payment (php)


Available web services

There are several web services in cyclos. A list can be seen at the address: <cyclos root url>/services.

Payment

Payment web service allows external applications to generate payments under Cyclos. A typical use case would be a POS (Point-Of-Sale) application installed in a member's office or a website from the organization itself that uses Cyclos as a backend and generates the payments directly.

To perform payments through this web service, a channel should be registered in Cyclos, granted to member groups and members should choose to participate in this channel. It's possible to set by group the default selected channels for new members also.

The most generally used method is doPayment(PaymentParameters), which performs a single payment directly. When the client is restricted to a member, the payment is either from an arbitrary member to the restricted member, with pin or from the restricted member to other members. The former is the common case for a POS application, where a member types his username and pin, and a payment is performed. When the client is not restricted, then both from and to member should be passed, and no pin is used. A variation of this method is doBulkPayment(List<PaymentParameters>), which is only usable when the client is not restricted to a member. This method perform several payments in the given sequence, under the same transaction (they are all guaranteed to succeed or fail atomically).

Another possible operation is a payment request. To do this, the registered channel in Cyclos needs to set the URL for a payment request web service, which is a web service implementing the PaymentRequestWebService interface provided in <cyclos mail download dir>/ws/cyclos_xxx_external_ws.jar. Then. a request may be sent using requestPaymentConfirmation(RequestPaymentParameters). A member may then confirm in another channel, which should then invoke confirmPayment(ConfirmPaymentParameters). This is a more advanced feature, and requires other web services to be implemented apart from Cyclos.

Available operations:

doPayment: Performs a single payment, returning the payment status. For clients restricted to a member, one of fromMemberUsername or toMemberUsername (or setting the toSystem flag) should be passed, with the other one assumed as the restricted member. In this case, when fromMemberUsername is used, his pin should also be informed.

  • Input parameters:
    • fromMember (string): The login name of the member performing the payment.
    • fromSystem (boolean): Only used when performing payment from a system account by a client which is not restricted to a member.
    • toMember (string): The login name of the member receiving the payment.
    • toSystem (boolean): Only used when performing payment to a system account by a client which is not restricted to a member.
    • amount (decimal): The payment amount. Required.
    • currency: Either the currency symbol or identifier. When not set, uses the default account's currency for the actual member.
    • credentials (string): The payer member pin. Only used when the client is restricted to a member, when it's required.
    • description (string): The generated payment description. Optional, defaulting to the payment type description.
    • transferTypeId (integer): The payment type identifier. Optional, defaulting to the first payment type enabled to the given currency (or default if not specified) which is enabled to the service client's channel.
    • customValues (array of fieldValue): The custom field values for this payment. Each array item contains the field internal name and the value.
  • Result:
    • status (enumerated): The payment status. May be one of:
      • PROCESSED: The payment was successfully processed
      • PENDING_AUTHORIZATION: The payment was created, but is awaiting authorization
      • INVALID_PIN: Invalid PIN was entered
      • INVALID_CHANNEL: The payment was being performed from a channel the member doesn't have access
      • INVALID_PARAMETERS: One or more parameters were invalid
      • NOT_ENOUGH_CREDITS: The payment couldn't be performed, because there was not enough amount on the source account
      • MAX_DAILY_AMOUNT_EXCEEDED: The payment couldn't be performed, because the maximum amount today has been exceeded
      • RECEIVER_UPPER_CREDIT_LIMIT_REACHED: The payment couldn't be performed, because the destination account would surpass it's upper credit limit
      • UNKNOWN_ERROR: Any other unexpected error will fall in this category
    • transfer (AccountHistoryTransferVO): Contains data about the generated payment

There is a code sample for performing POS payments in a Java client: Web services/POS Payment.

doBulkPayment: Performs several payments, returning a payment status for each input parameter. Only usable when the client is not restricted to a member. Has the same input parameter as doPayment(), but in a collection. The result is also a collection, one for each input.


simulatePayment: Simulates a payment. The input parameters are the same as doPayment(), but the result is only the payment status. No payment is actually performed.


requestPaymentConfirmation: Starts a payment request. The destination member should, using another (or the same) channel, accept this request and a payment is generated.

  • Parameters:
    • fromMember (string): The login name of the member performing the payment. Required.
    • toMember (string): The login name of the member receiving the payment. When the client is restricted to a member, that will be the forced. Otherwise, this is required.
    • destinationChannel (string): The channel that a member is supposed to receive the payment request. It should be the internal name of a channel which supports payment requests, as explained above. Required.
    • amount (decimal): The payment amount. Required.
    • currency: Either the currency symbol or identifier. When not set, uses the default account's currency for the actual member.
    • description (string): The generated payment description. Optional, defaulting to the payment type description.
  • Result:
    • requestStatus (enumerated): The status for the request itself. May be:
      • SUCCESS: The payment request was delivered to the member.
      • INVALID_MEMBER: The member which should receive the request is invalid for the operation.
      • SYSTEM_OFFLINE: The channel's backend is offline.
      • UNKNOWN_ERROR: There was an unknown error while sending the request.
    • paymentStatus (enumerated): The status of a payment simulation. Since accepting the request may involve costs (for example: SMS), a payment simulation is done. Only if the payment would be successfully processed, the request is sent. For possible values, see the doPayment operation.
    • ticket (string): The ticket used to accept the request by the member.


confirmPayment: Used to confirm a payment request, and should have a matching requestPaymentConfirmation previous invocation.

  • Parameters:
    • ticket (string): The same ticket returned from the requestPaymentConfirmation invocation. Required.
    • credentials (string): The pin of the member performing the payment. Required.
  • Result: The same as the doPayment operation.


expireTicket: Then the user will not confirm the payment, a ticket expiration may be sent immediately using this method. Anyway, payment which are not confirmed within 1 hour are expired.

  • Parameters:
    • ticket (string): The ticket to expire. Required.
  • Result: A boolean flag indicating whether the ticket was really expired.


WebShop

External web shops may allow their customers to pay with Cyclos units, and need tickets to do so. The tickets provide a secure mechanism where the web shop can define the transaction data and initiate the payment but does not have access to member authentication data and payment confirmation. In order to do this, both the shop client and the shop itself must have a Cyclos account.

The following flow would be applied for the client member to pay to the web shop member:

  1. The member client selects on the web shop to pay with Cyclos units;
  2. The web shop requests the Cyclos server to create a ticket, passing the transaction information, together with a return url;
  3. The web shop redirects the client into the Cyclos external payment page, passing as parameter the ticket id (<root>/do/webshop/payment?ticket=<ticket id>);
  4. The client types his username and password and confirms the payment;
  5. The Cyclos server validates the payment, and redirects the user back into the specified return url;
  6. The web shops queries Cyclos about that ticket id, and validates the response, and completes the transaction.

It is very important that the web shop validates the ticket, because the client may cancel the payment or do anything, at all.

Normally, each web shop would be registered as a Service Client in Cyclos under Settings > Service Clients. It is a good practice to restrict this client to the member who owns the web shop, so that all payments performed are guaranteed to go to that member.

Available operations:

  • generate: The generate operation returns the generated ticket identifier (String), and takes as argument an object, named params, containing the following parameters:
    • toUsername or toSystem: If the payment is targeted to a specific user (normally on web shops), then toUsername should be specified, containing the member login name. Otherwise, when the payment should be to system (for example, on a organization shop), then toSystem should be set to true. Required.
    • amount: The payment amount. If not specified, then the client member will be prompted. Althrough not required, the web shop will normally set, to force the amount to be correct.
    • currency: Either the currency symbol or identifier. When not set, uses the default account's currency for the actual member.
    • description: The payment description. If not set, will be the payment type description.
    • clientAddress: The IP address of the web shop client. Required.
    • returnUrl: The HTTP(s) URL where the user will be redirected to after completing the payment. Required.
  • get: Loads a specific ticket, getting the ticket identifier as parameter (the same returned from the generate operation), named ticket, and returns a ticket object.

There is a code sample for performing a WebShop payment in a PHP: Web services/WebShop payment.


Advertisements

Allow searching for advertisements. The organization site might find useful to publish on the institutional web site a list of recent advertisements published on Cyclos, or allow any user to search for advertisements. The advertisements web service allows such operations. The available operations are:

load: Given a numeric identifier named id, returns the details of an advertisement.

fullTextSearch: Searches for advertisements using a full text search technique, which is best suited when the user supplies keywords. The results are ordered by relevance, listing the best results first.

  • Parameters: Takes a single object names params, with the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10.
    • keywords (string): A text to search within the advertisement title or description, as well as member details.
    • categoryId (number): The internal identifier for the advertisement category.
    • since (timePeriod): The maximum time period since the ad publication date.
    • tradeType (enumeration): The advertisement trade type. May be OFFER (for ads offering a product / service), SEARCH (for ads searching for a product / service) or BOTH.
    • adFields (array of fieldValues): The advertisement custom field values, keyed by the field internal name or id. When searching for an enumerated field, the value must be the possible value id.
    • memberFields (array of fieldValues): The publisher custom field values, keyed by the field internal name or id. When searching for an enumerated field, the value must be the possible value id.
    • memberGroupIds (array of number): The publisher's group, allowing multiple groups to be specified.
    • withImagesOnly (boolean): If set to true, only return ads with at least one image. Defaults to false
    • showAdFields (boolean): If set to true, return the advertisement custom field values. Defaults to false
    • showMemberFields (boolean): If set to true, return the publisher custom field values. Defaults to false
  • Result: A page of ads, containing the following attributes:
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of advertisements (not only those returned in the page).
    • ads (array of ad): Contains the details for each advertisement. For more details, refer to the model data details

A complete example in PHP of how to search advertisements is available: Web services/Advertisements search.

search: Searches for advertisements without the full text search technique, and is best suited when the user does not supply a search phrase. Examples would be the last published advertisements, or n random advertisements. The input is an object very similar to the one for fullTextSearch, but has an additional option, randomOrder, which when set to true wull return the advertisements randomly ordered.

A simple example in PHP, listing a few random advertisements is available: Web services/Random search.

  • loadCategory: Given a numeric identifier named id, returns a category.
  • listCategories: Takes no arguments, and returns an array of leaf categories (categories with no children).
  • listCategoryTree: Takes no arguments, and returns an array of detailed categories (along with their children, allowing the navigation as a tree).


Members

Allow searching for members, and retrieving data from a given member. The following operations are available:

load: Given a numeric identifier named id, returns a member.

fullTextSearch: Searches for members using a full text search technique, which is best suited when the user supplies keywords. The results are ordered by relevance, listing the best results first.

  • Parameters: Takes a single object named params with the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10.
    • keywords (string): Keywords to search.
    • groupIds (array of numbers): An array of group identifiers.
    • groupFilterIds (array of numbers): An array of group filter identifiers.
    • fields (array of fieldValues): The custom field values for the member, keyed by the field internal name or id. When searching for an enumerated field, the value must be the possible value id.
    • showCustomFields (boolean): Indicates if the custom fields will be retrieved together with each member. Defaults to false.
    • showImages (boolean): Indicates if the images information will be retrieved together with each member. Defaults to false.
  • Result: A page of members, containing the following attributes:
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of members (not only those returned in the page).
    • ads (array of member): Contains the details for each member. For more details, refer to the model data details


search: Searches for members, returning a page of members.

  • Parameters: Takes a single object named params, which have almost all attributes as the one for fullTextSearch (except for keywords), and have the following additional ones:
    • username (string): A text to search within the login name.
    • name (string): A text to search within the name.
    • randomOrder (boolean): When set to true, the result order will be scrambled.


Custom Fields

Since Cyclos allows registering arbitrary fields for members, advertisements and other entities, it also offers this web service to get data about those fields. The following operations are provided:

  • memberFieldsForMemberSearch: Takes no arguments, and returns an array of member custom fields that may be used to search for members.
  • memberFieldsForAdSearch: Takes no arguments, and returns an array of member custom fields that may be used to search for advertisements.
  • adFieldsForAdSearch: Takes no arguments, and returns an array of advertisement custom fields that may be used to search for advertisements.
  • possibleValuesForMemberField: Takes an argument named name that is a member custom field internal name, and returns a list of possible values.
  • possibleValuesForAdField: Takes an argument named name that is an advertisement custom field internal name, and returns a list of possible values.


Access

It is possible for an organization to check for pin and channel access data for members. Here are the available operations:

checkPin: Checks whether the given pin is correct for the given member.

  • Parameters:
    • member (string): The member username. Ignored when client is restricted to a member, assuming him. Otherwise, required.
    • pin (string): The pin to check.
  • Result: A boolean flag indicating whether the given pin is correct.


isChannelEnabledForMember: Checks whether the given member allows access to the given channel.

    • member (string): The member username. Ignored when client is restricted to a member, assuming him. Otherwise, required.
    • channel (string): The channel internal name. Optional, only used if the service client is not restricted to a channel.
  • Result: A boolean flag indicating whether the given channel is enabled for the member.


Account

This web service allows retrieving information for a member account. When the client is restricted to a member, will only be able to see account information for that member. The available operations are:

getMemberAccounts: Returns which accounts a member have.

  • Parameters: A single parameter named member (string which is the member username. This parameter is ignored when the client is restricted to a member, assuming that member.
  • Result: A list of memberAccount. For more details, check out the model data details.


getMemberAccountStatus: Returns the status of a member account, such as the balance and reserved amount.

  • Parameters:
    • member (string): The member username. This parameter is ignored when the client is restricted to a member, assuming that member.
    • accountTypeId (integer): The account type internal identifier. When null or zero is passed, the default account type is assumed.
  • Result: An accountStatus. For more details, check out the model data details.


searchAccountHistory: Returns the account history (credits and debits) for a given member account.

  • Parameters: A single object containing the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10.
    • member (String): The member username. This parameter is ignored when the client is restricted to a member, assuming that member.
    • accountTypeId (integer): The account type internal identifier. When null or zero is passed, the default account type is assumed.
    • relatedMember (string): The login name for the payment related member. Optional.
    • beginDate (date): The begin date for payments. Optional.
    • endDate (date): The end date for payments. Optional.
    • fields (array of fieldValue): An array containing payment custom fields. Optional.
  • Result: A page of transfers, containing the following attributes:
    • currentPage (integer): The current page in the search.
    • totalCount (integer): The total number of transfers (not only those returned in the page).
    • transfers (array of transfer): Contains the details for each transfer. For more details, refer to the model data details


loadTransfer: Returns a single transfer, given it's identifier, or null when not found.

  • Parameters:
    • member (string) The member username. This parameter is ignored when the client is restricted to a member, assuming that member.
    • transferId (number): The transfer identifier. Required.
  • Result: A transfer object. For more details, refer to the model data details


searchTransferTypes: Gets the available transfer types (or payment types) for the given parameters.

  • Parameters: A single object containing the following attributes:
    • currentPage (number): The current query page, starting at zero. Defaults to 0.
    • pageSize (number): The number of records per page. Defaults to 10.
    • currencyId (number): The internal identifier for a currency. Optional.
    • fromMember (string): The username of the member performing the payment. When restricted to a member, either fromMember or toMember must be specified. Otherwise, required.
    • toMember (string): The username of the member receiving the payment. When restricted to a member, either fromMember or toMember must be specified. Otherwise, required.
    • toSystem (boolean): When set to true, instead of returning payment types to a member, return payment types to a system account.


Model data details

Many of the web services operations works with model data. The following elements are available (with their properties):

transfer

  • transferType (transferType): The payment type
  • date (date): The creation / submission date
  • formattedDate (string): The creation / submission date, formatted according to the Cyclos settings
  • processDate (date): The processing / accepting date
  • formattedProcessDate (string): The processing / accepting date, formatted according to the Cyclos settings
  • amount (decimal): The payment amount
  • formattedAmount (string): The payment amount, formatted according to the Cyclos settings
  • member (member): The member which received / performed the payment, when the payment was to / from a member
  • systemAccountName: The system account name, when the payment was to / from system
  • transactionNumber (string): The generated transaction number

accountStatus

  • balance (decimal): The raw account balance
  • formattedBalance (string): The raw account balance, formatted according to the Cyclos settings
  • availableBalance (decimal): The available balance
  • formattedAvailableBalance (string): The available balance, formatted according to the Cyclos settings
  • reservedAmount (decimal): The amount which is currently reserved
  • formattedReservedAmount (string): The amount which is currently reserved, formatted according to the Cyclos settings
  • creditLimit (decimal): The maximum negative balance this account may reach, represented as a positive number
  • formattedCreditLimit (string): The maximum negative balance this account may reach, formatted according to the Cyclos settings
  • upperCreditLimit (decimal): The maximum positive balance this account may reach, or null when unlimited
  • formattedUpperCreditLimit (string): The maximum positive balance this account may reach, formatted according to the Cyclos settings

transferType

  • name (string): The transfer type name
  • from (accountType): The origin account type
  • to (accountType): The destination account type

currency

  • symbol (string): The currency symbol
  • name (string): The currency name
  • pattern (string): A string containing #amount#, which should be replaced by the actual amount. For example: "$U #amount" would be replaced by "$U 0.00".

ticket

  • ticket (string): The ticket identifier
  • fromMember (member): The member that paid the transaction
  • toMember (member): The member that received the transaction (when was to a member)
  • toSystem (boolean): Indicates it the payment was to system
  • amount (number): The payment amount
  • description (string): The payment description
  • ok (boolean): Indicates if the payment was successfully completed
  • cancelled (boolean): Indicates if the payment was cancelled by the member
  • pending (boolean): Indicates if the payment wasn't completed yet
  • expired (boolean): Indicates if the payment wasn't completed within an hour
  • awaitingAuthorization (boolean): Indicates if the payment is awaiting authorization in Cyclos
  • formattedAmount (string): The payment amount, formatted according to the Cyclos settings
  • creationDate (date): The date the ticket was created
  • formattedCreationDate (string): The date the ticket was created, formatted according to the Cyclos settings
  • clientAddress (string): The client member IP address
  • memberAddress (string): The web shop IP address
  • returnUrl (string): The informed return url

ad

  • id (number): The internal identifier
  • category (adCategory): The advertisement category
  • searching (boolean): Indicates if the member is demanding a product / service (when true) or offering (when false)
  • title (string): The title
  • description (string): The description
  • html (boolean): Indicates if the description is html (true) or plain text (false)
  • owner (member): The member that published the advertisement
  • price (number): The price
  • formattedPrice (string): The price, formatted according to Cyclos settings
  • permanent (boolean): Indicates if the advertisement is permanent (like yellow pages) or not (a specific offering)
  • publicationStart (date): The date the advertisement was published
  • formattedPublicationStart (string): The date the advertisement was published, formatted according to Cyclos settings
  • publicationEnd (date): The date the advertisement expires
  • formattedPublicationEnd (string): The date the advertisement expires, formatted according to Cyclos settings
  • fields (array of fieldValues): The advertisement custom field values, keyed by the field internalName
  • images (array of image): An array of advertisement images

adCategory

  • id (number): The internal identifier
  • name (string): The full category name, in the form "Parent: Child"

detailedAdCategory

  • id (number): The internal identifier
  • name (string): The category name
  • fullName (string): The full category name, in the form "Parent: Child"
  • level (number): The level of nesting this category has, starting with 1
  • countOffer (number): The number of active advertisements being offered on this category
  • countSearch (number): The number of active advertisements being searched on this category
  • children (array of detailedAdCategory): The categories that are children of this category

member

  • id (number): The internal identifier
  • name (string): The member name
  • username (string): The login name
  • email (string): The member e-mail
  • fields (fieldValues of string x string): The member custom field values, keyed by the field internalName
  • images (array of image): An array of member images

field

  • id (number): The internal identifier
  • internalName (string): The internal name
  • displayName (string): The display name
  • type (enumeration): The field data type. May be: STRING, ENUMERATED, INTEGER, FLOAT, DATE or BOOLEAN
  • enumerated (boolean): Indicates if the field is enumerated, that means, accepts only specific values. Will be true when type is ENUMERATED

possibleValue

  • id (number): The internal identifier
  • value (string): The display value

image

  • id (number): The internal identifier
  • thumbnailUrl (string): The url for the image thumbnail
  • fullUrl (string): The url for the full image
  • caption (string): A descriptive caption

page

  • currentPage (number): The current page on the search
  • totalCount (number): The total number of results
  • [ads / members]: If is an ad page, the ads will contain an array of ads. If a member page, an array of members

fieldValue

  • field (string): The custom field internal name or identifier
  • value (any): The custom field value

timePeriod

  • number (number): The period numeric value
  • field (enumeration): The period field. May be: DAYS, WEEKS or MONTHS