Legacy Pubeasy Supplier SOAP API Programmers Reference

Contents

1. Overview

This document explains in detail the semantics of the function calls you can make using the Legacy Pubeasy Supplier Soap API web service. In this document you will learn:

• How Pubeasy's Supplier SOAP API syntax works
• How to interpret the result information sent back to you from the Legacy Pubeasy Supplier SOAP API web service.
• Best practices for how to implement fully functioning Pubeasy web service APIs for your Legacy Pubeasy Supplier web site.

2. Legacy Pubeasy API Summary

There are a total of seven Legacy Pubeasy Supplier APIs that can be implemented for your Legacy Pubeasy Supplier site. Not all of them are required, but if they are implemented, the user experience at your site will be that much better. Each API can be subdivided into two individual groups:

• Upload Services: For example, uploading product data to the Pubeasy application.

• Processing Services: For example, retrieving and processing orders entered or being able to answer order status enquiries requested by booksellers.

A summary of the seven API's that can be implemented for the operational environment and the required push/pull operation method is as follows:

Item	Description	Operational Method	Frequency
1	Upload Publisher/Imprint Data	Push	At Least Daily
2	Upload Series Data	Push	At Least Daily
3	Upload Product Data	Push	At Least Daily
4	Process Order Lines	Pull And Push	Interactive - Constant
5	Process General Order Status Requests/Results	Pull And Push	Interactive - Constant
6	Process Back Order Status Requests/Results	Pull And Push	Interactive - Constant
7	Process Personal Product Information	Pull And Push	Interactive - Constant

Push - Data will be uploaded into the database Pull - Data will be extracted from the database

For a more thorough description of the Legacy Pubeasy API's, please read the Legacy Pubeasy API Overview document, which can be requested here. Please provide your name, the company you work for, and a contact phone number.

3. Upload Publisher/Imprint Data API

3.1 Summary

When a bookseller clicks on the Publisher/Imprint link on the Affiliates Pubeasy main login page, they are taken to a page that displays a list of publishers/imprints that are available from the site. Some of the publishers displayed may be underlined to indicate that a hyperlink exists to that publishers marketing web site, from Pubeasy. This API is used to populate that Publisher/Imprint Data, one publisher line per request.

3.2 load_publisher SOAP Request

The load_publisher SOAP request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
data	string	The XML string representing a single publisher line of data to load into the database (See below for the xml data string format)

'Data' string format - <data>

The data parameter is an xml string representation of a single line to be inserted/updated in the publishers table. Therefore, each column name in the table below represents a single field in the database table for publishers/imprints.

Column Name	Description	Definition
code	Publisher's ID	VARCHAR2 (4)
description	Publisher's Name	VARCHAR2 (160)
url	Universal Resource Locator	VARCHAR2 (60)
marketing_site_url	The URL of the publishers marketing site.	VARCHAR2 (200)
dont_display_pub	A flag indicating if the publisher should be displayed on the Publisher/Imprint page.	VARCHAR2 (1)
dont_drop_down	Indicates to Pubeasy that the publisher/imprint should not be displayed in the drop down list on any of the search pages (Valid values are 'Y' or 'N').	VARCHAR2 (1)
publisher_logo	This is the name of the image file to be shown.	VARCHAR2 (50)
show_stock	This flag indicates if the Back Office stock values are to be shown for this publisher on the Personal Product Info API. It must contain either 'Y' or 'N'	VARCHAR2 (1)

The following is an example of a valid data parameter string.

<data>
  <code>BOWK</code>
  <description>R.R. Bowker LLC</description>
  <url></url>
  <marketing_site_url>http://www.bowker.com</marketing_site_url>
  <dont_display_pub>N</dont_display_pub>
  <dont_drop_down>N</dont_drop_down>
  <publisher_logo></publisher_logo>
  <show_stock>N</show_stock>
</data>

3.3 load_publisher SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The Publisher/Imprint line failed to be added to your Supplier Site. This usually means that invalid data was passed in and was rejected, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
1	SUCCESS	The Publisher/Imprint line was successfully added or updated for your Supplier Site.

3.4 Best Practices

This API should be run at least daily to ensure that Pubeasy contains the most up-to-date information available. Sequencing: Upload Publisher/Imprint data before products data

4. Upload Series Data API

4.1 Summary

It is possible within Pubeasy to search for products using a series code that relates to a group of products. This selection criteria is optional within Pubeasy and if the operational environments do not group products this way then this particular API will not be required. However, this API can be used to populate the Series Data if the operational environment does group products this way, one series line per request.

4.2 load_series SOAP Request

The load_series SOAP request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
data	string	The XML string representing a single series line of data to load into the database (See below for the xml data string format)

'Data' string format - <data>

The data parameter is an xml string representation of a single line to be inserted/updated in the series table. Therefore, each column name in the table below represents a single field in the database table for series.

Column Name	Description	Definition
series	Series ID	VARCHAR2 (10)
description	Series Description	VARCHAR2 (40)
dont_drop_down	Indicates to Pubeasy that the Series should not be displayed in the drop down list on any of the search pages (valid values are 'Y' or 'N').	VARCHAR2 (1)

The web service call will fail if a field exceeds the length of the corresponding database column. For example the load_series request will be successful if the Series Description value has more than 40 characters. The following is an example of a valid data parameter string.

<data>
  <series>0262-995X</series>
  <description>Bowker Books In Print</description>
  <dont_drop_down>N</dont_drop_down>
</data>

4.3 load_series SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The Series line failed to be added to your Supplier Site. This usually means that invalid data was passed in and was rejected, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
1	SUCCESS	The Series line was successfully added or updated for your Supplier Site.

4.4 Best Practices

This API should be run at least daily to ensure that Pubeasy contains the most up-to-date information available. Sequencing: Upload Series data before products data

5. Upload Products Data API

5.1 Summary

This is the main process that extracts relevant product data from the operational environment into a fixed format that is then loaded into Pubeasy. Not all of the products that exist within the operational environment may be required to be loaded, this will be Affiliate specific. The API will load one product line per request.

5.2 load_product SOAP Request

The load_product SOAP request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
data	string	The XML string representing a single series line of data to load into the database (See below for the xml data string format)

'Data' string format - <data>

The data parameter is an xml string representation of a single line to be inserted/updated in the products table. Therefore, each column name in the table below represents a single field in the database table for products.

