Legacy Pubeasy Retail SOAP API Programmers Reference

Contents

• How Pubeasy's Retail SOAP API syntax works
• How to interpret the result information sent back to you from the Legacy Pubeasy Retail SOAP API web service.

Item	Description	Operational Method
1	Bibliographic Information API	Pull
2	Order Status Query API	Pull
3	Back Order Status Query API	Pull
4	Invoice Request API	Push
5	Raise Order API	Push

Pull - Data will be extracted from the database

Push - Data will be uploaded into the database

In addition to the five APIs mentioned previously, there are two other optional APIs that may be implemented. These two APIs serve no other purpose but to aid developers in implementing the five Legacy Pubeasy Retail APIs. These two additional APIs are as follows:

Name	Type	Description
pin	string	A string that contains the login pin or ean
user_id	string	A string that contains the login user identification number
pwd	string	A string that contains the clear text password of the login user
query_string	string	The XML string that contains the parameters to search with (See below for the xml query_string format)

Column Name	Description	Definition
isbn	International Standard Book Number (10 or 13 digits)	VARCHAR2 (13)

The following is an example of a valid query_string parameter.

<query_string>
  <isbn>0123456789</isbn>
</query_string>
																

Column Name	Description	Definition
isbn	International Standard Book Number (10 or 13 digits)	VARCHAR2 (13)
region	Region should be either Ame-America or Eur-Europe/UK	VARCHAR2(3)

Example of Query_string with 2 parameters:

<query_string>
  <isbn>0123456789</isbn>
  <region>AME</region>
</query_string>
																

Return Value	Status	Description
0 RESULTS FOUND	FAILURE	The bibliograph request found no matching products within the Pubeasy Database. Please alter your query_string.
-1 INCORRECT LOGIN INFORMATION	FAILURE	The login information provided in the bibliograph request was incorrect or invalid. Please see thecheck_loginrequest for more information
-2 USER DOES NOT HAVE REQUIRED PRIVILEGES	FAILURE	The user provided does not have the required privileges enabled to execute an online product search.
<biblio> ... </biblio>	SUCCESS	See the Biblo XML string format below for a description of the xml string returned when there are matching products found

Column Name	Description	Definition
affiliate	Name of Pubeasy Affiliate	VARCHAR2(50)
affiliate_id	Unique identifier of Pubeasy Affiliate	NUMBER(8,0)
isbn	Product ID (International Standard Book Number)	VARCHAR2(13)
title	Product Description	VARCHAR2(70)
author	Product Author	VARCHAR2(200)
available	Product Availability Code (refer toAPPENDIX D)	VARCHAR2(2)
availability_description	Product Availability Description (refer toAPPENDIX D)	VARCHAR2(120)
sub_title	Extra Product Description	VARCHAR2(300)
long_title	Holds the long title for the product	VARCHAR2(600)
publisher	Publisher's Name	VARCHAR2(160)
medium	Replacement for Binding (seeAPPENDIX J)	VARCHAR2(5)
publication_date	Publication Date Of Product (format returned will be YYYYMMDD)	DATE
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)
currency	Currency Code	VARCHAR2(4)
price	Published Price Of Product	NUMBER(7,2)
series	Series Description	VARCHAR2(40)
order_allowed	Flag To Allow Order to be Placed Against Product	VARCHAR2(1)
pack_size	Binders Pack Size	NUMBER(4,0)
link_to_marketing	A flag indicating if the product provides a link to a marketing site	VARCHAR2(1)
marketing_site_url	The URL of the publishers marketing site for this product	VARCHAR2(200)
price_type	Price Type Code (refer toAPPENDIX L)	VARCHAR2(1)
price_type_desc	Price Type Description (seeAPPENDIX L)	VARCHAR2(35)
edition	Edition number, numeric only	NUMBER(4,0)

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

<biblio>
  <affiliate>Test Bowker Affiliate</affiliate>
  <affiliate_id>0</affiliate_id>
  <author>Charles Dickens</author>
  <availability_description>Refer to another supplier</availability_description>
  <available>RF</available>
  <currency>USD</currency>
  <edition></edition>
  <isbn>0123456789</isbn>
  <link_to_marketing></link_to_marketing>
  <long_title></long_title>
  <marketing_site_url></marketing_site_url>
  <medium>BA</medium>
  <next_isbn></next_isbn>
  <order_allowed>N</order_allowed>
  <other_edition></other_edition>
  <pack_size>1</pack_size>
  <price>14.95</price>
  <price_type></price_type>
  <price_type_desc></price_type_desc>
  <publication_date></publication_date>
  <publisher>Chronicle Books</publisher>
  <series></series>
  <sub_title></sub_title>
  <title>Hard Times</title>
