VICS

V . I . C . S .

Helpful Tips

Newest of the New

XML APIs for the Web

Access Rules

If they are not a customer, they cannot use it.

If they are a customer, they must have an approved contact set up in order to use it. A customer may have many contacts (generally that means employees) that are signed up. Each has their own password, etc with independent approval by the wholesaler.

API's

VicsLogin
ContactHintGet

Signup

ContactSignUp

Contact Management

ContactGet
ContactSet
ContactHintSet
ContactPreferencesGet
ContactPreferencesSet

Placing an Order

CustomerTermsList
CustomerShipToList
CustomerAddressAdd
CustomerShipViaList
OrderCreate
OrderDetail
OrderDelete
OrderHold
OrderMsgAdd
OrderPrint

Inquiries

CustomerAgingSummary
CustomerAgingDetailEmail
OrderHistoryList
ItemQuery
TermsGet
LocationGet
CustomerAddressGet
PriceTypeGet
ShipViaGet
OrderPickVersionGet

Summary of Return Status Codes Generic Notes

~~~~~~~~~~~~~~~~~~~~~

The “login” page is a form with two fields; Nickname and Password. There is a button to login, signup, or get their password hint.

The <VicsLogin> command requires the Nickname and Password. This command returns to you either "OK" with a <contact_number> or "FAILED" (invalid) or "WARNING" which means they are signed up but NOT activated by the wholesaler.

You may get this "WARNING" in other commands that allow a non-activated contact to have limited access. The <contact_number> you get back should be used in almost all subsequent commands. In fact, if you are not sure - send it!

SAMPLE screenshot:

Please Login to begin using the site

Existing customers, click "Sign Up" to request user name and password.

~~~~~~~~~~~~~~~~~~~~~

I. Login: A. VicsLogin

Input XML:

<VicsLogin>
<nickname>John Smith</nickname>
<password>Doggie</password>
</VicsLogin>

Output XML:

<VicsLogin>
  <contact_number>99277</contact_number>
  <CommandStatus>
    <code>OK</code>
    <text>contact validated</text>
  </CommandStatus>
</VicsLogin>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<nickname> format is -Alphanumeric 15-
<password> format is -Alphanumeric 15-
~~ NOTE: Nickname & password are not case sensitive ! ~~

^top of page^

~~~~~~~~~~~~~~~~~~~~~

I. Login: B. ContactHintGet

Input XML:

<ContactHintGet>
<nickname>John Smith</nickname>
<email>john@vicsmba.com</email>
</ContactHintGet>

Output XML:

Notes are listed in order as they appear in the xml input/output above.

Notes:

<nickname> format is -Alphanumeric 15-
<email> format is -Alphanumeric 80-
<contact_number> format is -Numeric 7-
<hint> format is -Alphanumeric 30-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

To signup, you simply need a form for the following fields. When submitted, an email goes to some email address we need to define on the wholesaler computer. You may, or may not, want to validate fields before sending.

Nicknames and Password MUST start with a letter and be at least 3 chars and 4 chars long.
Email must have an "@" sign in it.
The user must enter a VALID wholesaler customer number (or you get "FAILED").

SAMPLE screenshot:

Please complete the following form to signup:
(Underlined fields are required)
You will be contacted once the sign up is complete.

~~~~~~~~~~~~~~~~~~~~~

II. Signup: A. ContactSignUp

Input XML:

<ContactSignUp>
  <customer_number>99277</customer_number>
  <customer_company_name>Ted's Tees</customer_company_name>
  <contact>
    <nickname>John Smith</nickname>
    <password>Doggie</password>
    <email>John@tedstees.com</email>
    <hint>name of dog</hint>
    <name>John Smith</name>
    <phone>9285673727</phone>
  </contact>
</ContactSignUp>

Output XML:

<ContactSignUp>
  <CommandStatus>
    <code>OK</code>
    <text>1 contact added</text>
  </CommandStatus>
</ContactSignUp>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<customer_number> format is -Numeric 7-
<customer_company_name> format is -Alphanumeric 40-
<nickname> format is -Alphanumeric 15-
<password> format is -Alphanumeric 15-
<email> format is -Alphanumeric 80-
<hint> format is -Alphanumeric 30-
<name> format is -Alphanumeric 20-
<phone> format is -Numeric 10-

~~ NOTE: This will send an email to the wholesaler with the info for approval - which must be done before ordering. Error messages you may see: User name must be 3+ chars; Invalid customer number; Customer record duplicate; nickname must start with a letter ! ~~

^top of page^

~~~~~~~~~~~~~~~~~~~~~

III. Contact Management

The full set of fields can be changed using <ContactPreferencesGet> and <ContactPreferencesSet>. You can use various special ones to get the <hint>; the <hint> may be retrieved by Nickname/email combination. All others are by <contact_number>.

~~~~~~~~~~~~~~~~~~~~~

III. Contact Management: A. ContactGet

Input XML:

Output XML:

<ContactGet>
  <contact>
    <nickname>John Smith</nickname>
    <password>Doggie</password>
    <email>John@tedstees.com</email>
    <hint>name of dog</hint>
    <name>John Smith</name>
    <phone>9285673727</phone>
  </contact>
  <CommandStatus>
    <code>OK</code>
    <text>1 contact sent</text>
  </CommandStatus>
</ContactGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<customer_number> format is -Numeric 7-
<nickname> format is -Alphanumeric 15-
<password> format is -Alphanumeric 15-
<email> format is -Alphanumeric 80-
<hint> format is -Alphanumeric 30-
<name> format is -Alphanumeric 20-
<phone> format is -Numeric 10-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

III. Contact Management: B. ContactSet

Input XML:

<ContactSet>
  <contact_number>99277</contact_number>
  <contact>
    <nickname>John Smith</nickname>
    <password>Doggie</password>
    <email>John@tedstees.com</email>
    <hint>name of dog</hint>
    <name>John Smith</name>
    <phone>9285673727</phone>
  </contact>
</ContactSet>

Output XML:

<ContactSet>
  <CommandStatus>
    <code>OK</code>
    <text>1 contact sent</text>
  </CommandStatus>
</ContactSet>

Notes are listed in order as they appear in the xml input/output above.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

III. Contact Management: C. ContactHintSet

Input XML:

Output XML:

Notes are listed in order as they appear in the xml input/output above.

Notes:

<customer_number> format is -Numeric 7-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

III. Contact Management: D. ContactPreferencesGet

Input XML:

Output XML:

<ContactPreferencesGet>
  <preferences>
    <default_mill>Hanes</default_mill>
    <item_number>12345</item_number>
    <style_group>12</style_group>
    <dozens_pieces_code>N</dozens_pieces_code>
    <statement_printing>Y</statement_printing>
    <cash_receipt_printing>N</cash_receipt_printing>
    <invoice_printing>N</invoice_printing>
    <invoice_reprint_printing>N</invoice_reprint_printing>
    <shipment_printing>Y</shipment_printing>
    <ship_via>
      <number>1</number>
      <description>UPS ground</description>
    </ship_via>
    <terms>
      <number>10</number>
      <description>COD check</description>
    </terms>
    <list_flag>O</list_flag>
    <show_available>Y</show_available>
    <show_catalog_images>Y</show_catalog_images>
    <show_other_images>Y</show_other_images>
  </preferences>
  <CommandStatus>
    <code>OK</code>
    <text>1 preferences sent</text>
  </CommandStatus>
</ContactPreferencesGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<customer_number>: format is -Numeric 7-
<default_mill>: format is -Alphanumeric 8-
<item_number>: format is -Alphanumeric 28-
<style_group>: format is -Alphanumeric 20-
<dozens_pieces_code>: "N" (pieces only), "Y" (dozens/pieces)
<terms>:
  NOTE - to allow change, you will need to get the list as well and then match these up.
  You may prefer I send you a <terms> block with the description (ditto ship_via
  & address).
<list_flag>: "O" (order), "C" (catalog), "A" (ask); 1 click, type "Q"
<show_available>: Y/N display in inventory
<show_catalog_images>: Y/N display images in catalog
<show_other_images>: Y/N display other images

^top of page^

~~~~~~~~~~~~~~~~~~~~~

III. Contact Management: E. ContactPreferencesSet

Input XML:

<ContactPreferencesSet>
  <contact_number>99277</contact_number>
  <preferences>
    <terms_number>20</terms_number>
    <default_mill>Hanes</default_mill>
    <item_number>12345</item_number>
    <style_group>12</style_group>
    <dozens_pieces_code>N</dozens_pieces_code>
    <statement_printing>Y</statement_printing>
    <cash_receipt_printing>N</cash_receipt_printing>
    <invoice_printing>N</invoice_printing>
    <invoice_reprint_printing>N</invoice_reprint_printing>
    <shipment_printing>Y</shipment_printing>
    <ship_via_number>10</ship_via_number>
    <list_flag>O</list_flag>
    <show_available>Y</show_available>
    <show_catalog_images>Y</show_catalog_images>
    <show_other_images>Y</show_other_images>
  </preferences>
</ContactPreferencesSet>

Output XML:

<ContactPreferencesSet>
  <CommandStatus>
    <code>OK</code>
    <text>1 preferences set</text>
  </CommandStatus>
</ContactPreferencesSet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<customer_number> format is -Numeric 7-
<terms_number>: becomes default
<default_mill> format is -Alphanumeric 8-
<item_number> format is -Alphanumeric 28-
<style_group> format is -Alphanumeric 20-
<dozens_pieces_code>: "N" (pieces only), "Y" (dozens/pieces)
<statement_printing> see API Preferences
<cash_receipt_printing> API Preferences
<invoice_printing> API Preferences
<invoice_reprint_printing> API Preferences
<shipment_printing> API Preferences
<ship_via_number> format is -Numeric 4-
<list_flag>: "O" (order), "C" (catalog), "A" (ask); 1 click, type "Q"
<show_available>: Y/N display in inventory
<show_catalog_images>: Y/N display images in catalog
<show_other_images>: Y/N display other images

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Placing an Order