Column Name	Description	Notes	Definition
isbn	Product ID	Mandatory. International Standard Book Number	VARCHAR2 (13)
pub_code	Publisher Code	Mandatory. Refers to the CODE column in the Publishers table	VARCHAR2 (4)
binding	Product Binding Details	Mandatory. This column will be withdrawn in a future release. The column MEDIUM is replacing it. If the MEDIUM column is used then this column is ignored.	VARCHAR2 (24)
price	Published Price Of Product	Mandatory	NUMBER (7,2)
available	Answer code	Mandatory. Refer to APPENDIX D	VARCHAR2 (2)
series_series	Series Code	Refers to the SERIES column in the Series table.	VARCHAR2 (10)
title	Product Description		VARCHAR2 (70)
author	Product Author		VARCHAR2 (200)
availability_date	Answer Code Date	Date Mask Of 'Mmm-YYYY'	VARCHAR2 (8)
next_isbn	Alternative Product ID	If the current products is no longer available this would be populated with an alternative ISBN that is now available.	VARCHAR2 (13)
other_edition	Alternative Binding Of Product ID		VARCHAR2 (10)
publication_date	Publication Date Of Product	All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101.	DATE
sub_title	Extra Product Description		VARCHAR2 (300)
invalid		Defaults To 'N'. Must be 'Y' or 'N'. If this is 'Y' then title will not be displayed in Pubeasy.	VARCHAR2 (1)
pack_size	Binders Pack Size		NUMBER (4)
order_allowed	Flag To Allow Order Be Placed Against Product	Must Be 'Y' Or 'N' for customers with an OME flag set to an 'N'.	VARCHAR2 (1)
export_binding	Export Product Binding Details	Mandatory. This column will be withdrawn in a future release. The column EXPORT_MEDIUM is replacing it. If the EXPORT_MEDIUM column is used then this column is ignored.	VARCHAR2 (24)
export_price	Export Published Price Of Product		NUMBER (7,2)
export_available	Export Product Available For Purchase	Refer to APPENDIX D.	VARCHAR2 (2)
export_publication_date	Export Publication Date Of Product	All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101.	DATE
long_title	Holds the long title for the product.		VARCHAR2 (600)
link_to_marketing	A flag indicating if the product provides a link to a marketing site.	Must Be 'Y' Or 'N'. If this is 'Y' then a hyperlink will be displayed for this ISBN to the URL specified in the MARKETING_SITE_URL column of the PUBLISHERS table for this titles PUB_CODE.	VARCHAR2 (1)
actual_marketing_site_url	A static link to a marketing site for the product		VARCHAR2 (200)
export_availability	Don't use this		VARCHAR2(24)
export_availability_date	Answer Code Date	Date Mask Of 'Mmm-YYYY'	VARCHAR2 (8)
price_vat	This is for future use. It is not currently used and can be ignored.		NUMBER (7,2)
pages	This is the total number of pages in the ISBN. This is for future use. It is not currently used and can be ignored.		NUMBER (4)
editor	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (200)
general_editor	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (100)
translator	This is for future use. It is not currently used and can be ignored.		VARCHAR2 100)
illustrator	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (100)
reprint	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (1)
medium	This column replaces the BINDING column. It is the medium of the ISBN for customers that have an OME flag set to a value of 'N'. It must be one of the values in APPENDIX J.		VARCHAR2 (5)
prod_lang_code	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (2)
category	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (9)
sub_category	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (9)
key_stage	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (6)
age_group	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (6)
pub_town	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (30)
title_alpha	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (8)
desc1	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (1000)
desc2	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (1000)
prod_size	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (10)
export_medium	This column replaces the EXPORT_BINDING column. It is the export medium of the ISBN for customers that have an OME flag set to a value of 'Y'. It must be one of the values in APPENDIX J.		VARCHAR2 (5)
supply_site	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (1)
order_allowed_ome	This flag indicates if OME flagged customer are permitted to order this ISBN. It must contain either 'Y' or 'N'.		VARCHAR2 (1)
stocked	Default is 'Y'.	Only replicate info to Central if product is stocked	VARCHAR2(1)
availability	Don't use it. Ignore this column; it may be removed in a future release.		VARCHAR2(24)
price_type	Optional. Price Type. See APPENDIX L for valid Price Types		VARCHAR2(1)
quantity_available	Quantity of Product that is available		NUMBER(8,0)
edition	Edition number, numeric only		NUMBER(4)

The following is an example of a valid data parameter string.

<data>
  <pub_code>BOWK</pub_code>
  <available>OR</available>
  <medium>BB</medium>
  <export_available></export_available>
  <reprint></reprint>
  <illustrator></illustrator>
  <invalid>N</invalid>
  <sub_category></sub_category>
  <title_alpha></title_alpha>
  <next_isbn></next_isbn>
  <translator></translator>
  <isbn>0683082574</isbn>
  <other_edition></other_edition>
  <stocked></stocked>
  <prod_lang_code></prod_lang_code>
  <desc1></desc1>
  <link_to_marketing></link_to_marketing>
  <long_title></long_title>
  <desc2></desc2>
  <author>TILLEY</author>
  <price>59.95</price>
  <export_price></export_price>
  <price_type>L</price_type>
  <series_series>0262-995X</series_series>
  <publication_date>19970201</publication_date>
  <pack_size>1</pack_size>
  <export_availability_date></export_availability_date>
  <age_group></age_group>
  <binding></binding>
  <key_stage></key_stage>
  <export_binding></export_binding>
  <price_vat></price_vat>
  <category></category>
  <supply_site></supply_site>
  <actual_marketing_site_url></actual_marketing_site_url>
  <title>Books In Print</title>
  <export_medium></export_medium>
  <order_allowed>Y</order_allowed>
  <order_allowed_ome>Y</order_allowed_ome>
  <general_editor></general_editor>
  <editor></editor>
  <sub_title></sub_title>
  <edition>1</edition>
  <pub_town></pub_town>
  <prod_size></prod_size>
  <pages></pages>
  <export_publication_date></export_publication_date>
  <quantity_available>1</quantity_available>
</data>

5.3 load_product SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The product line failed to be added to your Supplier Site. This usually means that invalid data was passed in and was rejected, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
1	SUCCESS	The product line was successfully added or updated for your Supplier Site.

5.4 Best Practices

This API should be run at least daily to ensure that Pubeasy contains the most up-to-date information available. Sequencing: Upload product data after publisher/imprint and series data

6. Process Order Lines API

6.1 Summary

The Pubeasy application provides various methods for trade customers to place confirmed orders. Once the bookseller has completed an order, this information is stored in an order table, which is immediately available for the operational environment to process. The order information could be passed to the operational environment on a regular basis for processing, however it is more desirable that an interactive API is developed to continually monitor the Pubeasy order table to check and process orders as soon as they are confirmed. The strategy that should be implemented to accomplish this with web service calls is CHECK->GET->LOAD.

6.2 check_for_orders SOAP Request

The check_for_orders SOAP request call is used to return the count of unprocessed orders for an affiliate. This request has been speed optimized such that it can be called frequently, or continuously as in a loop. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
in_progress	string	OPTIONAL: A string that indicates to search for order_lines marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise null

6.3 check_for_orders SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a check_for_orders request can either mean that there are currently no outstanding or in progress orders to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
N	SUCCESS	Where N is any non-negative number. In this case, N represents the total number of outstanding or in progress orders that need to be processed by the operational environment. The next step will be to get those orders for processing.

6.4 get_orders SOAP Request

The get_orders SOAP request call is used to return the actual order_lines for an affiliate, in xml format. With this request, it is possible to limit the number of records that are returned to a number that you specify, otherwise the default will return all unprocessed orders. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
num_recs	unsigned integer	OPTIONAL: An integer that sets the upper limit of records to return. If in_progress or single_order is used, a value for num_recs must be used as well (0 - returns all records)
in_progress	string	OPTIONAL: A string that indicates to search for order_lines marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise 'C' or null)
single_order	unsigned integer	OPTIONAL: An integer that indicates to pull all order_lines for a single order. Set value to 1 to pull all order_lines for a single order, or 0 or null for default order_line processing. When using single_order, the values for num_recs and in_progress must be set (recommended use would be num_recs = 0 and in_progress = 'C')

6.5 get_orders SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a get_orders request can either mean that there are currently no outstanding or in progress orders to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
<order_lines> ... </order_lines>	SUCCESS	See the Order_Lines XML string format below for a description of the xml string returned when there are unprocessed orders

'Order_Lines' XML string format - <order_lines>

The data returned is an xml string representation of an actual order line in the order_lines table. Each order line will be wrapped with <order_lines> ... </order_lines> tags. In the case of multiple orders, there will be multiple order line items returned. The table below lists each column name that will be returned in each order_lines composite:

