Vision Link API Specification

revision 20220111 matt@winepos.com

Introduction

The Vision Link API provides secure access to the Vision POS System for 3rd party software developers. A web shopping cart can connect to our internet server and submit orders that will then be automatically relayed to the merchant's Vision system.

The Vision Link API is based on HTTP and XML, so you can interact with it from just about any programming language.

HTTP Conventions

You'll need to follow a few conventions

1. Use the hostname sent to you in the welcome email. It should be vznlink.com
2. Use https (http with ssl encryption on port 443).
3. Use the POST method (as opposed to GET, PUT or DELETE).
4. POST to the path /orders
5. Use HTTP Basic authentication. The API username and API password were sent to you in the welcome email.
6. Use Content-Type application/x-www-form-urlencoded

Here is a sample request to the API, including headers:

POST /orders HTTP/1.1
Authorization: Basic YWRtaW4yMTI0ODE6NGFkM2M2NzE2ZjU0OWQ5ZTk2NTdjNWU5MzA5OGYzZTcyNjE2ZjU1Yw==
Host: vznlink.com
Accept: */*
Content-Length: 246
Content-Type: application/x-www-form-urlencoded

<order><api-version>1</api-version>
<items><item><item-num>00812</item-num></item></items></order>

If successful, the reponse Status will be "201 Created". If the response is 302, double-check your authentication code, including the username and password. If the reponse is 500, look at the content of the response for the reason the order was rejected.

XML Conventions - Entities

The XML specification requires that all XML processors represent these five characters (at a minimum) as special entities. Your xml tools should include a method to "escape" them. The Vision Link XML entities do not support formatting elements such as the <sup> tag or <font> tag. If you want to submit these literal values for some reason, then they must be escaped properly.

Unescaped and Incorrect:

<notes>You & I have been "friends" a long time.</notes>

Correct:

<notes>You &amp; I have been &quot;friends&quot; a long time.</notes>

XML Conventions - Case Sensitive

The XML standard defines tags as case sensitive. The tag <order> is different from <Order> which is different from <ORDER>. All XML tags in Vision Link are in lower case.

Customer Order Creation

Example

<order>

  <api-version>2</api-version>
  <vision-customer-num>543210</vision-customer-num>
  <alt-customer-num>34a56</alt-customer-num>
  <alt-num>x123123a</alt-num>
  <source>3</source>
  <orderred>2008-01-12</orderred>
  <notes>Please rush my order.</notes>
  <customer-email>adler@vznlink.com</customer-email>
  <tax><code>NJ</code></tax>
  <first-name>John</first-name>
  <last-name>Smith</last-name>
  <phone>732-555-0909</phone>
  <birthday>1996-01-01</birthday>
  <delivery-time>2019-01-01 01:01:01-04</delivery-time>

  <billing-address>
    <address1>123 Main Street</address1>
    <address2>Apt #2</address2>
    <city>Montclair</city>
    <state>NJ</state>
    <zip-code>07042</zip-code>
    <organization>The Best Wine Club</organization>
  </billing-address>

  <shipping-address>
    <shipping-first-name>Jane</shipping-first-name>
    <shipping-last-name>Doe</shipping-last-name>
    <address1>123 River Road</address1>
    <city>Rumson</city>
    <state>NJ</state>
    <zip-code>07760</zip-code>
    <shipping-phone>732-867-5309</shipping-phone>
    <organization>The Best Wine Club</organization>
  </shipping-address>

  <items>
    <item>
      <item-num>00812</item-num>
      <size>CASE</size>
      <quantity>7</quantity>
      <price>8.95</price>
      <deposit>.5</deposit>
      <tax>
        <code>NJ</code>
        <state>.3</state>
        <county>.2</county>
        <city>.1</city>
      </tax>
    </item>
  </items>

  <tenders>
   <tender>
     <amount>14.94</amount>
     <tender-id>4</tender-id>
   </tender>
  </tenders>

  <subscriptions>
    <subscription>
      <vision_group_id>12345ABC</vision_group_id>
    </subscription>
  </subscriptions>

</order>

Tags

Subscriptions

You can optionally include any number of subscriptions to assign the customer in the order to a customer group in Vision. This is useful for so called 'Wine of the Month' or other promotions that the merchant may have that require the customer to be part of a customer group in Vision.

<subscriptions>
  <subscription>
    <vision_group_id>12345ABC</vision_group_id>
  </subscription>
</subscriptions>

Shipping Charges, Gift Wrap Charges and Coupon Discounts, Subscriptions

Instead of submitting a five digit numeric value for the "item-num", you can submit the text "shipping", "gift_wrap", or "coupon". You can provide a tax amount, just like a regular item. Use the "coupon" item in order to give discounts on the balance due.

Shipping

You can include any number of "shipping" items to represent shipping charges and the associated taxes. The tax field is optional.

<item>
  <item-num>shipping</item-num>
  <price>7.99</price>
  <tax><state>.79</state></tax>
</item>

Gift_Wrap

You can include any number of "gift_wrap" items to represent gift wrap charges and the associated taxes. The tax field is optional.

<item>
  <item-num>gift_wrap</item-num>
  <price>5.99</price>
  <tax><state>0.41</state></tax>
</item>

Coupon

You can include any number of "coupon" items to provide discounts to the shopper. The balance due will be decreased by the price and the tax. The tax field is optional.

<item>
  <item-num>coupon</item-num>
  <price>10.99</price>
  <tax><state>0.76</state></tax>
</item>

Gratuity

You can include any number of "gratuity" items to add gratuity to an order. The balance due will be increased by the price and the tax. The tax field is optional.

<item>
  <item-num>gratuity</item-num>
  <price>4.00</price>
  <tax><state>0.00</state></tax>
</item>

Tenders

Sources

Gift Cards

  <gift-cards>
    <gift-card>
      <code>wf_aaa110</code>
      <balance>10.00</balance>
      <web-code>aaa110</web-code>
    </gift-card>
    <gift-card>
      <code>wf_aaa111</code>
      <balance>0.2</balance>
      <web-code>aaa111</web-code>
    </gift-card>
    <gift-card>
      <code>333</code>
      <balance>33.33</balance>
      <web-code>333</web-code>
    </gift-card>
  </gift-cards>

Refund Creation

/refunds

Example

<refund>

  <api-version>1</api-version>
  <order-alt-num>order123</order-alt-num>
  <alt-num>refund123</alt-num>
  <notes>Please rush my return.</notes>
  <source>3</source>

  <items>
    <item>
      <item-num>61110</item-num>
      <price>9.99</price>
      <size>BOTTLE</size>
      <quantity>2</quantity>
      <tax-code>AAA</tax-code>
      <state-tax>0.2</state-tax>
      <county-tax>0.1</county-tax>
      <city-tax>0.05</city-tax>
    </item>
    <item>
      <item-num>61111</item-num>
      <price>9.99</price>
      <size>BOTTLE</size>
      <quantity>2</quantity>
      <tax-code>AAA</tax-code>
      <state-tax>0.2</state-tax>
      <county-tax>0.1</county-tax>
      <city-tax>0.05</city-tax>
    </item>
  </items>

  <tenders>
    <tender>
      <amount>10.25</amount>
      <tender-id>4</tender-id>
    </tender>
    <tender>
      <amount>10.0</amount>
      <tender-id>3</tender-id>
    </tender>
  </tenders>

</refund>

Tags

sh/curl Sample Implementation

#!/bin/sh
LOGIN=admin123
API_PASS=4076686adcfeff4b6cfbd548b686a3dedd86eaaa
echo '<order><api-version>1</api-version><items><item><item-num>00812</item-num></item></items></order>' > in.xml
curl -s -X POST -v -u $LOGIN:$API_PASS -d @in.xml https://vznlink.com/orders
    

perl/LWP Sample Implementation

#!/usr/bin/perl

use LWP;
# also need Crypt::SSLeay for https

# this info was emailed to you
my $login='admin123';
my $api_key='4076686adcfeff4b6cfbd548b686a3dedd86eaaa';

my $host = "vznlink.com";
my $port = 443;
my $url = "https://${host}:${port}";

my $browser = LWP::UserAgent->new;
# configure "HTTP Basic" authentication with the realm "vznlink"
$browser->credentials( "${host}:$port", "vznlink", $login, $api_key );
# express preference for XML type
my $headers = HTTP::Headers->new( 'Accept' => 'application/xml' );

# your XML content will vary according to your needs
my $content = q{<order><api-version>1</api-version>
<items><item><item-num>00812</item-num></item></items></order>};

# send HTTP POST to "/orders" with XML as body
my $request = HTTP::Request->new( 'POST', $url."/orders", $headers, $content);
my $response = $browser->request($request);
die "Can't create order by posting to $url -- ", $response->status_line
    unless $response->code == 201;
my $order_url = $response->header('location');
print "created order $order_url\n";