The address and terms must be supplied first to determine "legal" shipping choices and pricing. These items determine the "legal" ship vias and pricing. However, some people do not check if COD terms are allowed (for example with US mail) and sometimes do these together. You need to ask the wholesaler. My example has the terms on the 2nd SAMPLE screen below (I would put terms on screen 1).

SAMPLE screenshot 1:

Please Begin Order In This Window

Please enter shipping data below

VICS
P.O. Box 3661
Camp Verde, AZ 86322

SAMPLE screenshot 2:

Your order will need the following data:

<contact_number>: from <VicsLogin>
<terms_number>: from forms -- choices from <CustomerTermsList>
<ship_via_number>: from forms -- choices from <CustomerShipViaList>
<address_number>: from forms -- choices from <CustomerAddressList>
<po_number>: from forms (free form)
<location_number>: You may compute this or ask or ??? Splits???

Note: my screens have some contact information - I allow entry (and update) from these screens.

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: A. CustomerTermsList

Input XML:

Output XML:

<CustomerTermsList>
  <terms>
    <number>30</number>
    <description>net 10</description>
  </terms>
  <default>20</default>
  <CommandStatus>
    <code>OK</code>
    <text>7 terms sent</text>
  </CommandStatus>
</CustomerTermsList>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<customer_number> format is -Numeric 7-
<terms>: these could be in multiples
<number>: Numeric. This can be zero filled up to 11 digits. No dashes. I must have exactly what I sent you (e.g. if I send 5 digits and the first two are "0" -00123- please send that EXACT number).
<description> format is -Alphanumeric 30-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: B. CustomerShipToList

Input XML:

Output XML:

<CustomerShipToList>
  <default>1234</default>
  <address>
    <number>1234</number>
    <description>ship_to</description>
    <company_name>The Company</company_name>
    <contact_name>Bob Smith</contact_name>
    <address1>1234 Main</address1>
    <address2>Suite 1</address2>
    <city>Camp Verde</city>
    <state>AZ</state>
    <zip>86322</zip>
  </address>
  <CommandStatus>
    <code>OK</code>
    <text>6 addresses sent</text>
  </CommandStatus>
</CustomerShipToList>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<customer_number> format is -Numeric 7-
<default>: customer default shipto address
<address>: these could be in multiples
<number>: format is -Numeric 4-
<company_name>: format is -Alphanumeric 32-
<contact_name>: format is -Alphanumeric 32-
<address1>: format is -Alphanumeric 32-
<address2>: format is -Alphanumeric 32-
<city>: format is -Alphanumeric 30-
<state>: format is -Alphanumeric 2-
<zip>: format is -Numeric 9-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: C. CustomerAddressAdd

Input XML:

<CustomerAddressAdd>
  <contact_number>99277</contact_number>
  <address>
    <number>1234</number>
    <description>ship_to</description>
    <company_name>The Company</company_name>
    <contact_name>Bob Smith</contact_name>
    <address1>1234 Main</address1>
    <address2>Suite 1</address2>
    <address3></address3>
    <city>Camp Verde</city>
    <state>AZ</state>
    <zip>86322</zip>
    <temporary>N</temporary>
  </address>
</CustomerAddressAdd>

Output XML:

<CustomerAddressAdd>
  <address_number>4</address_number>
  <CommandStatus>
    <code>OK</code>
    <text>1 address added</text>
  </CommandStatus>
</CustomerAddressAdd>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<address_number> format is -Numeric 7-
<company_name>: format is -Alphanumeric 32-
<contact_name>: format is -Alphanumeric 32-
<address1>: format is -Alphanumeric 32-
<address2>: format is -Alphanumeric 32-
<address3>: Optional, format is -Alphanumeric 32-
Also see: Address3 new tag page.
<city>: format is -Alphanumeric 30-
<state>: format is -Alphanumeric 2-
<zip>: format is -Numeric 9-

<temporary>: "Y" or "N" - is this a temporary address? Note: If “Y” will always add Temporary Address Record (TAD). If “N” will not add a temporary address record and will try to add an alternate address record. If blank (Not set), will add to the alternate address record.

<address_number>: this is the address added

NOTE:
any orders to this address will be on hold pending wholesaler approval

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: D. CustomerShipViaList

Input XML:

Output XML:

<CustomerShipViaList>
  <ship_via>
    <number>2320</number>
    <description>UPS Ground</description>
  </ship_via>
  <default>1</default>
  <CommandStatus>
    <code>OK</code>
    <text>22 ship vias sent</text>
  </CommandStatus>
</CustomerShipViaList>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-
<terms_number> format is -Numeric 8-
<ship_via>: these could be in multiples
<number>: the "key" numeric 4
<description>: format is -Alphanumeric 30-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: E. OrderCreate

Explanation of Line Items:

SKUs are sold in a matrix. One matrix represents one "Mill-Style"; each row in a matrix is a single color. Each column in the matrix is a single size. Where they intersect is a "mill-style-color-size" which we call a "cell" within the matrix. Each cell has an underlying "tracking number" and "size code" which are a 7 digit and a 1 digit number. The combination of tracking number and size is unique and has available inventory (by location) and prices (up to 5). The pop-up window with pricing is for a single cell and pops up when the mouse enters a cell. The "cost" column is the line item total more or less.

When doing inquiries, it is possible to retrieve entire rows (descriptions, pricing, or available inventory). Note that the pricing in this case included four different prices (the columns). The different rows are simply to show the same price in prices and in dozens which is done mathematically (piece price x 12). This entire process is very flexible.

Generally, small, medium, large, & extra large have the same tracking number and price (difference size codes). 2XL and 3XL (and bigger) have different pricing and hence each have a unique tracking number.

A "line item" contains ONE tracking number and MULTIPLE sizes.
A "cell" is a single tracking number/size. A line_item_cell may come over multiple times (up to 6).

You may need to know this for display purposes. The XML block called <line_item> contains up to 6 cells with the same tracking number (and prices) and size codes 1-6.

When I receive "cells" during an OrderCreate, I will combine them into line items by tracking number.

If you give us a <sorted> tag with value "Y" when doing the <OrderCreate>, we'll create the order exactly as you give it to us (not recommended unless you have good sorting on your side). Without that tag or if you send "N" then I will sort it appropriately.

The location is listed at the top with the "short" description (POR=Portland). The pricing is this case includes four different prices (the columns). The different rows are simple to show the same price in pieces and in dozens which is done mathematically (piece price x 12). The pricing is for a single cell and pops up when the mouse enters a cell. The "cost" column totals the line.

You can inquire to get entire rows, do multiple "gets" to build a matrix, or just get one cell. Your choice. Depending on how you do it will determine if you want available, prices, both, or whatever.

One command that does not exist but which you may want would be <RowNetCompute> in which you would send us a bunch of cells and we would treat it as a row and return to you the "net" price for the entire row. Otherwise, you will have to compute this - AND - it is not easy.

Once you have built your "cells" and once you have the header information required (above), you use the <OrderCreate> to send it all to us. If all is good, you get back an <order_number> and "OK". You may get back a "WARNING" instead of "OK". Or, you get "FAILED". In general, no matter how bad it is, we accept the order and give you "WARNING".

OrderCreate

Input XML:

Output XML:

<OrderCreate>
    <order_number>1234-1-1234567-1234</order_number>
  <CommandStatus>
    <code>OK</code>
    <text>Order created</text>
  </CommandStatus>
</OrderCreate>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number>: format is -Numeric 7-
<terms_number>: from TermsList
<invalid_via>: Y/N. If Y, will allow an order to be created if an invalid ship via is not allowed on the web.
<ship_via_number>: from ShipViaList
<address_number>: from ShipToList
<po_number>: format is -Alphanumeric 15-
<cell>: multiples allowed
<tracking_number>: from part master
<size>: from part master; from 1-6

<location_number>: Optional, if not sent in the <cell>, it uses location from header. NOTE: if you split the order yourselves, you only need the <location_number> in the <header> only

<quantity>: in pieces

<sorted>: Optional, Y/N. If you put "Y", then our program will add the line items in exactly the order that you send them. If not (or "N"), then we will sort them (by location-mill-style-colors-size) and then output them. This allows us to more easily combine the sizes into single line items. It will also make the "order" different than your system. You decide.

<order_number>: If splitting, you will only get back the "main" order number. The reason: we have to write new code to do this as the splitting happens later in the print program. It is moot if you are going to split them. If you decide not to and want all the order number, we can change.

<Note>:
Query, we need to deal with the "closest location" scenario. For now, I am assuming you are computing the closest location and are directing the order to the closest location and sending it to us from there.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: F. OrderDetail

Input XML:

Output XML:

<OrderDetail>
  <order_number>1-1234-1234567-1234</order_number>
  <shipped>Not Yet</shipped>
  <summary>1-1234-1234567-1234 from HOP on 2/14/07 for $6.20 invoiced not yet shipped not yet PO cheryl</summary>
  <location>
    <number>1</number>
    <description>MN location</description>
    <short_description>HOP</short_description>
  </location>