Column Name	Description	Notes	Definition
cust_account	Customer ID	Mandatory	VARCHAR2 (20)
prod_isbn	Product ID	Mandatory. International Standard Book Number	VARCHAR2 (13)
order_line_number	Unique ID Number	Mandatory. Populated by Pubeasy.	NUMBER (8)
ordstat_status	Status of the Order Line within Pubeasy. Populated by Pubeasy and then updated by the operational system.	Mandatory. Refer to APPENDIX B	VARCHAR2 (1)
quantity	Quantity Of Product Ordered	Mandatory	NUMBER (6)
record_dues	The customer allows back orders to be recorded	Mandatory. (Must Be 'Y' Or 'N').	VARCHAR2 (1)
part_supply	The customer allows orders to be part supplied	Mandatory. (Must Be 'Y' Or 'N').	VARCHAR2 (1)
order_date	Date Order Was Confirmed	Mandatory	DATE
e_mail_required	Specifies if an email acknowledgement of the order is required. This is always set to 'Y' if the user or customer posses an email address.	Mandatory. Defaults To 'N' (Must be 'Y' or 'N')	VARCHAR2 (1)
vissta_status	Supply status of the Order Line. Populated by Pubeasy and updated by the operational system once the order line has been processed	Defaults To 'A', Refer to APPENDIX C. The description of this code is displayed in the status column of the 'Check Order Status - Recent Orders' page and sent in the order confirmation email.	VARCHAR2 (1)
order_reference	Originator's Transaction Reference (PO Number)	If a user specifies a Line Reference but no Order Reference then this column will be populated with Not Entered	VARCHAR2 (14)
line_reference	Originator's Transaction Line Reference (Line PO Number)	If the user specifies an Order reference without a line reference then the line reference will be equal to the order reference.	VARCHAR2 (14)
PROMOTIONAL_CODE	Promotional Code	The value will be passed no matter if the affiliate accepts promotional code or not	VARCHAR2 (50)
special_instructions	Special Instruction Text	If Populated, Order Will Be Delayed.	VARCHAR2 (1600)
e_mail	Electronic Mail Address	If E_MAIL_REQUIRED is 'Y and this field is populated with an E-Mail address, Pubeasy will send the user an email confirming the order line once the operational system has processed the order line.	VARCHAR2 (80)
user_id	User Id	Mandatory	VARCHAR2 (4)
answer_text	Product Answer Description. Populated by the operational system once the order line has been processed.	This must be one of the standard EDI Answer Descriptions as used in APPENDIX D. This column will be withdrawn in a future release. The column has been superseded with the columns ANSWER_TEXT_CODE and ANSWER_TEXT_DATE.	VARCHAR2 (60)
customer_id	Customer Id	Mandatory. The operational environment may ignore this as it is used to maintain the referential integrity with the users table.	NUMBER (8)
price	This column contains the original price taken from the PRODUCTS table.		NUMBER (7,2)
order_from_cust_id	This column is for future use.		NUMBER (8)
answer_text_code	This is the answer code for the title availability. It must be one of the values in APPENDIX D.	This should be populated at the time this transaction order line is transferred to the back office operational system. It should contain the availability of this order transaction line.	VARCHAR2 (2)
answer_text_date	If the ANSWER_TEXT_CODE requires an additional date to be supplied, then this will contain the date information in the format 'Mon-YYYY'.	Please refer to the notes for the ANSWER_TEXT_CODE column.	VARCHAR2 (11)
language_id	This column contains the internal Language ID of the user that entered the order. It is for future use and can be ignored.		VARCHAR2 (5)
invocation_method	This column contains the Invocation method.	The column will contain one of the following values- T-The order line originated from a /TRANSACT file. W-The order line originated from a web based user.	VARCHAR2 (1)
transact_reference	If the order line originated from /TRANSACT then this is the unique reference.		VARCHAR2 (8)
order_number	This is an internal generated number. It can be ignored.		NUMBER (8)
type_of_activity	This is for internal reporting an can be ignored.		VARCHAR2 (2)
order_form_code	If this order line originated from a catalogue then this is the internal catalogue code.		VARCHAR2 (20)
override_price	If a price override has been applied then this is the new price. A zero or NULL price indicates that there is NO price override.		NUMBER (7,2)
requested_discount	If a discount has been supplied within a /TRANSACT order line file, then this column will contain the discount requested. This column is not applicable on web based order lines.		NUMBER (6,2)
central_order_line_number			NUMBER(8,0)
central_order_number			NUMBER(8,0)
affiliate_id	Unique Indentifier of Pubeasy Affiliate		NUMBER (8,0)
transmission_reference			VARCHAR2(8)
transmission_date			DATE
shipping_name			VARCHAR2(100)
shipping_address1			VARCHAR2(100)
shipping_address2			VARCHAR2(100)
shipping_address3			VARCHAR2(100)
shipping_town			VARCHAR2(100)
shipping_county			VARCHAR2(50)
shipping_post_code			VARCHAR2(20)
shipping_country			VARCHAR2(2)
billing_name			VARCHAR2(100)
billing_address1			VARCHAR2(100)
billing_address2			VARCHAR2(100)
billing_address3			VARCHAR2(100)
billing_town			VARCHAR2(100)
billing_county			VARCHAR2(100)
billing_post_code			VARCHAR2(20)
billing_country			VARCHAR2(2)
card_type			VARCHAR2(30)
card_no			VARCHAR2(20)
card_exp_date			VARCHAR2(7)
card_start_date			VARCHAR2(7)
card_issue_no			VARCHAR2(5)
card_holder			VARCHAR2(30)

The following is an example of a returned order line

<order_lines>
  <affiliate_id>2</affiliate_id>
  <answer_text></answer_text>
  <answer_text_code>CS</answer_text_code>
  <answer_text_date></answer_text_date>
  <billing_address1></billing_address1>
  <billing_address2></billing_address2>
  <billing_address3></billing_address3>
  <billing_country></billing_country>
  <billing_county></billing_county>
  <billing_name></billing_name>
  <billing_post_code></billing_post_code>
  <billing_town></billing_town>
  <card_exp_date></card_exp_date>
  <card_holder></card_holder>
  <card_issue_no></card_issue_no>
  <card_no></card_no>
  <card_start_date></card_start_date>
  <card_type></card_type>
  <central_order_line_number></central_order_line_number>
  <central_order_number></central_order_number>
  <customer_id>268</customer_id>
  <cust_account>11223344</cust_account>
  <e_mail>test@bowker.com</e_mail>
  <e_mail_required>Y</e_mail_required>
  <invocation_method>W</invocation_method>
  <language_id>UKENG</language_id>
  <line_reference>1</line_reference>
  <order_date>20060424</order_date>
  <order_form_code></order_form_code>
  <order_from_cust_id></order_from_cust_id>
  <order_line_number>15833</order_line_number>
  <order_number>4568</order_number>
  <order_reference>Not Entered</order_reference>
  <ordstat_status>C</ordstat_status>
  <override_price></override_price>
  <part_supply>N</part_supply>
  <price>85</price>
  <prod_isbn>9789004137738</prod_isbn>
  <promotional_code>promo2013</promotional_code>
  <quantity>1</quantity>
  <record_dues>N</record_dues>
  <requested_discount></requested_discount>
  <shipping_address1></shipping_address1>
  <shipping_address2></shipping_address2>
  <shipping_address3></shipping_address3>
  <shipping_country></shipping_country>
  <shipping_county></shipping_county>
  <shipping_name></shipping_name>
  <shipping_post_code></shipping_post_code>
  <shipping_town></shipping_town>
  <special_instructions></special_instructions>
  <transact_reference></transact_reference>
  <transmission_date></transmission_date>
  <transmission_reference></transmission_reference>
  <type_of_activity>4</type_of_activity>
  <user_id>0001</user_id>
  <vissta_status>P</vissta_status>
</order_lines>

6.6 load_order_results SOAP Request

After an order has been processed by an affiliate's system, the next step will be to load the results of that order back into Pubeasy. This is accomplished with the load_order_results SOAP request. The load_order_results SOAP request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
data	string	The XML string representing a single order_line result of data to load into the database (See below for the xml data string format)

'Data' string format - <data>

The data parameter is an xml string representation of the results of a single order line to update in the order_lines table. Therefore, each column name in the table below represents a single field in the database table for order_lines that can be updated.

Column Name	Description	Notes	Definition
order_line_number	Unique ID Number	Mandatory. Populated by Pubeasy.	NUMBER (8)
vissta_status	Supply status of the Order Line. Populated by Pubeasy and updated by the operational system once the order line has been processed	Defaults To 'A', Refer to APPENDIX C. The description of this code is displayed in the status column of the 'Check Order Status - Recent Orders' page and sent in the order confirmation email.	VARCHAR2 (1)
answer_text	Product Answer Description. Populated by the operational system once the order line has been processed.	This must be one of the standard EDI Answer Descriptions as used in APPENDIX D. This column will be withdrawn in a future release. The column has been superseded with the columns ANSWER_TEXT_CODE and ANSWER_TEXT_DATE.	VARCHAR2 (60)
answer_text_code	This is the answer code for the title availability. It must be one of the values in APPENDIX D.	This should be populated at the time this transaction order line is transferred to the back office operational system. It should contain the availability of this order transaction line.	VARCHAR2 (2)
answer_text_date	If the ANSWER_TEXT_CODE requires an additional date to be supplied, then this will contain the date information in the format 'Mon-YYYY'.	Please refer to the notes for the ANSWER_TEXT_CODE column.	VARCHAR2 (8)
override_price	If a price override has been applied then this is the new price. A zero or NULL price indicates that there is NO price override.		NUMBER (7,2)

The following is an example of a valid data parameter string.

<data>
<order_lines>
  <order_line_number>15855</order_line_number>
  <vissta_status>P</vissta_status>
  <answer_text_code>CS</answer_text_code>
