ERP 2.50:Developers Guide/Concepts/SOAP Web Services

ERP 2.50:Developers Guide

ERP 2.50:Developers Guide/Fundamentals and Concepts ERP 2.50:Developers Guide/Concepts/WebServices ERP 2.50:Developers Guide/Concepts/XML REST Web Services ERP 2.50:Developers Guide/Concepts/SOAP Web Services ERP 2.50:Developers Guide/Concepts/JSON REST Web Services

Index

Contents 1 Introduction 2 Web Services objects 2.1 externalSales 2.1.1 Product definition 2.1.1.1 Product type 2.1.1.2 Category type 2.1.1.3 Tax type 2.1.2 Order definition 2.1.2.1 Order type 2.1.2.2 Order identifier type 2.1.2.3 Orderline type 2.1.2.4 Payment type 2.1.3 Business partner 2.1.3.1 Business partner type 2.2 services 2.2.1 Business Partner 2.2.2 Customer 2.2.3 Contact 2.2.4 Location 3 Web Services methods 3.1 ExternalSales 3.1.1 getProductsCatalog 3.1.2 uploadOrders 3.1.3 getOrders 3.2 WebService 3.2.1 getCustomers 3.2.2 getCustomer 3.2.3 getCustomer 3.2.4 updateCustomer 3.2.5 getCustomerAddresses 3.2.6 getCustomerLocation 3.2.7 updateAddress 3.2.8 getCustomerContact 3.2.9 updateContact

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
email	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: Validate that the client associated with the new Order exists (in case of the Terminal POS the client will be dummy). If the client doesn't exist it will be inserted. Save the Order. 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: Entity. WebService's param. Organization. WebService's param. Doc. Num. Openbravo generated. Business Partner. Order's client. PriceList. Assigned by ERP and will be the Entity/Organization's default priceList. Currency. Assigned by ERP and will be the Entity/Organization's default currency Warehouse. Assigned by ERP and will be the Entity/Organization's default warehouse Order Date. Order.dateNew. Payment type. Order.paymentType. For every OrderLine: Product. OrderLine.productId. Unit. OrderLine.units. Tax. OrderLine.tax. Price. OrderLine.price. UOM. Assigned by ERP and will be the Product's default unit of measure 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

---

ERP 2.50:Developers Guide/Concepts/XML REST Web Services | ERP 2.50:Developers Guide/Concepts/JSON REST Web Services