Fieldpine Logo Documentation Home  

eLink retailmax.elink.sale.create API


This API allows you to store a new sale into the system. It is designed to receive complete sales that have been generated from a POS system, web selling screen, eCommerce systems or other sources.

Goto: eLink Home | Product Modifiers (coffee)

Input Arguments

SalesHeader:

Arg#BinaryDescription
8's'Required. Constant 'retailmax.elink.sale.create'
100'E' Optional. Sale Id number. If provided, must be unique. This field contains the unique server sale id to be used. Clients should generally not provide this value as several additional undocumented rules exist. If provided, must not be zero; zero is taken as no value provided.
101'y' Optional, highly recommended. Completion Date/Time of the sale. If not supplied the server will insert the current date/time. If you are storing sales for later transmission and there is a chance the date will change between the sale being processed and uploaded via eLink, then this field must be provided as it is required for tax purposes.
103's' Total value of sale, including all taxes. This value should equal f104 + f105 + f106 + f107
104's' Total value of sale, excluding all taxes
105's' Total of tax #1 (GST in New Zealand, Australia, Zimbabwe. MwSt in Germany. VAT in United Kingdom)
106's' Total of tax #2
107's' Total of tax #3
108'E' Optional, recommended. Phase of sale (see retailmax.elink.sale.fetch) Clients may only inject phases, 1=complete, 200=pending, 10000=void (store for audit)
109'y' Optional, recommended. Start Date/Time of the sale. If not supplied the server will insert the completed date/time. If you are storing sales for later transmission and there is a chance the date will change between the sale being processed and uploaded via eLink, then this field must be provided as it is required for tax purposes.
115'E'Teller or staff member id that processed this sale.
117'E' or 's'Customer id that made this sale. These ids are selected from a known list of customers and will positive integers. Zero means unknown customer or value not set.
It is acceptable for distributed environments to use pending customer registrations and supply the TXKC value in this field. For example a newly defined customer record may be stored as "-6,Rs521UDEHAp1560|sq21" where this value is made from the negative Cid value (-6) and TXKC value seperated by a comma. Developers should be aware that this second form is ideally quite rare and should not be used widely.
120's' Optional. Sale total. Total value of sale. If not supplied the server will insert the total of the salelines. If provided, it must be correct otherwise the server will reject the sale and not load it. This is the total of F205 (total price including taxes) fields from Saleline APPT packets
122'E'System Specific identification code.
123'E'System Specific unique sale number. Must be unique for every f122. Must be in the range >0 and < 2^31
125'E'Location id of the store that processed this sale.
130's' External Sale Id. This field allows clients to specify a unique sale indentification string (maximum 32 bytes for maximum system reliability).
131'E'Sales Type information. Provides details about the type of sale being uploaded which is often used for reporting purposes. This field is a bitmask, with the following values defined.
2. Web Site Sale. Sale originated from a CUSTOMER facing website.
4. Wholesale flag. Sale is a wholesale sale, not a standard retail sale. A retail sale with discounts does not set this wholesale flag.
133's'Comments on this sale. Text only, comments DO NOT convey commands to the POS system.
134's'Fly-Buys number
135'E'Fly-Buys capture source. A coded number to indicate how f134 was captured. Possible values are 1=Retrieved from DPS EFTpos termainl, 2=Manual entered, 3=Copied from previous known source, ie anything that is already electronically known. 4=Barcode scanned
136's'Tax registration number, such as GST number in New Zealand, ABN in Australia or VAT# in the United Kingdom.
137's'Tax invoice number, or other legal sale #. This is the number shown to customers, while f100 are primarily internal numbers. If this field is not supplied, f100 is used as the external invoice number where required
138'E'Charge account #. Where a customer/sale is being placed on a charge account, this field contains the account number to charge
139's'Sale Physical Key
144's'Meetu4 Shopper Id Card Number
145'E'Meetu4 Shopper Id Card Number capture source
146'E'Meetu4 Benchmark flags. Bitmask 1=send to Benchmark
147's'Sale Tax control. Used to set specific tax handling features such as tax exempt.
148'E'Target delivery country number. Where delivery of items is known to be an external country this field contains the country items are actually delivered too.
149'E'Stock location number. Location where stock is to be extracted from if not the same as sales reporting location
151's'(Advanced) Status change. Sets the name of a machine or bucket to be called when this sale is altered. Primarily this allows external applications loading sales to be advised when their sales are changed. eg. Web sales send status messages back to the source website as they are accepted/picked/completed.

Dynamic Fields - Used on active sales

600's'Meetu4 reference URL. Includes host part. For example HTTP://MEETU4.ORG/$C100T1K0
601'E'Sale will print indicator. Used on active sales to indicate if a receipt will be printed or not. Has no meaning once a sale is complete.
700's'Company Name or trading name, as would be shown to customers. This may not be the legal name of the retailer.
701's'Receipt Header Lines. May be repeated several times to have multiple lines
702's'Receipt Footer Lines. May be repeated several times to have multiple lines
720's'Automatic Email Receipt requested. This field contains the address to send an email receipt to.
721's'Remaining balance for Layby/Layaway sales

Salelines can be added using an APPT subpacket with the following contents. Complete description of salelines Saleline Object or older structure APPT 21,1