</order_lines>
</data>

6.7 load_order_results SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The order_line was not updated. This usually means that invalid data was passed in and was rejected, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
1	SUCCESS	The order_line was successfully processed (updated) in your Supplier Site.

6.8 Best Practices

One of the significant benefits of the Pubeasy application is that it can provide almost instant order supply status confirmation information back to the bookseller after they have placed a confirmed order. Therefore, it is recommended that when developing your Process Orders API you implement it in such away that it is constantly running. The strategy that is recommended is CHECK->GET->LOAD. #ProcessOrderQueryAPI

7. Process General Order Status Requests/Results API

7.1 Summary

Pubeasy offers the ability for a trade customer to inquire about the status of any order that has been entered into the Affiliate's operational environment. This inquiry facility is not restricted to orders that have been placed via the Pubeasy application but any orders that exist on the Affiliate's operational environment. An interactive API is needed to continually monitor the Pubeasy order_queries table to check and process order queries as soon as they are requested. The strategy that should be implemented to accomplish this with web service calls is CHECK->GET->LOAD.

7.2 check_for_order_queries SOAP Request

The check_for_order_queries SOAP request call is used to return the count of unprocessed order queries for an affiliate. This request has been speed optimized such that it can be called frequently, or continuously as in a loop. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
in_progress	string	OPTIONAL: A string that indicates to search for order queries marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise null)

7.3 check_for_order_queries SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a check_for_order_queries request can either mean that there are currently no outstanding or in progress order queries to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
N	SUCCESS	Where N is any non-negative number. In this case, N represents the total number of outstanding or in progress order queries that need to be processed by the operational environment. The next step will be to get those order queries for processing.

7.4 get_order_queries SOAP Request

The get_order_queries SOAP request call is used to return the actual order queries for an affiliate, in xml format. With this request, it is possible to limit the number of records that are returned to a number that you specify, otherwise the default will return all unprocessed order queries. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
num_recs	unsigned integer	OPTIONAL: An integer that sets the upper limit of records to return. If in_progress is used, a value for num_recs must be used as well (0 - returns all records)
in_progress	string	OPTIONAL: A string that indicates to search for order_queries marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise null)

7.5 get_order_queries SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a get_order_queries request can either mean that there are currently no outstanding or in progress order queries to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
<order_queries> ... </order_queries>	SUCCESS	See the Order_Queries XML string format below for a description of the xml string returned when there are unprocessed order queries

'Order_Queries' XML string format - <order_queries>

The data returned is an xml string representation of an actual order query in the order_queries table. Each order query will be wrapped with <order_queries> ... </order_queries> tags. In the case of multiple order queries, there will be multiple order query items returned. The table below lists each column name that will be returned in each order_queries composite:

Column Name	Description	Notes	Definition
cust_account	Customer Account number	Mandatory	VARCHAR2(20)
query_number	Unique Query Number	Mandatory	NUMBER(8)
order_reference	Originator's Transaction Reference (PO Number)		VARCHAR2(14)
publisher	Publisher Code	THIS IS NOT USED AND MAY BE IGNORED.	VARCHAR2(2)
status	Status Of Order Query Line	Refer to APPENDIX E	VARCHAR2(1)
date_of_query	Date Of Query	YYYYMMDD	DATE
prod_isbn	Product ID	International Standard Book Number	VARCHAR2(13)
user_id	User Id	Mandatory	VARCHAR2(4)
customer_id	Customer ID	Mandatory. This can be ignored by the operational system/. It is used to maintain the referential integrity with the Users table.	NUMBER(8)
invocation_method	This column contains the Invocation method.	The column will contain one of the following values- T-The order query originated from a /TRANSACT file. W-The order query originated from a web based user.	VARCHAR2(1)
ome	This column will contain the OME indicator of the customer.		VARCHAR2(1)
affiliate_id	Unique Indentifier of Pubeasy Affiliate		NUMBER(8,0)
invoice_no	invoice_no is from affiliate given to bookseller		varchar2(22)
cust_ord_date_from	YYYYMMDD		DATE
cust_ord_date_to	YYYYMMDD		DATE

The following is an example of a returned order query:

<order_queries>
  <affiliate_id>2</affiliate_id>
  <customer_id>268</customer_id>
  <cust_account>11223344</cust_account>
  <date_of_query>20060629</date_of_query>
  <invocation_method>W</invocation_method>
  <ome>N</ome>
  <order_reference></order_reference>
  <prod_isbn>0123456789</prod_isbn>
  <publisher></publisher>
  <query_number>1115</query_number>
  <status> </status>
  <user_id>0001</user_id>
  <invoice_no>bowker12345</invoice_no>
  <cust_ord_date_from>20100101</cust_ord_date_from>
  <cust_ord_date_to>20100113</cust_ord_date_to>
</order_queries>

7.6 load_order_query_results SOAP Request

After an order query has been processed by an affiliate's system, the next step will be to load the results of that order query back into Pubeasy. This is accomplished with the load_order_query_results SOAP request. This function loads the order query results of a single order query. There can be multiple results for a single order query however. The load_order_query_results SOAP request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
data	string	The XML string representing the order_query_results of data to load into the database (See below for the xml data string format)
reject_results	string	OPTIONAL For: (1) A string holding the status code R to be used when processing could not be completed, some results rejected. This should be used whenever the total number of results is greater than 9999 records; Or (2) If you can't find any results, then use status code Q (upper case) and in this case, your field "ordquery_query_number" in 'Data' string is the only required parameter, all other fields can be filled with dummy data

'Data' string format - <data>

The data parameter is an xml string representation of the results of a single order query to insert in the order_query_results table. Therefore, each column name in the table below represents a single field in the database table for order_query_results that can be uploaded.

Column Name	Description	Notes	Definition
ordquery_query_number	Unique Query Number	Mandatory Populated By Search Engine This number must be equal to the QUERY_NUMBER in the ORDER_QUERIES_API table that the query came from.	NUMBER(8)
result_number	Unique Query Line Number	Mandatory Populated By Affiliate's Software This is a sequential number identifying each result record	NUMBER(4)
isbn	Product ID	Mandatory International Standard Book Number	VARCHAR2(13)
title	Product Description		VARCHAR2(35)
author	Product Author		VARCHAR2(35)
docref	Document Reference (Invoice number)		VARCHAR2(22)
order_reference	Originator's Transaction Order Reference (PO Number)		VARCHAR2(14)
status	Status Of The Order Line - NO LONGER USED. REPLACED BY THE STATUS_CODE COLUMN.	THIS IS NOT USED.	VARCHAR2(50)
price	Published Price Of Product		NUMBER(7,2)
quantity	Quantity Of Product Ordered		NUMBER(6)
pod_date	Proof Of Delivery Date	All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101.	DATE
pod_signature	Proof Of Delivery Signature		VARCHAR2(30)
source	Order Line Source Code	THIS IS NOT USED	VARCHAR2(1)
status_code	This is a code that reflects the current order status of this record	See APPENDIX H for a list of valid status codes.	VARCHAR2(4)
doc_date	Document Date (Invoice Date)	All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101.	DATE
carrier_code	This is the Carrier Code.		VARCHAR2(3)
tracking_no1	This is the tracking number for the Carrier code.		VARCHAR2(30)
shipper_code	This is the shipper code.		VARCHAR2(3)
tracking_no2	This is the tracking number for the Shipper code.		VARCHAR2(30)
price_type	Price Type Code (refer to APPENDIX L)	VARCHAR2(1)
price_type_desc	Price Type Description (refer to APPENDIX L)	VARCHAR2(100)
discount_applied	Discount percentage, up to three decimal places	NUMBER(6,3)
order_confirmation_number	Affiliate provided number that uniquely identifies order	VARCHAR2(40)
order_date	Date order was originally placed (YYYYMMDD)	DATE
<multi_tracking_info>...</multi_tracking_info>	Support multi-tracking info. It intends to replace tracking_no1 and tracking_no2. If the MULTI_TRACKING_INFO field is not populated by the API then the current tracking fields tracking_no1, tracking_no2 would be still used. This implies that any unmodified API implementations would continue to work without change. If the MULTI_TRACKING field is populated then any data in the current tracking fields listed above will be ignored. multi_tracking_info requires affiliate patch level 33 or higher (refer to multi_tracking_info), carrier_shipper_name can hold up to 80 chars. It should come from table carriers_shippers	VARCHAR2(4000)