Either:
{
  <ship_via>
    <number>1</number>
    <description>UPS Ground</description>
  </ship_via>

Or
  <ship_via>
    <type>bill</type>
    <number>2</number>
    <description>UPS Ground</description>
  </ship_via>
}
  <ship_via>
    <type>ship</type>
    <number>20</number>
    <description>UPS 2nd day</description>
  </ship_via>
  <terms>
    <number>10</number>
    <description>COD company check</description>
  </terms>
  <price_type>
    <number>10</number>
    <description>piece pricing</description>
  </price_type>
  <pick_ticket_version>1</pick_ticket_version>
  <free_freight_info>yes free freight</free_freight_info>
  <address>
    <description>bill_to</description>
    <company_name>The Company</company_name>
    <contact_name>Bob Smith</contact_name>
    <address1>1234 Main</address1>
    <address2>Suite 1</address2>
    <city>Camp Verde</city>
    <state>AZ</state>
    <zip>86322</zip>
  </address>
  <address>
    <description>ship_to</description>
    <number>4</number>
    <company_name>The Company</company_name>
    <contact_name>Bob Smith</contact_name>
    <address1>1234 Main</address1>
    <address2>Suite 1</address2>
    <city>Camp Verde</city>
    <state>AZ</state>
    <zip>86322</zip>
  </address>
  <weight>6</weight>
  <boxes>1</boxes>
  <line_items>1</line_items>
  <gross_to_ship>620</gross_to_ship>
  <line_discount>0</line_discount>
  <free_freight>-482</free_freight>
  <other_discounts>-6</other_discounts>
  <other_charges>0</other_charges>
  <sub_total>132</sub_total>
  <sales_tax>0</sales_tax>
  <other_taxes>0</other_taxes>
  <all_shipping>1457</all_shipping>
  <invoice_total>1589</invoice_total>
  <cash_applied>0</cash_applied>
  <balance_due>1589</balance_due>
  <po_number>joe123</po_number>
  <invoice_number>1-1234567</invoice_number>
  <web_discount>6</web_discount>
If invoiced:
  <box>
    <number>1</number>
    <tracking_number>1z8141000300064995</tracking_number>
    <weight>6500</weight>
    <value>57153</value>
    <shipping>1722</shipping>
    <total>58875</total>
    <cod_amount>58875</cod_amount>
  </box>
  <line>
    <number>1234</number>
      <cell>
        <tracking_number>1234567</tracking_number>
        <size>1</size>
        <item_detail>
        <mill_style_color>1-13200-BLACK</mill_style_color>
        <item_number>1-13200-BLACK-M</item_number>
        <item_description>blue Hanes thing</item_description>
        <size_code>M</size_code>
        <size_description>M</size_description>
        </item_detail>
        <order_quantity>12345</order_quantity>
      </cell>
      <net>123411</net>
  </line>
  <CommandStatus>
    <code>OK</code>
    <text>order detail sent</text>
  </CommandStatus>
</OrderDetail>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-, from VicsLogin

<order_number> from OrderCreate or OrderHistoryList

<shipped> if the order has not been invoiced, the response is "Not Yet". If the order has been invoiced, the ship date will display. An "*" preceeding the date means it was never put on a manifest

<ship_via> type is only set if the actual ship via is different than the ship via charged to the customer. The one actually shipped will have a type of "ship" and the one billed with have a "bill" type

<price_type> reflects the customer type on order

<pick_ticket_version> only sent on current orders if version is greater than zero

<free_freight_info> text describing what free freight was given (often "no free freight")

<company_name> -Alphanumeric 32-
<contact_name> -Alphanumeric 32-
<address1> -Alphanumeric 32-
<address2> -Alphanumeric 32-
<city> -Alphanumeric 30-
<state> -Alpha 2-
<zip> -Numeric 9-

<number> -Numeric-

<free_freight> free freight dollar amount

<sub_total> total of gross_to_ship thru other_charges

<po_number> -Alphanumeric 15-

<web_discount> dollar amount of web discount, already included in totals; this is just a breakdown

<tracking_number> N/A if not UPS

<value> declared package value

<total> total of boxes including discounts/freight, etc. If order is COD, this is generally the same as <total> except that sometimes (1 cod per order) it is not the same. Also value plus shipping does not always equal total

<line> multiples per order

<number> important!

<cell> multiples allowed per line item

<tracking_number> from part master - N/A if not UPS

<size> from part master, always 1-6

<order_quantity> in pieces

<net> extended net price for a line_item_number

Once you create the order it now exists on the wholesaler’s computer. It will have a “hold” status, a message attached to the order saying “it is not complete” and IT WILL NOT PRINT.

If you got back an OK then you should ask the user to confirm and use <OrderPrint>; this will remove the hold status, and print the picking ticket, and remove the message on the order stating that the customer did not complete it.

If you got back WARNING you must decide – should you print or should you email Trimark ?????????? with the order number? Note that any error messages received in the WARNING will also be attached to the order as messages. If you print it, it will NOT remove these messages and it will NOT take the order off of hold until a human examines it.

Also note that order with an address added will be on hold until a human approves.

Besides printing the order you should also allow the user (during the confirmation step) to either delete the order or hold the order. What we do is:

<CreateOrder>
<OrderDetail> (display entire order/totals and any errors)

EXAMPLE Form, asking if they want to print, delete, or hold:

(the rest of this screen is just an <OrderDetail> so they can see the tax, totals, shipping, etc)