</biblio>
																

Name	Type	Description
pin	string	A string that contains the login pin or ean
user_id	string	A string that contains the login user identification number
pwd	string	A string that contains the clear text password of the login user
query_string	string	The XML string that contains the parameters to search with (See below for the xml query_string format)

Column Name	Description	Definition
affiliate_id	Unique Identifier of Pubeasy Affiliate	NUMBER(8,0)
isbn	International Standard Book Number (10 or 13 digits)	VARCHAR2 (13)
order_ref	A full or partial customer or line reference. This must be entered if the ISBN is not entered	VARCHAR2 (14)
from_date	From Date (All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101)	DATE
to_date	To Date (All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101)	DATE

The following is an example of a valid query_string parameter.

<query_string>
  <affiliate_id>0</affiliate_id>
  <isbn>0123456789</isbn>
  <from_date>20060525</from_date>
  <to_date>20060801</to_date>
</query_string>
																

Return Value	Status	Description
0 RESULTS FOUND	FAILURE	The order_status_query request found no matching orders within the Pubeasy Database. Please alter your query_string
-1 INCORRECT LOGIN INFORMATION	FAILURE	The login information provided in the order_status_query request was incorrect or invalid. Please see thecheck_loginrequest for more information
-2 USER DOES NOT HAVE REQUIRED PRIVILEGES	FAILURE	The user provided does not have the required privileges enabled to execute an order status query
-3 AFFILIATE WITH ID <affiliate_id> DOES NOT EXIST	FAILURE	The affiliate_id provided in the query string is not a valid Pubeasy affiliate_id
-4 AFFILIATE <affiliate_id> DOES NOT HAVE THIS FEATURE ENABLED	FAILURE	The Pubeasy affiliate provided in the query string does not support the Order Status Query Feature
-5 REQUEST TIMED OUT	FAILURE	Order Status Query Request timed out before a response could be returned. Please try again later
-6 AN ERROR OCCURRED DURING REQUEST	FAILURE	An unknown error occurred during this request. Please try again later
-7 ORDER QUERY PROCESSING NOT AVAILABLE AT AFFILIATE WITH ID: <affiliate_id>	FAILURE	Order Status Query processing is currently unavailable at this Affiliate. Please try again later
<order_query_result> ... </order_query_result>	SUCCESS	See the Order_Query_Result XML string format below for a description of the xml string returned when there are matching orders found

Column Name	Description	Definition
record_number	Unique Query Line Number, this is a sequential number identifying each result record (Populated by Pubeasy)	NUMBER(4,0)
affiliate_id	Unique identifier of Pubeasy Affiliate	NUMBER(8,0)
query_number	Unique Query Number (Populated By Pubeasy)	NUMBER(8,0)
result_number	Unique Query Line Number, this is a sequential number identifying each result record (Populated by Affiliate's Software)	NUMBER(4,0)
isbn	Product ID (International Standard Book Number)	VARCHAR2(13)
title	Product Description	VARCHAR2(70)
author	Product Author	VARCHAR2(200)
price	Published Price Of Product	NUMBER(7,2)
quantity	Quantity Of Product Ordered	NUMBER(6,0)
order_reference	Originator's Transaction Order Reference (PO Number)	VARCHAR2(14)
invoice_no	Document Reference (Invoice number)	VARCHAR2(8)
invoice_date	Document Date (Invoice Date)	DATE
status_code	This is a code that reflects the current order status of this record (refer to APPENDIX H)	VARCHAR2(4)
order_status	This is a description of the status code (refer toAPPENDIX H)	VARCHAR2(100)
pod_signature	Proof Of Delivery Signature	VARCHAR2(30)
pod_date	Proof Of Delivery Date	DATE
availability_code	Product Availability Code (refer toAPPENDIX D)	VARCHAR2(2)
availability_desc	Product Availability Description (refer toAPPENDIX D)	VARCHAR2(120)
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)
carrier_code	This is the Carrier Code	VARCHAR2(3)
carrier_name	This is the name of the Carrier	VARCHAR2(80)
tracking_no1	This is the tracking number for the Carrier code	VARCHAR2(30)
shipper_code	This is the Shipper Code	VARCHAR2(3)
shipper_name	This is the name of the Shipped	VARCHAR2(80)
tracking_no2	This is the tracking number for the Shipper code	VARCHAR2(30)
price_type	Price Type Code (refer toAPPENDIX L)	VARCHAR2(1)
price_type_desc	Price Type Description (refer toAPPENDIX 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 tomulti_tracking_info)	VARCHAR2(4000)

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