The following is an example of xml results data returned from a order_status_query request:

The following is an example of a valid data parameter string.

<data>
  <order_query_results>
    <order_reference>david1</order_reference>
    <ordquery_query_number>1116</ordquery_query_number>
    <isbn>0123456789</isbn>
    <price>40.75</price>
    <result_number>1</result_number>
    <status_code>200</status_code>
    <title>Pubeasy Reference Volume I</title>
  </order_query_results>

  <order_query_results>
    <order_reference>davidzhang2</order_reference>
    <ordquery_query_number>1116</ordquery_query_number>
    <isbn>9876543210</isbn>
    <price>40.75</price>
    <result_number>2</result_number>
    <status_code>200</status_code>
    <title>Pubeasy Reference Volume II</title>
    <price_type>N</price_type>
    <price_type_desc>Net</price_type_desc>
    <discount_applied>20</discount_applied>
    <order_confirmation_number>ABC123</order_confirmation_number>
    <order_date>20041229</order_date>
    <multi_tracking_info>
      <multi_tracking>
        <tracking_info>
            <carrier_shipper_code>DHL</carrier_shipper_code>
            <carrier_shipper_name>DHL international</carrier_shipper_name>
            <tracking_number>123456</tracking_number>
            <pod_date />
            <pod_signature />
        </tracking_info>
        <tracking_info>
           <carrier_shipper_code>RPS</carrier_shipper_code>
            <carrier_shipper_name>FedEx Ground</carrier_shipper_name>
           <tracking_number>87654</tracking_number>
           <pod_date format="YYYYMMDD">20070202</pod_date>
           <pod_signature>Mr Smith</pod_signature>
        </tracking_info>
      </multi_tracking>
    </multi_tracking_info>
  </order_query_results>
</data>

Note that to load multiple order query results, each result is placed within an order_query_results composite. In addition, all results should reference the same order query, thus the ordquery_query_number should be the same in each order_query_results composite.

7.7 load_order_query_results SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The order_query_results were not uploaded. This usually means that invalid data was passed in and was rejected, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
1	SUCCESS	The order_query_results were successfully processed for your Supplier Site.
N	PARTIAL FAILURE	Where N is a non negative value greater than 1. This means that there was a failure uploading some or all of the order query results. To get the total number of order query results failures, subtract one from this number, and that will tell you how many results failed to be uploaded.

7.8 Best Practices

This API has to be run continually to be confident that any queries entered via Pubeasy are processed immediately. The response times are obviously a very important part of this particular Pubeasy option and will be subject to constraints of the Affiliate's operational environments to perform the 'fast' matching process that is required. The strategy that is recommended for implementing this API is CHECK->GET->LOAD. #ProcessBackOrderQueryAPI

8. Process Back Order Status Requests/Results API

8.1 Summary

Pubeasy offers the ability for a trade customer to inquire about the status of any order that has been entered into the Affiliate's operational environment and is currently on back order. This inquiry facility is not restricted to orders that have been placed via the Pubeasy application but any orders that exist on the Affiliates operational environment. An interactive API is needed to continually monitor the Pubeasy back_order_queries table to check and process back order queries as soon as they are requested. The strategy that should be implemented to accomplish this with web service calls is CHECK->GET->LOAD.

8.2 check_for_back_order_queries SOAP Request

The check_for_back_order_queries SOAP request call is used to return the count of unprocessed back order queries for an affiliate. This request has been speed optimized such that it can be called frequently, or continuously as in a loop. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
in_progress	string	OPTIONAL: A string that indicates to search for back order queries marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise null)

8.3 check_for_back_order_queries SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a check_for_back_order_queries request can either mean that there are currently no outstanding or in progress back order queries to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
N	SUCCESS	Where N is any non-negative number. In this case, N represents the total number of outstanding or in progress back order queries that need to be processed by the operational environment. The next step will be to get those back order queries for processing.

8.4 get_back_order_queries SOAP Request

The get_back_order_queries SOAP request call is used to return the actual back order queries for an affiliate, in xml format. With this request, it is possible to limit the number of records that are returned to a number that you specify, otherwise the default will return all unprocessed back order queries. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
num_recs	unsigned integer	OPTIONAL: An integer that sets the upper limit of records to return. If in_progress is used, a value for num_recs must be used as well (0 - returns all records)
in_progress	string	OPTIONAL: A string that indicates to search for back_order_queries marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise null)

8.5 get_back_order_queries SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a get_back_order_queries request can either mean that there are currently no outstanding or in progress back order queries to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
<back_order_queries> ... </back_order_queries>	SUCCESS	See the Back_Order_Queries XML string format below for a description of the xml string returned when there are unprocessed back order queries

'Back_Order_Queries' XML string format - <back_order_queries>

The data returned is an xml string representation of an actual back order query in the back_order_queries table. Each back order query will be wrapped with <back_order_queries> ... </back_order_queries> tags. In the case of multiple back order queries, there will be multiple back order query items returned. The table below lists each column name that will be returned in each back_order_queries composite:

Column Name	Description	Notes	Definition
account	Customer Account Number	Mandatory	VARCHAR2(20)
user_id	User Id	Mandatory	VARCHAR2(4)
query_number	Unique Query Number	Mandatory	NUMBER(8)
prod_isbn	Product ID	International Standard Book Number	VARCHAR2(13)
order_reference	Original order reference associated with the order.		VARCHAR2(14)
cust_ord_date_from	Original customer order date range	YYYYMMDD	DATE
cust_ord_date_to	Original customer order date range	YYYYMMDD	DATE
status	Status Of Back Order Query	Must be ' ' or 'I' or 'P' or 'R' Refer to APPENDIX E	VARCHAR2(1)
date_of_query	Date query was issued.	YYYYMMDD	DATE
query_start	Date/Time Query Started	YYYYMMDD	DATE
query_end	Date/Time Query Finished	YYYYMMDD	DATE
availability_date_from	For future use		VARCHAR2(8)
availability_date_to	For future use		VARCHAR2(8)
customer_id	Pubeasy Unique Identifier for the Customer.	The API can ignore this column as it is used internally within Pubeasy.	NUMBER(8)
invocation_method	This will contain the Invocation Method of the row. It will contain one of the following values- W-The row was generated as a result of a Web based query. T-The row was generated as a result of a transaction that originated via /TRANSACT.		VARCHAR2(1)
ome	This will contain the OME indicator of the customer. It will be a 'Y' or 'N'.		VARCHAR2(1)
affiliate_id	Unique Indentifier of Pubeasy Affiliate		NUMBER(8,0)

The following is an example of a returned back order query:

<back_order_queries>
  <account>11223344</account>
  <affiliate_id>2</affiliate_id>
  <availability_date_from></availability_date_from>
  <availability_date_to></availability_date_to>
  <customer_id>268</customer_id>
  <cust_ord_date_from>20060601</cust_ord_date_from>
  <cust_ord_date_to>20060630</cust_ord_date_to>
  <date_of_query>20060630</date_of_query>
  <invocation_method>W</invocation_method>
  <ome>N</ome>
  <order_reference>5</order_reference>
  <prod_isbn>0123456789</prod_isbn>
  <query_end></query_end>
  <query_number>821</query_number>
  <query_start></query_start>
  <status> </status>
  <user_id>0001</user_id>
</back_order_queries>

8.6 load_back_order_query_results SOAP Request

After a back order query has been processed by an affiliate's system, the next step will be to load the results of that back order query back into Pubeasy. This is accomplished with the load_back_order_query_results SOAP request. This function loads the back order query results of a single back order query. There can be multiple results for a single back order query however. The load_back_order_query_results SOAP request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
data	string	The XML string representing the back_order_query_results of data to load into the database (See below for the xml data string format)
reject_results	string	OPTIONAL For: (1) A string holding the status code R to be used when processing could not be completed, some results rejected. This should be used whenever the total number of results is greater than 9999 records; Or (2) If you can't find any results, then use status code Q (upper case) and in this case, your field "query_number" in 'Data' string is the only required parameter, all other fields can be filled with dummy data

'Data' string format - <data>

The data parameter is an xml string representation of the results of a single back order query to insert in the back_order_query_results table. Therefore, each column name in the table below represents a single field in the database table for back_order_query_results that can be uploaded.