Hold and delete are really the same – they ask for a “reason” and this is entered as a message on the order (e..g “Customer asked to hold this order because: <reason why>") The delete does not really delete - it is just a message to the wholesaler to delete (so they can monitor deletes).

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: G. OrderDelete

Input XML:

<OrderDelete>
  <contact_number>99277</contact_number>
  <order_number>1-1234-1234567-1234<order_number>
  <reason>I want to delete<reason>
</OrderDelete>

Output XML:

<OrderDelete>
  <CommandStatus>
    <code>OK</code>
    <text>Delete message recorded on: 2-21-2007</text>
  </CommandStatus>
</OrderDelete>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-
<order_number> from OrderCreate
<reason>: -Alphanumeric 78-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: H. OrderHold

Input XML:

Output XML:

<OrderHold>
  <CommandStatus>
    <code>OK</code>
    <text>Hold message recorded on: 2-21-2007</text>
  </CommandStatus>
</OrderHold>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-
<order_number> from OrderCreate
<reason>: -Alphanumeric 78-

Note:
a person should only be allowed to either print, delete, or hold an order - never more than one of these! The reason becomes an "F8" message.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: I. OrderMsgAdd

You also have the option to add messages to an order with <OrderMsgAdd> - Note: If you do this, the order will go on hold! In general, it uses the existence of messages to determine if an order had errors or not. So, <OrderMsgAdd> is really just a way for YOU to generate errors (perhaps if you have problems with pricing or ???).

Input XML:

Output XML:

<OrderMsgAdd>
  <CommandStatus>
    <code>OK</code>
    <text>Message recorded on: 2-21-2007</text>
  </CommandStatus>
</OrderMsgAdd>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-
<order_number> from OrderCreate
<reason>: -Alphanumeric 78-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

IV. Place an Order: J. OrderPrint

Input XML:

Output XML:

<OrderPrint>
  <CommandStatus>
    <Error>
      <code>WARNING</code>
      <text>Already printed previously, version=2</text>
    </Error>
    <code>WARNING</code>
    <text>Order 1-1-3988 is printing</text>
  </CommandStatus>
</OrderPrint>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-
<order_number> from OrderCreate
<text>: you will get a warning if the pick_ticket_version is greater than zero
<magic>: this is ONLY for the CVV2 number. -Numeric 4-

Note:
this will email the contact their shipping info as things change.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries

Doing various inquiries are generally either contact related, customer related, or order related. The first two require a <contact_number>, the later requires an <order_number>. The contact ones were mostly gone over in the login. Most of the customer ones are to get ship_vias and so forth are gone over in the ordering.

SAMPLE Customer Aging Summary:

In ours, we make them get the summary before they can email the aging report.

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: A. CustomerAgingSummary

Input XML:

Output XML:

<CustomerAgingSummary>
  <current_status>Open</current_status>
  <credit_limit>123411</credit_limit>
  <expires>123411</expires>
  <terms>
    <number>10</number>
    <description>COD check</description>
  </terms>
  <balance>123411</balance>
  <unposted_balance>2071</unposted_balance>
  <column>
    <number>1</number>
    <title>Current</title>
    <amount>123411</amount>
  </column>
  <max_balance>123411</max_balance>
  <max_sales>123411</max_sales>
  <prior_year_sales>123411</prior_year_sales>
  <average_days_to_pay>123456</average_days_to_pay>
  <past_due>Y</past_due>
  <CommandStatus>
    <code>OK</code>
    <text>1 aging sent</text>
  </CommandStatus>
</CustomerAgingSummary>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-
<current_status> from OrderCreate
<text>: you will get a warning if the pick_ticket_version is greater than zero
<magic> ??????????????

Note:
this will email the contact their shipping info as things change.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: B. CustomerAgingDetailEmail

Input XML:

Output XML:

<CustomerAgingDetailEmail>
  <CommandStatus>
    <code>OK</code>
    <text>The aging is printing and will be emailed to xxx@xxx.xxx</text>
  </CommandStatus>
</CustomerAgingDetailEmail>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-

Note:
this will email the contact their customer aged trial balance.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: C. OrderHistoryList

Input XML:

Output XML:

<OrderHistoryList>
  <order_summary>
    <order_number>1-1234-1234567-1234</order_number>
    <date>MM/DD/YYYY</date>
    <invoice_number>1-1234567</invoice_number>
    <shipped>MM/DD/YYYY</shipped>
    <location>
      <number>1</number>
      <description>Denver</description>
      <short_description>Den</short_description>
    </location>
    <ship_via>
      <number>2320</number>
      <description>UPS Ground</description>
    </ship_via>
    <amount>123411</amount>
  </order_summary>
  <CommandStatus>
    <code>OK</code>
    <text>History list sent</text>
  </CommandStatus>
</OrderHistoryList>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> format is -Numeric 7-

Note:
this will email the contact their customer aged trial balance.

We display a header and then the box/tracking information and then the line item detail. I suppose you can do it in any order you like. The terminology we used on the screens matches the XML tags. In turn this matches the terminology used in the wholesaler’s non-web application. It took two pictures to show what is really one screen.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: D. Itemquery

Input XML:

Output XML:

<Itemquery>
  <price_type>
    <number>10</number>
    <description>piece pricing</description>
  </price_type>
  <result>
    <tracking_number>1234567</tracking_number>
    <size>1</size>
    <item_detail>
      <mill_style_color>H-5180-Blue</mill_style_color>
      <item_number>H-5180-Blue-2</item_number>
      <item_description>Blue fleece sweatshirt</item_description>
      <size_code>S</size_code>
      <size_description>small</size_description>
    </item_detail>
    <price>
      <location_number>all</location_number>
      <price_description>piece</price_description>
      <pieces_qty>1</pieces_qty>
      <price_per_piece>310</price_per_piece>
      <price_per_uom>310</price_per_uom>
    </price>
    <price>
      <location_number>all</location_number>
      <price_description>dozen</price_description>
      <pieces_qty>12</pieces_qty>
      <price_per_piece>300</price_per_piece>
      <price_per_uom>3600</price_per_uom>
    </price>
    <available>
      <location_number>1234</location_number>
      <quantity>12345678</quantity>
    </available>
  </result>
  <CommandStatus>
    <code>OK</code>
    <text>History list sent</text>
  </CommandStatus>
</Itemquery>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<tracking_number> from part master
<size> from part master
<want_detail> Y/N - only needed if Y
<want_prices> Y/N - only needed if Y
<want_available> Y/N - only needed if Y
<want_sale> Y/N. See Itemquery - new tags page.
<want_sale_exp> Y/N. See Itemquery - new tags page.
<location_number> required for available, "all" allowed
<terms_number> sometimes prices depend upon (cash)terms; if not sent, customer default terms are used
<quantity_price> shows net price for that line item for a customer
<contact_number> required for prices
<price_type_number> from generic cases
<result> multiples if you sent "all"
<tracking_number> from part master
<size> from part master, always 1-6
<mill_style_color> without size
<item_number> mill-style-color with size
<item_description> text description
<size_code> attribute code 1-6
<size_description> if the last 2 are the same and "BRIEF=Y" won't print
<price> usually from 3-5 of these
<location_number> only sent if prices different by location
<available> could be multiples by location

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: E. TermsGet

Input XML:

Output XML:

<TermsGet>
  <terms>
    <number>10</number>
    <description>COD Company Check</description>
  </terms>
  <CommandStatus>
    <code>OK</code>
    <text>1 terms sent</text>
  </CommandStatus>
</TermsGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<terms_number> -Numeric-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: F. LocationGet

Input XML:

Output XML:

<LocationGet>
  <location>
    <number>1</number>
    <description>MN location</description>
    <short_description>HOP</short_description>
  </location>
  <CommandStatus>
    <code>OK</code>
    <text>1 location sent</text>
  </CommandStatus>
</LocationGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

None

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: G. CustomerAddressGet

Input XML:

Output XML:

<CustomerAddressGet>
  <address>
    <description>ship_to</description>
    <company_name>Joes Bar & Grill</company_name>
    <contact_name>Joe</contact_name>
    <address1>1 Bar Street</address1>
    <city>No Where</city>
    <state>AZ</state>
    <zip>86322</zip>
  </address>
  <CommandStatus>
    <code>OK</code>
    <text>1 address sent</text>
  </CommandStatus>
</CustomerAddressGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<address_number> if address_number is zero or not passed, the shipping address is the same as the billing address. Otherwise, the alternate address number is sent.

<description> optional. bill_to and ship_to are the only valid values. If the address you are looking for is bill_to, no need to pass the address number. If address you are looking for is ship_to, you must pass this.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: H. PriceTypeGet

Input XML:

Output XML:

<PriceTypeGet>
  <price_type>
    <number>10</number>
    <description>piece pricing</description>
  </price_type>
  <CommandStatus>
    <code>OK</code>
    <text>1 price_type sent</text>
  </CommandStatus>
</PriceTypeGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> if contact number sent, if finds the customer type for that customer and responds with that.

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: I. ShipViaGet

Input XML:

Output XML:

<ShipViaGet>
  <ship_via>
    <number>2320</number>
    <description>UPS Ground</description>
  </ship_via>
  <CommandStatus>
    <code>OK</code>
    <text>1 ship_via sent</text>
  </CommandStatus>
</ShipViaGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<number> the key, -Numeric 4-
<description> -Alphanumeric 30-

^top of page^

~~~~~~~~~~~~~~~~~~~~~

V. Inquiries: J. OrderPickVersionGet

Input XML:

Output XML:

<OrderPickVersionGet>
  <pick_ticket_version>1</pick_ticket_version>
  <CommandStatus>
    <code>OK</code>
    <text>pick version sent</text>
  </CommandStatus>
</OrderPickVersionGet>

Notes are listed in order as they appear in the xml input/output above.

Notes:

<contact_number> from Login, -Numeric 7-
<description> from OrderCreate

^top of page^

~~~~~~~~~~~~~~~~~~~~~

Summary of Return Status Codes

OK = worked perfectly
FAILED = pretend you never did it, try again - it didn't work
WARNING = it worked, but there were some problems
4 - 5 others = all FAILED and rare (so if not one of the above 3; treat as failed)

The FAILED is not as simple as I make it out in complex examples. If you add an order and I add 50% of it and then die, it did fail. However, if you just try and add it again you will get WARNING because it will be a duplicate PO (for example). Or cause over credit limit. Or??? So you may need to be careful even with a FAILED -- in this case you could ask to delete the original and then ignore the WARNING.

The WARNING is even more difficult to deal with. Perhaps I got your perfect XML and added a perfect order ... except the price computed to "$0.00" (zero) due to an error in the data on Trimark's computer. I consider free stuff an error so you WILL GET A WARNING with this. You will also get an <error> block in the <CommandStatus> block for EACH warning (there may be several). In this case, the order will get duplicates for your <error> blocks attached to them as messages (F8 for Scott) and the order will be placed on hold!

We will have to work out some decent error processing.

Another area of WARNING we should talk about is in regards to the login status. A customer has 3 states: 1) not signed up 2) signed up but not yet activated by Trimark 3) ready to go.