Name	Type	Description
pin	string	A string that contains the login pin or ean
user_id	string	A string that contains the login user identification number
pwd	string	A string that contains the clear text password of the login user
query_string	string	The XML string that contains the parameters to search with (See below for the xml query_string format)

Column Name	Description	Definition
affiliate_id	Unique Identifier of Pubeasy Affiliate	NUMBER(8,0)
isbn	International Standard Book Number (10 or 13 digits)	VARCHAR2 (13)
order_ref	A full or partial customer order or line reference.	VARCHAR2 (14)
from_date	From Date (All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101)	DATE
to_date	To Date (All DATE fields, unless otherwise specified, must be provided in the format YYYYMMDD, such that January 1, 2006 would be 20060101)	DATE

The following is an example of a valid query_string parameter.

<query_string>
  <affiliate_id>0</affiliate_id>
  <isbn>0123456789</isbn>
  <from_date>20060525</from_date>
  <to_date>20060801</to_date>
</query_string>
																

Return Value	Status	Description
0 RESULTS FOUND	FAILURE	The back_order_status_query request found no matching back orders within the Pubeasy Database. Please alter your query_string
-1 INCORRECT LOGIN INFORMATION	FAILURE	The login information provided in the back_order_status_query request was incorrect or invalid. Please see thecheck_loginrequest for more information
-2 USER DOES NOT HAVE REQUIRED PRIVILEGES	FAILURE	The user provided does not have the required privileges enabled to execute an back order status query
-3 AFFILIATE WITH ID <affiliate_id> DOES NOT EXIST	FAILURE	The affiliate_id provided in the query string is not a valid Pubeasy affiliate_id
-4 AFFILIATE <affiliate_id> DOES NOT HAVE THIS FEATURE ENABLED	FAILURE	The Pubeasy affiliate provided in the query string does not support the Back Order Status Query Feature
-5 REQUEST TIMED OUT	FAILURE	Back Order Status Query Request timed out before a response could be returned. Please try again later
-6 AN ERROR OCCURRED DURING REQUEST	FAILURE	An unknown error occurred during this request. Please try again later
-7 BACK ORDER QUERY PROCESSING NOT AVAILABLE AT AFFILIATE WITH ID: <affiliate_id>	FAILURE	Back Order Status Query processing is currently unavailable at this Affiliate. Please try again later
<back_order_query_result> ... </back_order_query_result>	SUCCESS	See the Back_Order_Query_Result XML string format below for a description of the xml string returned when there are matching back orders found

Column Name	Description	Definition
record_number	Unique Query Line Number, this is a sequential number identifying each result record (Populated by Pubeasy)	NUMBER(4,0)
affiliate_id	Unique identifier of Pubeasy Affiliate	NUMBER(8,0)
query_number	Unique Query Number (Populated By Pubeasy)	NUMBER(8,0)
result_number	Unique Query Line Number, this is a sequential number identifying each result record (Populated by Affiliate's Software)	NUMBER(4,0)
isbn	Product ID (International Standard Book Number)	VARCHAR2(13)
title	Product Description	VARCHAR2(70)
author	Product Author	VARCHAR2(200)
price	Published Price Of Product	NUMBER(7,2)
quantity	Quantity Of Product Back Ordered	NUMBER(6,0)
order_reference	Originator's Transaction Order Reference (PO Number)	VARCHAR2(14)
order_date	Date order was originally placed (YYYYMMDD)	DATE
invoice_no	Document Reference (Invoice number)	VARCHAR2(8)
invoice_date	Document Date (Invoice Date)	DATE
availability_code	Product Availability Code (refer toAPPENDIX D)	VARCHAR2(2)
availability_desc	Product Availability Description (refer toAPPENDIX D)	VARCHAR2(120)
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)
price_type	Price Type Code (refer toAPPENDIX L)	VARCHAR2(1)
price_type_desc	Price Type Description (refer toAPPENDIX L)	VARCHAR2(100)
discount_applied	Discount percentage, up to three decimal places	NUMBER(6,3)

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