Column Name	Description	Notes	Definition
query_number	Unique Query Number	Mandatory Populated By Search Engine.This number must be equal to the QUERY_NUMBER in the BACK_ORDER_QUERIES_API table that the query came from.	NUMBER (8)
result_number	Unique Query Line Number	Mandatory Populated By Affiliate's Software. This is a sequential number identifying each result record	NUMBER (4)
isbn	Produt ID	Mandatory International Standard Book Number	VARCHAR2 (13)
title	Product Description		VARCHAR2 (70)
author	Product Author		VARCHAR2 (200)
docref	Document Reference		VARCHAR2 (8)
order_reference	Originator's Transaction Order Reference (PO Number)		VARCHAR2 (14)
status	Status Of The Order Line - NO LONGER USED. REPLACED BY THE STATUS_CODE COLUMN.		VARCHAR2 (50)
price	Published Price Of Product		NUMBER (7,2)
quantity	Quantity Of Product Ordered		NUMBER (6)
order_date	Date order was originally placed	All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101.	DATE
doc_date	Document Date	All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101.	DATE
availability	Not used.		VARCHAR2 (24)
availability_date	Answer Code Date	Date Mask Of 'Mmm-YYYY'	VARCHAR2 (8)
status_code	This is a code that reflects the current order status of this record	This column is no longer required. In the next release of Pubeasy it will be removed. It can be ignored. If supplied then it must be either NULL or one of the valid codes (See APPENDIX H for a list of valid status codes).	VARCHAR2 (4)
available	EDI availability answer code.	Mandatory (See APPENDIX D)	VARCHAR2 (2)
price_type
discount_applied

The following is an example of a valid data parameter string.

<data>
  <back_order_query_results>
    <order_reference>5</order_reference>
    <query_number>821</query_number>
    <isbn>0123456789</isbn>
    <price>16.48</price>
    <result_number>1</result_number>
    <status_code>100</status_code>
    <title>Pubeasy Reference Volume I</title>
    <author>John Doe</author>
    <docref>12</docref>
    <availability></availability>
    <availability_date>Jan-2007</availability_date>
    <available>MD</available>
    <status>I</status>
    <price_type></price_type>
    <discount_applied></discount_applied>
  </back_order_query_results>
  <back_order_query_results>
    <order_reference>5</order_reference>
    <query_number>821</query_number>
    <isbn>9876543210</isbn>
    <price>16.48</price>
    <result_number>2</result_number>
    <status_code>100</status_code>
    <title>Pubeasy Reference Volume I</title>
    <author>John Doe</author>
    <docref>12</docref>
    <availability></availability>
    <availability_date>Jan-2007</availability_date>
    <available>MD</available>
    <status>I</status>
    <price_type></price_type>
    <discount_applied></discount_applied>
  </back_order_query_results>
</data>

Note that to load multiple back order query results, each result is placed within an back_order_query_results composite. In addition, all results should reference the same back order query, thus the query_number should be the same in each back_order_query_results composite.

8.7 load_back_order_query_results SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The back_order_query_results were not uploaded. This usually means that invalid data was passed in and was rejected, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
1	SUCCESS	The back_order_query_results were successfully processed for your Supplier Site.
N	PARTIAL FAILURE	Where N is a non negative value greater than 1. This means that there was a failure uploading some or all of the back order query results. To get the total number of back order query results failures, subtract one from this number, and that will tell you how many results failed to be uploaded.

8.8 Best Practices

This API has to be run continually to be confident that any queries entered via Pubeasy are processed immediately. The response times are obviously a very important part of this particular Pubeasy option and will be subject to constraints of the Affiliate's operational environments to perform the 'fast' matching process that is required. The strategy that is recommended for implementing this API is CHECK->GET->LOAD. #ProcessPPI

9. Process Personal Product Information API

9.1 Summary

Pubeasy offers the ability for booksellers to obtain custom/personal-pricing information about a specific ISBN by clicking on a hyperlink. This option is only available to a bookseller if they have a current account with the Affiliate (account number). The API will provide associated information including any special price, currency, base discount and/or market restriction information where available. An interactive API is needed to continually monitor the Pubeasy personal_product_info table to check and process personal product information queries as soon as they are requested. The strategy that should be implemented to accomplish this with web service calls is CHECK->GET->LOAD.

9.2 check_for_ppi SOAP Request

The check_for_ppi SOAP request call is used to return the count of unprocessed personal product info queries for an affiliate. This request has been speed optimized such that it can be called frequently, or continuously as in a loop. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
in_progress	string	OPTIONAL: A string that indicates to search for personal_product_info queries marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise null

9.3 check_for_ppi SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a check_for_ppi request can either mean that there are currently no outstanding or in progress personal product info queries to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
N	SUCCESS	Where N is any non-negative number. In this case, N represents the total number of outstanding or in progress personal product info queries that need to be processed by the operational environment. The next step will be to get those queries for processing.

9.4 get_ppi SOAP Request