Some things cannot be done unless you are #3 (like OrderCreate). Some things need nothing (e.g. #1 - like ContactSignup). Some things only need #2 such as setting and getting the hint. BUT, the return text is likely to contain "Valid contact -- not active now" so you can decide. You can use the login to check this up front (#1 and #2 return FAILED and #3 returns OK).

^top of page^

~~~~~~~~~~~~~~~~~~~~~

Generic Notes

Brief

A tag can be passed by you named "brief" --so far, it does things like:

don't send available if available is "zero"
don't send you locations when you asked for a specific location (it will send if you asked for "all")
don't send size_code and size_description if they are the same

On the example page the “order” link allows them to re-order the line automatically, the “catalog” link shows them the catalog page for that item (picture, etc).

There are a bunch of useful calls where you can send a number and get back the related block (such as terms, ship_via, address, location, price_type, etc). These are just for display purposes if you need them.

I included a lot of screen shots. They are not cosmetic masterpieces (in fact I stripped the graphics as a rule). They are meant to show content. I would go over them with the wholesaler for cosmetic issues. Having said that, I would strongly suggest you use the same vocabulary on your screens as we do. This makes it easier for our people to support you, support the wholesaler, and for the wholesaler to support the ultimate end user. This is because all screens on the wholesaler’s system match these.