<back_order_query_result>
  <record_number>1</record_number>
  <affiliate_id>0</affiliate_id>
  <query_number>575</query_number>
  <result_number>3</result_number>
  <isbn>0123456789</isbn>
  <title>Hard Times</title>
  <author>Charles Dickens</author>
  <price>14.95</price>
  <quantity>3</quantity>
  <order_reference></order_reference>
  <order_date></order_date>
  <invoice_no></invoice_no>
  <invoice_date></invoice_date>
  <availability_code>NP</availability_code>
  <availability_desc>Not yet published</availability_desc>
  <availability_date>20061215</availability_date>
  <price_type>N</price_type>
  <price_type_desc>Net</price_type_desc>
  <discount_applied>20</discount_applied>
</back_order_query_result>
																

The Invoice Request API is not supported.

Name	Type	Description
pin	string	A string that contains the login pin or ean
user_id	string	A string that contains the login user identification number
pwd	string	A string that contains the clear text password of the login user
orders	string	The XML string that contains the order lines to be placed (See below for the xml orders format)
order_ref	string	OPTIONAL: A string that contains the order_reference of every order line in the orders parameter. If this is not provided, a line_reference will be required for each order line
activity_code	string	OPTIONAL: This field will be used byPubeasy

Column Name	Description	Definition
isbn	International Standard Book Number (10 or 13 digits)	VARCHAR2 (13)
record_dues	Allow back orders to be recorded ('Y' or 'N') Note that a NULL entry will be read as N.	VARCHAR2 (1)
part_supply	Allow orders to be part supplied ('Y' or 'N') Note that a NULL entry will be read as N.	VARCHAR2 (1)
order_quantity	Quantity Of Product to order	NUMBER (6)
order_line_reference	Originator's Transaction Line Reference (Line PO Number). If an order_reference is specified without an order_line_reference, then the order_line_reference will automatically be set to the order_reference.	VARCHAR2 (14)
special_instructions	Special Instruction Text. If Populated, Order Will Be Delayed	VARCHAR2 (1600)
affiliate_id	Unique Indentifier of Pubeasy Affiliate	NUMBER (8,0)
promotional_code	Promotional Code, no special characters are allowed, such as $, @. No spaces are allowed	VARCHAR2 (50)

The following is an example of a valid orders parameter.

<orders>
  <order_lines>
   <isbn>0835245373</isbn>
   <record_dues>Y</record_dues>
   <part_supply>Y</part_supply>
   <order_quantity>1</order_quantity>
   <order_line_reference>111111</order_line_reference>
   <affiliate_id>501</affiliate_id>
  </order_lines>
  <order_lines>
   <isbn>0123456789</isbn>
   <record_dues>Y</record_dues>
   <part_supply>Y</part_supply>
   <order_quantity>5</order_quantity>
   <order_line_reference>222222</order_line_reference>
   <special_instructions>These are my special instructions</special_instructions>
   <affiliate_id>502</affiliate_id>
   <promotional_code>promo12345</promotional_code>
  </order_lines>
</orders>
																

Return Value	Status	Description
0 RESULTS FOUND	FAILURE	The raise_order API failed to place any orders into the Pubeasy Database
-1 INCORRECT LOGIN INFORMATION	FAILURE	The login information provided in the raise_order request was incorrect or invalid. Please see thecheck_loginrequest for more information
<result_order_lines> ... </result_order_lines>	FAILURE/SUCCESS	See the Result_Order_Lines XML string format below for a description of the xml string returned

Column Name	Description
status	The status of the order line ('F' - Failed to be raised, 'S' - Successfully Raised)
description	Description of the status
<order_lines> ... </order_lines>	The original order_lines composite is embedded here

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

<result_order_lines>
  <status>F</status>
  <description>-2 USER DOES NOT HAVE REQUIRED PRIVILEGES AT AFFILIATE WITH ID 501</description>
  <order_lines>
    <isbn>0835245373</isbn>
    <record_dues>Y</record_dues>
    <part_supply>Y</part_supply>
    <order_quantity>1</order_quantity>
    <order_line_reference>111111</order_line_reference>
    <affiliate_id>501</affiliate_id>
  </order_lines>