The get_ppi SOAP request call is used to return the actual personal_product_info queries for an affiliate, in xml format. With this request, it is possible to limit the number of records that are returned to a number that you specify, otherwise the default will return all unprocessed personal product info queries. This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
num_recs	unsigned integer	OPTIONAL: An integer that sets the upper limit of records to return. If in_progress is used, a value for num_recs must be used as well (0 - returns all records)
in_progress	string	OPTIONAL: A string that indicates to search for personal_product_info queries marked as 'In Progress', i.e. status = 'I' (when using the value must be set to 'I', otherwise null

9.5 get_ppi SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE or NO_RESULTS	The result of 0 from a get_ppi request can either mean that there are currently no outstanding or in progress personal product info queries to be processed, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
<personal_product_info> ... </personal_product_info>	SUCCESS	See the Personal_Product_Info XML string format below for a description of the xml string returned when there are unprocessed personal product info queries.

'Personal_Product_Info' XML string format - <personal_product_info>

The data returned is an xml string representation of an actual personal product info query in the personal_product_info table. Each personal product info query will be wrapped with <personal_product_info> ... </personal_product_info> tags. In the case of multiple queries, there will be multiple personal product info items returned. The table below lists each column name that will be returned in each personal_product_info composite:

Column Name	Description	Notes	Definition
query_number	This is an unique query number. Each successive query number will be higher than the previous one. The interval between queries will not necessarily be a unit value of one. This column is populated by the Pubeasy application.		NUMBER (8)
prod_isbn	This is the product ISBN. This column is populated by the Pubeasy application.	International Standard Book Number	VARCHAR2 (13)
cust_account	This is the Back Office account number. This column is populated by the Pubeasy application.		VARCHAR2 (20)
price	This column will contain one of the following values- 1. The published price of the title in the currency of the Back Office account. 2. This is the net price for this title in the currency of the Back Office account. The value in the PRICE_TYPE column will indicate the type of price.		NUMBER (12,2)
price_type	This column must contain one of the following values- P - The value in the price column is the published price of the title in the currency of the Back Office account. N - The value in the price column is the net price for this title in the currency of the Back Office account.	If set to P then the price does not reflect the discount and the discount % is displayed. If set to N the price does reflect the discount and this is stated on the web page.	VARCHAR2 (1)
availstk	This is the total number of copies currently available in the Back Office system.	This value is ONLY shown if the SHOW_STOCK indicator is set to a value of 'Y' for the publisher that owns this title.	NUMBER (6)
available	This is the current availability of this title. It must be one of the codes listed in APPENDIX D.		VARCHAR2 (2)
availability_date	If the availability code requires the additional information of a date then this column will contain the date in the format of 'Mon-YYYY'.		VARCHAR2 (8)
discount	This is the base discount that the customer is entitled to assuming an order quantity of one.	Further discounts may be applicable if this title is ordered depending on quantity breaks and order value.	NUMBER (6,3)
market_restricted	This column indicates if there is any market restriction on this title for this customer. It must contain a 'Y' or 'N'.		CHAR (1)
agent_name	This is the name of the Agent.		VARCHAR2 (30)
agent_address	This is the address of the Agent.	This field is assumed to be 5 lines of 30 characters for each line and will be displayed in that format.	VARCHAR2 (150)
status	This is the status of this row. It must have one of the following values- The row is awaiting processing. I - The row is currently been processed. P - The row has been processed.		CHAR (1)
currency_code	If the Back Office account operates in a currency that is different to the currency of the Pubeasy site then this will be the currency code of the Back Office account.		VARCHAR2 (4)
restriction_code	This is the restriction code that describes the nature of the restriction on this title being sold to this customer. It must be one of the values stored in APPENDIX I.		VARCHAR2 (3)
creation_date	This is the date and time that this row was created.		DATE
product_qty	This is for future use. It is not currently used and can be ignored.		NUMBER (7)
product_bo_qty	This is for future use. It is not currently used and can be ignored.		NUMBER (7)
subject_qty	This is for future use. It is not currently used and can be ignored.		NUMBER (7)
subject_description	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (100)
substitution_reason	If a substitution will take place, affiliate may display relative information here. Substitution title and ISBN are suggested values for this field.		VARCHAR2(1000)
ome			VARCHAR2(1)
prev_isbn			VARCHAR2(10)
prev_title			VARCHAR2(70)
prev_pub_date			DATE
pub_price			NUMBER(12,2)
affiliate_id	Unique Indentifier of Pubeasy Affiliate		NUMBER(8,0)

The following is an example of a returned personal product info query:

<personal_product_info>
  <affiliate_id>2</affiliate_id>
  <agent_address></agent_address>
  <agent_name></agent_name>
  <availability_date></availability_date>
  <available></available>
  <availstk></availstk>
  <creation_date>20060630</creation_date>
  <currency_code></currency_code>
  <cust_account>11223344</cust_account>
  <discount></discount>
  <market_restricted></market_restricted>
  <ome>N</ome>
  <prev_isbn></prev_isbn>
  <prev_pub_date></prev_pub_date>
  <prev_title></prev_title>
  <price></price>
  <price_type></price_type>
  <product_bo_qty></product_bo_qty>
  <product_qty></product_qty>
  <prod_isbn>0123456789</prod_isbn>
  <pub_price>29.95</pub_price>
  <query_number>160</query_number>
  <restriction_code></restriction_code>
  <status> </status>
  <subject_description></subject_description>
  <subject_qty></subject_qty>
  <substitution_reason></substitution_reason>
</personal_product_info>

9.6 load_ppi_results SOAP Request

After a personal product info query has been processed by an affiliate's system, the next step will be to load the results of that query back into Pubeasy. This is accomplished with the load_ppi_results SOAP request. The load_ppi_results SOAP request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password
data	string	The XML string representing a single personal_product_info result of data to load into the database (See below for the xml data string format)

'Data' string format - <data>

The data parameter is an xml string representation of the results of a single personal product info query to update in the personal_product_info table. Therefore, each column name in the table below represents a single field in the database table for personal_product_info that can be updated.

Column Name	Description	Notes	Definition
query_number	This is an unique query number. Each successive query number will be higher than the previous one. The interval between queries will not necessarily be a unit value of one. This column is populated by the Pubeasy application.		NUMBER (8)
price	This column will contain one of the following values- 1. The published price of the title in the currency of the Back Office account. 2. This is the net price for this title in the currency of the Back Office account. The value in the PRICE_TYPE column will indicate the type of price.		NUMBER (12,2)
price_type	This column must contain one of the following values- P - The value in the price column is the published price of the title in the currency of the Back Office account. N - The value in the price column is the net price for this title in the currency of the Back Office account.	If set to P then the price does not reflect the discount and the discount % is displayed. If set to N the price does reflect the discount and this is stated on the web page.	VARCHAR2 (1)
availstk	This is the total number of copies currently available in the Back Office system.	This value is ONLY shown if the SHOW_STOCK indicator is set to a value of 'Y' for the publisher that owns this title.	NUMBER (6)
available	This is the current availability of this title. It must be one of the codes listed in APPENDIX D.		VARCHAR2 (2)
availability_date	If the availability code requires the additional information of a date then this column will contain the date in the format of 'Mon-YYYY'.		VARCHAR2 (8)
discount	This is the base discount that the customer is entitled to assuming an order quantity of one.	Further discounts may be applicable if this title is ordered depending on quantity breaks and order value.	NUMBER (6,3)
market_restricted	This column indicates if there is any market restriction on this title for this customer. It must contain a 'Y' or 'N'.		CHAR (1)
agent_name	This is the name of the Agent.		VARCHAR2 (30)
agent_address	This is the address of the Agent.	This field is assumed to be 5 lines of 30 characters for each line and will be displayed in that format.	VARCHAR2 (150)
currency_code	If the Back Office account operates in a currency that is different to the currency of the Pubeasy site then this will be the currency code of the Back Office account.		VARCHAR2 (4)
restriction_code	This is the restriction code that describes the nature of the restriction on this title being sold to this customer. It must be one of the values stored in APPENDIX I.		VARCHAR2 (3)
product_qty	This is for future use. It is not currently used and can be ignored.		NUMBER (7)
product_bo_qty	This is for future use. It is not currently used and can be ignored.		NUMBER (7)
subject_qty	This is for future use. It is not currently used and can be ignored.		NUMBER (7)
subject_description	This is for future use. It is not currently used and can be ignored.		VARCHAR2 (100)
substitution_reason	If a substitution will take place, affiliate may display relative information here. Substitution title and ISBN are suggested values for this field.		VARCHAR2(1000)

The following is an example of a valid data parameter string.

<data>
  <query_number>160</query_number>
  <price>12.66</price>
  <discount>10</discount>
  <price_type>P</price_type>
  <currency_code>USD</currency_code>
  <available>SB</available>
  <market_restricted>Y</market_restricted>
  <restricted_code>NA</restricted_code>
  <substitution_reason>Test substitution reason</substitution_reason>
</data>

9.7 load_ppi_results SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The personal_product_info query was not updated. This usually means that invalid data was passed in and was rejected, or the login information provided was invalid or lacked the required privileges (see the check_login request for more information)
1	SUCCESS	The personal_product_info query was successfully processed (updated) in your Supplier Site.

9.8 Best Practices

This API should be run continually to be confident that any personal product info queries entered via the Pubeasy application are processed immediately. The strategy that is recommended for implementing this API is CHECK->GET->LOAD. #CheckLogin

10. Check Login Information API

10.1 Summary

This API was added to aid developers in verifying that they are providing the correct login information to the Legacy Pubeasy Supplier SOAP API web service. This API should be used as a developer's first step during implementation of the Legacy Pubeasy Supplier SOAP API service for an affiliate site.

10.2 check_login SOAP Request

This request is called with the following parameters:

Name	Type	Description
aff_id	unsigned integer	An integer that contains the affiliate's unique identifier
pin	string	A string that contains the login pin
pwd	string	A string that contains the login password

10.3 check_login SOAP Response

Each time you issue a request to the Legacy Pubeasy Supplier API service, a response is returned back to you. This section describes the meanings of the values returned to you.

Return Value	Status	Description
0	FAILURE	The result of 0 from a check_login request means that the login information provided was invalid.
1	SUCCESS	The result of 1 from a check_login request means that the login information provided was valid.

10.4 Best Practices

This goal of this API is to aid the development process. It is recommended that the first API that developers try to implement is this one. This is because this API only checks login information which is necessary for every other API to be called. Therefore it is recommended that you get this API working first before moving on to any others.

11. Process Invoice Request API

The Process Invoice Request API is not supported.

12. WSDL and XML

12.1 WSDL Support

The WSDL files you can use with any development platform that supports web services can be found at the following URLs:

• http://sandbox.pubnet.org/services/legacy/order/?wsdl for using namespaces with http (prefered, http://soap.pubeasy.com/ExchangePEWS)
• http://sandbox.pubnet.org/services/legacy/orderSSL/?wsdl for using namespaces with https (https://soap.pubeasy.com/ExchangePEWS)

Test and Live Legacy Pubeasy Supplier Web Services

For your convenience, Pubeasy has implemented all web services on a test site, in addition to the live site. This will allow you to develop your web service clients worry free. Use this environment as a test platform for your clients before you port them to the live Pubeasy site. Please use the following service endpoints:

• Legacy Pubeasy Supplier Web Service Live URLs (PROD)
  • https://soap.pubnet.org/services/legacy/order/ (prefered, secure)
  • http://soap.pubnet.org/services/legacy/order/ (fallback, if HTTPS is not possible)

• Legacy Pubeasy Supplier Web Service Test URLs (SANDBOX)
  • https://sandbox-soap.pubnet.org/services/legacy/order/ (prefered, secure)
  • http://sandbox-soap.pubnet.org/services/legacy/order/ (fallback, if HTTPS is not possible)

12.2 XML Formatting

Since some of the APIs require xml strings to be embedded inside SOAP parameters, it must be noted that these xml strings must be escaped. For example, assume the following tags, tag1 - tag4, represent an xml string to be passed in as part of the parameter data. The following illustrates how this needs to be accomplished:

...
<data>
  &lt;tag1&gt;VALUE1&lt;/tag1&gt;
  &lt;tag2&gt;VALUE2&lt;/tag2&gt;
  &lt;tag3&gt;VALUE3&lt;/tag3&gt;
  &lt;tag4&gt;VALUE4&lt;/tag4&gt;
</data>
...

The following table illustrates the reserved characters within XML that need to be escaped and their corresponding escaped values. Please note that these characters will need to be escaped in your program if your development platform does not automatically do it already.

Reserved Character	Escaped Value
<	&lt;
>	&gt;
&	&amp;

Keep in mind, the same holds true for xml string responses sent back from the Legacy Pubeasy Supplier SOAP API.

14. Appendices

14.1 Appendix B - Order Line Status Codes

Code	Description	Notes
O	Outstanding : Entered By Bookseller, But Not Yet Confirmed	Set By Pubeasy
C	Confirmed : Entered By Bookseller And Now Confirmed	Set By Pubeasy
I	In Progress : Order Line Processing Currently In Progress	Set By Affiliate's Software
P	Processed : Order Line Processing Complete On Affiliate's System	Set By Affiliate's Software

14.2 Apendix C - VISTA_OP_STATUS Table Codes

Code	Description	Notes
A	Awaiting Processing
B	Awaiting Processing - Substitution
C	In Progress - Pt Supply Only - Substitution
D	In Progress - Stock Available - Substitution
E	Back Ordered - To Follow - Substitution
H	Held
I	In progress
N	Not supplied - not back ordered
O	Order Rejected
P	In progress - part supply only
S	In progress - stock available
T	Back ordered - to follow
Z	Shipped

14.3 Apendix D - Product Availability Status Codes

Code	Description	Notes
AB	Publication abandoned
AD	Apply Direct: item not available to trade
CB	Click Book icon for Availability	Use on records where marketing link is used
CS	Status uncertain: check with customer service
HK	Paperback out of print: hardback available
I2	Import to Order, Available, Ship within 2 weeks
IP	In print and in stock
IT	Import to Order, Available
MD	Manufactured on demand
NP	Not yet published
OF	This format out of print: other format available
OO	On order from publisher
OP	Out of print
OR	Out of print: (to be) replaced by new edition
OS	Out of Stock
PK	Hardback out of print: paperback available
RE	Awaiting reissue
RF	Refer to other publisher or distributor
RM	Remaindered
RP	Reprinting
SB	Substitution
RR	Rights Restricted
TO	Only to order
TU	Temporarily unavailable
UC	Unavailable: reprint under consideration

14.4 Appendix E - Pubeasy Process Codes

Code	Description	Notes
<Space>	Outstanding
I	Processing Currently In Progress
P	Processing Complete
R	Processing could not be completed, some results Rejected

14.5 Appendix H - Order Query Status Descriptions

Status	Description	Notes
100	Order in Progress - Stock Available
101	Order in Progress - Stock Available - Substitution
200	Order Cannot be Supplied - Referred/Restricted
201	Order Cannot be Supplied - Title Status OP or OSI
202	Order Cannot be Supplied - Customer cancel preference
203	Order Cannot be Supplied - Customer cancellation
300	Order Not Supplied - Reason Unspecified
400	Order Back Ordered - To Follow
401	Order Back Ordered - Substitution to Follow
402	Order Back Ordered - NYP
403	Order Back Ordered - Managed release
404	Order Canceled – Managed release
500	Order on Hold - Contact Customer Services
501	Order on hold – awaiting payment
600	Credit note issued – contact Customer Services
800	Order line invoiced, stock allocated - may or may not have been dispatched.
801	Order line invoiced, stock allocated and dispatched.
802	Order line invoiced, stock allocated, not yet dispatched.
803	Order line invoiced, stock allocated and delivered
804	Order line invoiced, substitution, stock allocated
805	Order line invoiced, substitution, stock allocated and shipped
806	Order line invoiced, substitution, stock allocated, not yet shipped
807	Order line invoiced, substitution, stock allocated and delivered
808	Order received, awaiting processing
809	Stock allocated and shipped
810	Stock allocated with substitution and shipped
811	Returned Items
812	Replacement in Progress
813	Replacement Shipped
C800	Order line consigned, stock allocated
C801	Order line consigned, substitution, stock allocated

14.6 Appendix I - Restriction Codes

Restriction Code	Description	Notes
EXT	Order sent to
MR1	Restricted
MR2	Market restricted
NA	Not applicable
REF	Refer to
SNP	Sale not permitted

14.7 Apendix J - Medium Codes

Code	Description	Notes
00	Undefined
AA	Audio
AB	Audio cassette
AC	CD-audio
AD	DAT
AE	Audio disk
AF	Audio tape
AG	MiniDisc?
AH	CD-Extra
AI	DVD Audio
AJ	Downloadable audio file
AK	Pre-recorded digital audio player
AL	Pre-recorded SD card
AZ	Other audio format
BA	Book
BB	Hardback
BC	Paperback
BD	Loose-leaf
BE	Spiral bound
BF	Pamphlet
BG	Leather/fine binding
BH	Board book
BI	Rag book
BJ	Bath Book
BK	Novelty book
BL	Slide bound
BM	Big book
BN	Part-work (fasciculo)
BO	Fold-out book or chart
BP	Foam book
BZ	Other book format
CA	Sheet map
CB	Sheet map, folded
CC	Sheet map, flat
CD	Sheet map, rolled
CE	Globe
CZ	Other cartographic format
DA	Digital
DB	CD-ROM
DC	CD-I
DD	DVD
DE	Game cartridge
DF	Diskette
DG	Electronic book text
DH	Online file
DI	DVD-ROM
DJ	Secure Digital (SD) Memory Card
DK	Compact Flash Memory Card
DL	Memory Stick Memory Card
DM	USB Flash Drive
DN	Double-sided CD/DVD
DZ	Other digital
FA	Film or transparency
FB	Film
FC	Slides
FD	OHP transparencies
FE	Filmstrip
FF	Film
FZ	Other film or transparency format
LB	Library Binding
MA	Microform
MB	Microfiche
MC	Microfilm
MG	Multi-Media
MM	Mass Market
MZ	Other microform
NM	New Media
PA	Miscellaneous print
PB	Address book
PC	Calendar
PD	Cards
PE	Copymasters
PF	Diary
PG	Frieze
PH	Kit
PI	Sheet music
PJ	Postcard book or pack
PK	Poster
PL	Record book
PM	Wallet
PN	Pictures or photographs
PO	Wallchart
PP	Stickers
PQ	Plate (lamina)
PR	Notebook / blank book
PS	Organizer
PT	Bookmark
PZ	Other printed item
TP	Trade Paperback
VA	Video
VB	Video, VHS, PAL
VC	Video, VHS, NTSC
VD	Video, Betamax, PAL
VE	Video, Betamax, NTSC
VF	Videodisk
VG	Betamax Video
VH	VHS video
VI	DVD video
VJ	VHS video
VK	Betamax video
VL	VCD
VM	SVCD
VN	HD DVD
VO	Blu-ray
VP	UMD Video
VZ	Other video format
WW	Mixed product
WX	Quantity Pack
XA	Point of sale material
XB	Dumpbin - empty
XC	Dumpbin - filled
XD	Counterpack - empty
XE	Counterpack - filled
XF	Poster
XG	Shelf strip
XH	Window piece
XI	Streamer
XJ	Spinner
XK	Large book
XL	Shrink-wrapped pack
XZ	Other point of sale
ZA	General merchandise
ZB	Doll
ZC	Soft toy
ZD	Toy
ZE	Game
ZF	T-Shirt
ZZ	Other merchandise

14.8 Apendix L - Pubeasy Price Type Codes

Code	Description	Notes
E	Rental Price
F	Freight Pass Through
L	List Price
N	Net Price
P	Preview Price
R	Retail Price