ERP 2.50:Developers Guide/Concepts/SOAP Web Services
Contents |
Introduction
Openbravo ERP's webservices provide the interface that allows Openbravo ERP's integration with other systems (for example with a Virtual Shop and a POS Terminal) and hereby share the management of products and orders obtaining this way a global integrated and more complete solution.
Different classes of web service objects have been defined as part of this interface (Products, Orders and Business Partner) as well as the web interface methods that will be able to be invoked.
For the implementation of the security a user's validation is realized in every request that the ERP receives from the webService, for what in every method we have to pass a user with the necessary permissions and his ciphered password (such it is stored in database).
This user has to have permission to be able to execute the task of the ExternalPOS (org.openbravo.erpCommon.ws.externalSales.ExternalSales) inside the ERP.
For Openbravo's integration with other systems we have developed an API named "ExternalSales" that takes charge providing the mechanisms necessary for the integration of Orders, Products and Business Partner.
The technology used on that the implementation of the API is based is AXIS that is WebServices's implementation developed by Apache of easy integration in Tomcat. These are the current webservice object classes:
Web Services objects
These are the current webservice object classes.
externalSales
- Package: org.openbravo.erpCommon.ws.externalSales
Product definition
Product definition is related with three object classes.
Product type
Field | Type | Description |
---|---|---|
id | int | ERP Product's identifier. |
name | Java.lang.String | Product 's name. |
number | Java.lang.String | Product number. |
description | Java.lang.String | Product's description. |
listPrice | double | Product's price without taxes and discounts. |
purchasePrice | double | Product price for sale. |
tax | Tax | Tax assigned to this product. |
imageUrl | Java.lang.String | URL to download product's image. |
ean | Java.lang.String | Product's barcode. |
category | Category | Product's category |
Category type
Field | Type | Description |
---|---|---|
id | int | ERP category's identifier. |
name | Java.lang.String | Category's name. |
description | Java.lang.String | Category's description. |
Tax type
Field | Type | Description |
---|---|---|
id | int | Tax's identifier. |
name | Java.lang.String | Tax's name |
percentage | double | Values between -100 and 100. |
Order definition
Order type
Field | Type | Description |
---|---|---|
orderId | OrderIdentifier | Order's identifier for Virtual Shop and POS Terminal. |
lines | OrderLine [] | OrderLine's array. |
state | int | Order's state identifier. |
bpartner | BPartner | Client that generates this order. |
payments | Payment [] | Payments array |
Order identifier type
Field | Type | Description |
---|---|---|
document_no | String | Order identifier for Virtual Shop and POS Terminal. |
dateNew | Java.util.Date | Insert date. |
Orderline type
Field | Type | Description |
---|---|---|
orderLineId | int | OrderLine identifier for ERP. |
productId | int | Product identifier. |
units | double | Number of product for this line. |
price | double | Price in PriceList for this product. |
taxId | int | Tax applied (Tax applied identifier). |
Payment type
Field | Type | Description |
---|---|---|
amount | double | Amount satisfied with the payment. |
paymentType | String | Way of payment. |
Business partner
We will define the Business partner in BPartner type.
Business partner type
Field | Type | Description |
---|---|---|
id | String | Business Partner identifier for Virtual Shop. |
name | String | Business Partner name. |
country | String | Business Partner Country. |
region | String | Business Partner region. |
city | String | Business Partner city. |
postal | String | Business Partner postal code. |
address1 | String | Business Partner address' first line. |
address2 | String | Business Partner address' second line. |
services
- Package: org.openbravo.erpCommon.ws.services
Business Partner
- Class Name: BusinessPartner
Field | Type | Description |
---|---|---|
id | java.lang.String | Business Partner identificator |
clientId | java.lang.String | The Client Id where the Bussines Partner belong |
name | java.lang.String | Name of the Business Partner |
searchKey | java.lang.String | Search Key – a unique string that identify the Business Partner |
description | java.lang.String | Description of the Business Partner |
customer | java.lang.Boolean | A flag that specifies if the Business Partner is a Customer |
vendor | java.lang.Boolean | A flag that specifies if the Business Partner is a Vendor |
locations | Location[] | A list of the available Locations of the Business Partner |
contacts | Contact[] | A list of the available Contact of the Business Partner |
Customer
- Class Name: Customer
An instance of BusinessPartner
with the customer
member set to true
.
Contact
- Class Name: Contact
Field | Type | Description |
---|---|---|
id | java.lang.String | Contact identifier |
clientId | java.lang.String | Client Id where the Contact belongs to |
businessPartnerId | java.lang.String | Business Partner Id where the Contact belongs to |
firstname | java.lang.String | Contact's First Name |
lastname | java.lang.String | Contact's Last Name |
java.lang.String | Contact's Email | |
phone | java.lang.String | Contact's Phone |
phone2 | java.lang.String | Contact's Second phone |
fax | java.lang.String | Contact's Fax |
Location
- Class Name: Location
Field | Type | Description |
id | int | Location identifier |
clientId | java.lang.String | Client Id where the Location belongs to |
businessPartnerId | java.lang.String | Business Partner Id where the Location belongs to |
address1 | java.lang.String | Location's Address 1 |
address2 | java.lang.String | Location's Address 2 |
city | java.lang.String | Location's City |
postal | java.lang.String | Location's Postal Code |
region | java.lang.String | Location's Region |
country | java.lang.String | Location's Country |
Web Services methods
These are the current webservice methods interfaces:
ExternalSales
getProductsCatalog
Function name | getProductsCatalog | |
---|---|---|
Parameters | entityId: java.lang.String | Entity identifier for the Virtual Shop or the POS Terminal on the ERP. |
OrganizationId: java.lang.String | Organization identifier for the Virtual Shop or the POS Terminal on the ERP. | |
salesChannel:int | Virtual Shop = 1 POS Terminal = 2 | |
username:String | ERP user. | |
password:String | ERP user's ciphered password | |
Return | Product [] | Products array. |
PreConditions | -- | |
PostConditions | The Virtual Shop or the Terminal POS can update his catalog of products with the obtained one of the ERP. | |
Functionality | It has to return the list of products according to the channel of sale and the consulted entity.
Every product includes, specific information, the information of the category to which it belongs and the tax that partner has in the ERP. For more details on the Product Type see the paragraph "Product definition". |
uploadOrders
Function name | uploadOrders | |
---|---|---|
Parameters | entityId:String | Entity identifier for the Virtual Shop or the POS Terminal on the ERP. |
OrganizationId: String | Organization identifier for the Virtual Shop or the POS Terminal on the ERP. | |
salesChannel:int | Virtual Shop = 1 POS Terminal = 2 | |
newOrders:Order[] | an array of the Orders to be uploaded | |
username:String | ERP user. | |
password:String | ERP user's ciphered password | |
Return | Void | |
PreConditions | The product's catalog has been synchronized previously. | |
PostConditions | ERP store new order's information. | |
Functionality | Insert into ERP new order's generated in Virtual Shop or POS Terminal.
It has to complete the following process:
The order will be saved in the ERP with the specified values by the WebService with the object Order, more certain values that will be informed About automatic form. Order values will be:
For every OrderLine:
Others: There exist other values of the order that is preferable adapt to the suggestions proposed by Openbravo ERP. |
getOrders
Function name | getOrders | |
---|---|---|
Parameters | entityId: String | Entity identifier for the Virtual Shop or the POS Terminal on the ERP. |
OrganizationId: String | Organization identifier for the Virtual Shop or the POS Terminal on the ERP. | |
username:String | ERP user. | |
password:String | ERP user's ciphered password | |
orderIds:OrderIdentifier[] | List of orders requested. | |
Return | Order [] | |
Functionality | It has to return an Order type array. With the information returned by this service, the state of the orders will be updated in the Terminal POS and the Virtual Shop. |
WebService
getCustomers
Function name | getCustomers | |
---|---|---|
Parameters | clientId: int | Client identifier from which the Customers will be retrieved |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Customer [] | Customer array. |
PreConditions | -- | |
PostConditions | -- | |
Functionality | Returns an array of Customer from the Client specified
|
getCustomer
Function name | getCustomer | |
---|---|---|
Parameters | clientId: java.lang.String | Client identifier from which the Customers will be retrieved |
customerId: java.lang.String | Customer identifier that will be retrieved | |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Customer | Customer specified by the identifier |
PreConditions | -- | |
PostConditions | -- | |
Functionality | Returns the Customer specified
|
getCustomer
Function name | getCustomer | |
---|---|---|
Parameters | clientId: int | Client identifier from which the Customers will be retrieved |
name: java.lang.String | Customer's name [optional] | |
searchKey: java.lang.String | Customer's searchKey [optional] | |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Customer | Customer specified by the name or searchKey |
PreConditions | -- | |
PostConditions | -- | |
Functionality | Returns the Customer specified by the name or searchKey . You need to choose the parameter to search for, name or searchKey
|
updateCustomer
Function name | updateCustomer | |
---|---|---|
Parameters | customer: BusinessPartner | A Customer object to update |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Boolean | A success or failure of the update execution |
PreConditions | -- | |
PostConditions | -- | |
Functionality | Returns a Boolean on success or failure of the update process
|
getCustomerAddresses
Function name | getCustomerAddresses | |
---|---|---|
Parameters | clientId: int | The Client identifier |
customerId: int | The Customer identifier | |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | int [] | An Array of available location identifiers |
PreConditions | -- | |
PostConditions | -- | |
Functionality | Returns an array int of the available location identifiers for the Customer |
getCustomerLocation
Function name | getCustomerLocation | |
---|---|---|
Parameters | clientId: int | The Client identifier |
customerId: int | The Customer identifier | |
locationId: int | The Customer location identifier | |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Location
| A Location object for the specified identifier |
PreConditions | -- | |
PostConditions | -- | |
Functionality | A Location object for the specified identifier |
updateAddress
Function name | updateAddress | |
---|---|---|
Parameters | addr: Location | A Location object to update |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Boolean
| A success or failure update execution |
PreConditions | -- | |
PostConditions | -- | |
Functionality | A Boolean success or failure update execution
|
getCustomerContact
Function name | getCustomerContact | |
---|---|---|
Parameters | clientId: String | The Client identifier |
customerId: String | The Customer identifier | |
contactId: String | The Customer contact identifier | |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Contact
| A Contact object for the specified identifier |
PreConditions | -- | |
PostConditions | -- | |
Functionality | A Contact object for the specified identifier |
updateContact
Function name | updateContact | |
---|---|---|
Parameters | contact: Contact | A Contact object to update |
username: java.lang.String | ERP user. | |
password: java.lang.String | ERP user's ciphered password | |
Return | Boolean
| A success or failure update execution |
PreConditions | -- | |
-- | ||
Functionality | A Boolean success or failure update execution
|
Languages: |
ERP 2.50:Developers Guide/Concepts/XML REST Web Services | ERP 2.50:Developers Guide/Concepts/JSON REST Web Services