Echo

The <echo> tag is a Y/N tag. This can be used to echo back the input that you have sent.

Debug

The <debug> tag is a Y/N tag. This sends you back various information used to help you debug values that have been sent back.

BASIC FORMAT:
Many tags such as dates and invoice numbers may in fact get text instead. For example a ship date may have a value of "N/A" if it has not shipped.

All "dollar" fields are without any punctuation and there are two decimals implied -- $12.34 is sent as 1234 and $1.00 is sent as 100.

Other numeric fields are whole numbers and not punctuated -- 1,234 is sent as 1234

Date fields are MM/DD/YYYY unless they are not applicable.

I often refer to fields as "key" fields such as order_number and ship_via_number. These are the actual values I want returned to me. When you use "list" APIs they will return the key and the description (for your list box). Generally "key" values are not seen by the user, they are simply passed back and forth between us.

INQUIRIES:
Please be aware that asking for available inventory is "expensive" and asking for prices is "very expensive" -- meaning that it is perfectly OK to ask for it when you need it, please don't when you don't :-)

CUSTOMER VS CONTACT:
Please be aware of the difference between a "contact" and a "customer" and the "contact name on a ship to address" which are all different things.

LOCATIONS & SPLITTING:
Location descriptions come in two flavors -- a "short" description (6 char) and a "long " (30 chars) that match the host system. You may want me to always send the short one (or long one) or both. Or perhaps you want the location number and you can keep short and long descriptions on your side.

You may want an API to get you the location numbers according to the "closest location" -- this is a complex calculation based on customer defaults, system defaults, ship via chosen, and ship to address. That way, you can default the location to the closest location and if you give a list box of locations (when availability is short) you can list them in normal order. Please be aware of "order splitting" -- when you create an order it may in fact create multiple orders. Each one should be SEPERATELY confirmed and printed. The steps would be to do OrderCreate and then for EACH order_number you get, do an OrderDetail to display to the user. They should then have a chance to print, hold, or delete the order. If splitting an order, you will only get back the “main” order number. The reason – I have to write no code to do that (the splitting happens later in the print program). It is moot if you are going to split them. If you decide not to split and you want all the order numbers, I can change the program. Note: We have not dealt with the “closest location” issue. For now, we are assuming that you are computing the closest location and are direct the order to that location.

^top of page^

New Features in:

Newest of the New

Order Entry

Inventory

Purchasing

Shipping

General Ledger

Accounts Receivable

Accounts Payable

Telemarketing

Credit Cards

Misc

Annual User Conference