Arg#BinaryDescription
2'E'Required. Constant '1'
3'E'Required. Constant '21'
200'E'Required. Product id for the product being sold.
If this saleline is a modifier (rare) this field contains the Modifier id#
201'E'NYI. Product variant id for the product being sold
202'E'Quantity of product being sold. If not specified the value is assumed to be 1 (one). The quantity field is an integer (not a fractional number) in the measurement units of the product. Most items are unit based (a bar of chocolate), but others are weight or volume based ("flour"). If the item is measured in grams, then this field contains the number of grams. Use caution, as prices are typically in a different measurement, such as $ per Kilogram.
203'E'Pidflag for the product being sold, which indicates the type of product id in f200. All normal products (those listed in retailmax.elink.products) use PidFlag=0, which is the default if not supplied. A value of "5" is used for Product Modifiers.
205's'Required. Total price including all taxes where possible.
206'E'Optional line sequence (ordinal position). If supplied, must be a positive integer.
303's' Total value of line, including all taxes. This value should equal f304 + f305 + f306 + f307. If a sale contains a mix of taxable and non-taxable items, these fields must be present on all packets.
304's' Total value of line, excluding all taxes
305's' Total of tax #1 (GST in New Zealand, Australia, Zimbabwe. MwSt in Germany. VAT in United Kingdom)
306's' Total of tax #2
307's' Total of tax #3
308's' Tax Control information
320's' Optional. Unit price of item used for price calculations.
400'E' Optional. Fuel Dispenser used for this item.
401's' Optional. Serial Number of item. The quantity of this line is expected to be "1" as only one serial number can be stored per line
410'E' Optional/Rare. Picked by Teller Id. (Not typically supplied when storing sales as servers allocate these values as items processed)
411'E' Optional/Rare. Picked Qty. (Not typically supplied when storing sales as servers allocate these values as items processed)
412's' Optional/Rare. Picked total price. (Not typically supplied when storing sales as servers allocate these values as items processed)

Payments can be added using an APPT subpacket with the following contents. Complete description of payments APPT 21,2

Arg#BinaryDescription
2'E'Required. Constant '2'
3'E'Required. Constant '21'
200'E'Required. Payment Type code.
201's'Required. Amount of the payment. This should be the actual amount involved, not rounded or adjusted.
214's'External payment provider reference number. Where the payment was provided by external parties, this field contains a reference to that party.

Physical delivery information can be added with an APPT 21,401. You do not need to store any linking information in fields f100-f119 as these will be added automatically.

If a sale is transmitted with a unique value in SalesHeader.f100 or SalesHeader.f130 that is already know by the server, the sale will not be stored a second time, but the server will return confirmation, like a new sale, not an error. This is explicitly to allow clients to transmit sales multiple times with safety.

If a sale transmits any of the SaleHeader.103, 104, 105, 106, 107 fields (relating to tax breakdown in the sale) it must transmit all the fields.

See also: The following definitions, which defines the underlying database storage written by this bucket: Sales Table | SaleLines Table | Payments Table

Output Fields

On success a QDNE is returned. The following fields may be returned also.

FieldDatatypeDescription
f100NumberThe f100 Sale Id assigned to this sale
f101NumberA number indicating if the server already knew of this sale. While the value of the number has meaning to the server, clients should take any value 1 or higher as indication that the server already knew of the sale, a value of zero, or no value, indicates the sale was loaded now.
f510StringAn information message that should be displayed to the user. This is not a simple confirmation message rather it contains less frequently occurring messages.

Product Modifiers

Product modifiers are additional attributes connected to a saleline describing exact specifications. These are commonly seen when selling something such as coffee. A "Flat White" (product) can have many variations, such as number of sugar, type of milk, blend of coffee, topping plus many others. These additional attributes are sold/described by adding modifier salelines. Modifiers are not free form attributes, but describe a fixed addition or option applied to a product. Milk, for example, can only be selected from an available list of milks.

Product salelines can have any number of modifiers. Each modifier is listed immediately after the product being sold, and has f203=5.

Examples

Minimum sale example. Sends a sale of one unit of product id #77, for a total price of $1. Paid in cash. This example is for demonstration purposes only, clients should provide more information than this for real sales.

 <dati>
  <f8>retailmax.elink.sale.create</f8>
  <APPT>
   <f2>1</f2>
   <f3>21</f3>
   <f200>77</f200>
   <f202>1</f202>
   <f205>1.00</f205>
  </APPT>
  <APPT>
   <f2>2</f2>
   <f3>21</f3>
   <f200>1</f200>
   <f201>1.00</f201>
  </APPT>
 </dati>

Sale of two items at 2-Jan-2011 14:32:22. One for 15.00 with a serial number, the other for 1.3 Kg of flour, measured in grams. The client has assiged unique number "abc-123' to this sale.

 <dati>
  <f8>retailmax.elink.sale.create</f8>
  <f130>ABC-123</f130>
  <f101_y>2011|01|02|14|32|22</f101_y>
  <APPT>
   <f2>1</f2>
   <f3>21</f3>
   <f200>43</f200>
   <f202>1</f202>
   <f205>15.00</f205>
   <f401>XY-41434B</f401>
  </APPT>
  <APPT>
   <f2>1</f2>
   <f3>21</f3>
   <f200>47</f200>
   <f202>1300</f202>
   <f205>6.50</f205>
  </APPT>
  <APPT>
   <f2>2</f2>
   <f3>21</f3>
   <f200>1</f200>
   <f201>21.50</f201>
  </APPT>
 </dati>

Sale of one item, with one modifier, which causes two salelines to be transmitted

 <dati>
  <f8>retailmax.elink.sale.create</f8>
  <f130>ABC-123</f130>
  <f101_y>2011|01|02|14|32|22</f101_y>
  <APPT>
   <f2>1</f2>
   <f3>21</f3>
   <f200>43</f200>
   <f202>1</f202>
   <f203>0</f203>		// Note Product flag set (optional)
   <f205>5.50</f205>
  </APPT>
  <APPT>
   <f2>1</f2>
   <f3>21</f3>
   <f200>4</f200>
   <f202>1</f202>
   <f203>5</f203>		// Note Modifier flag set (required)
  </APPT>
 </dati>