</result_order_lines>
<result_order_lines>
  <status>S</status>
  <description>1 ORDER LINE RAISED SUCCESSFULLY</description>
  <order_lines>
    <isbn>0123456789</isbn>
    <record_dues>Y</record_dues>
    <part_supply>Y</part_supply>
    <order_quantity>5</order_quantity>
    <order_line_reference>222222</order_line_reference>
    <special_instructions>These are my special instructions</special_instructions>
    <affiliate_id>502</affiliate_id>
    <promotional_code>promo12345</promotional_code>
  </order_lines>
</result_order_lines>
																

Name	Type	Description
pin	string	A string that contains the login pin or ean
user_id	string	A string that contains the login user identification number
pwd	string	A string that contains the clear text password of the login user
query_string	string	OPTIONAL: This optional XML string contains the parameters to search with (See below for the xml query_string format)

Column Name	Description	Definition
name	Name of Pubeasy Affiliate	VARCHAR2(50)
affiliate_id	Unique identifier of Pubeasy Affiliate	NUMBER(8,0)

The following is an example of a valid query_string parameter.

<query_string>
  <name>Test Bowker Affiliate<name>   
</query_string>
																

Return Value	Status	Description
0 RESULTS FOUND	FAILURE	The get_affiliate_info found no matching affiliates within the Pubeasy Database. Please alter your query_string
-1 INCORRECT LOGIN INFORMATION	FAILURE	The login information provided in the get_affiliate_info request was incorrect or invalid. Please see thecheck_loginrequest for more information
-2 USER DOES NOT HAVE REQUIRED PRIVILEGES	FAILURE	The user provided does not have the required privileges enabled to execute this request. Online search privileges must be enabled
<affiliate> ... </affiliate>	SUCCESS	See the Affiliate XML string format below for a description of the xml string returned when there are matching affiliates found

Column Name	Description	Definition
affiliate_id	Unique identifier of Pubeasy Affiliate	NUMBER(8,0)
domain_name	URL Address of Pubeasy Affiliate	VARCHAR2(240)
name	Name of Pubeasy Affiliate	VARCHAR2(50)

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

<affiliate>
  <affiliate_id>0</affiliate_id>
  <domain_name>http://test.pubeasy.bowker.com/</domain_name>
  <name>Test Bowker Affiliate</name>
</affiliate>
																

Name	Type	Description
pin	string	A string that contains the login pin or ean
user_id	string	A string that contains the login user identification number
pwd	string	A string that contains the clear text password of the login user

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.

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

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

...
<query_string>
  &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;
</query_string>
...
																

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

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

Header|23|20150818|XO|00230006
1|14193|39429|P0000620|TEST_ORDER|"Perseus"|"Example@emailaddress.com"|"9782759403165"|1|"1212"|N|N||80|0|||||"20150723"|12:00:00|||
2|14194|39430|P0000620|TEST_ORDER|"Perseus"|"Example@emailaddress.com"|"9782759403127"|1|"1213"|Y|N||25|0|||||"20150802"|01:32:48|||
3|14188|39425|P0000620|TEST_ORDER|"Perseus"|"Example@emailaddress.com"|"9780231136235"|1|"123"|Y|Y||27|0|||||"20150406"|09:21:31|||
4|14187|39424|P0000620|TEST_ORDER|"Perseus"|"Example@emailaddress.com"|"9780099268796"|1|"12345"|Y|Y||53.75|0|||||"20150331"|02:37:40|||
5|14190|39426|P0000620|TEST_ORDER|"Perseus"|"Example@emailaddress.com"|"9780231136563"|1|"124"|Y|Y||72.5|0|||||"20150721"|12:00:00|||
6|14192|39428|P0000620|TEST_ORDER|"Perseus"|"Example@emailaddress.com"|"9780231158572"|1|"test"|N|Y||26|0|||||"20150721"|12:00:00|||
7|14264|39492|P0000620|TEST_ORDER|"Perseus"|"Example@emailaddress.com"|"9781569752432"|1|"test5"|N|N||17.95|0|||||"20150817"|12:00:00|||																			"pro"
8|14191|39427|PSLOG1|PSLOG1|"Example Name"|"Example@emailaddress.com"|"9780231136570"|1|"123"|Y|Y||22.5|0|||||"20150406"|10:10:01|||
Trailer|8|8
																		

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