Run Your Entire Company
From One Integrated System
1-800-446-0236 (US)
+1-239-986-0233 (Int'l)
Not Logged In | Login

Web Service API Module

Systemize! features a powerful API (Application Programming Interface) to enable integration with your own external applications or website.

Interaction is performed using XML based SOAP web-service posts, and provides the following functionality:

  • Read any information from the entire database.
  • Create new records or edit existing ones for the following form types:
    • Admin Functions:
      • Contacts
    • Sales Order Functions:
      • Sales Quotes
      • Sales Order Acknowledgements
      • Demo Quotes
      • Demo Order Acknowledgements
    • Service Functions:
      • Return RMAs
    • Communication Functions:
      • E-Mails
      • Notes
    • Finance Functions:
      • Credit Cards

Each database account provides an API Authorization Number and matching transaction key. This information is only available to users you give administrative privilages, and the transaction key can be re-created at any time.

Reading data with the API

Data is read using the fGetDataBuilderData function call, which loads records specified by any DataBuilder® within your database. This allows you to set up DataBuilders to provide any information your website or external application may need.

Parameters for the fGetDataBuilderData function are:

  • lngAPIAuth - provide your API Authorization Number
  • strKey - provide your current transaction key.
  • strSite - provide the name of the site you wish the DataBuilder to be run on.
  • strDBName - provide the name of the DataBuilder® to use, which defines the fields and filtering controlling the requested data.
  • strLogin - provide the e-mail address of the user who created the DataBuilder®. This is required since two DataBuilders may have the same name, but not those created by the same user.
  • lngRecLimit - indicate the maximum number of returnable records, or pass 0 to set no limit. For example, you may be wish to list the last 5 orders that a customer placed with you - so the DataBuilder® can be set to sort by order date in descending order and the record limit set to 5.

Return from fGetDataBuilderData:

Data is returned in the following XML format:

<DataBuilder>
    <Columns>
        <Column1>Name of first column</Column1>
        <Column2>Name of second column</Column2>
    </Columns>
    <Records>
        <Record1>
            <Col1>Value from first column of first record</Col1>
            <Col2>Value from second column of first record</Col2>
        </Record1>
        <Record2>
            <Col1>Value from first column of second record</Col1>
            <Col2>Value from second column of second record</Col2>
        </Record2>
    </Records>
</DataBuilder>

The first column returned by this function will always be "PriKey", which is the unique ID of each record.

The first column returned by this function will always be "PriKey", which is the unique ID of each If an error occurs preventing data from being retrieved then the error description will be returned encapsulated in <ERROR> tags

Writing Data with the API

The first column returned by this function will always be "PriKey", which is the unique ID of each Data is written to your Systemize! database using a different function call for each different form type. New records can be created or existing records modified using the following function calls.

All fields are optional. To not write data to a field, remove reference to it from the XML data stream. To write nothing into a field (i.e. to clear a field in an existing record), keep the reference, but leave the value between the tags blank.

Error Handling

All write function calls return a single result as a string value:

<RESULT>success</RESULT> if successful, or <RESULT>description of error</RESULT> if failure.

Possible errors:

E1 - Invalid API Authorization Number/Transaction Key combination
E2 - Primary Key ID for Editing does not exist
E3 - Transmission Error - could not communicate with database
E4 - Malformed XML
E5 - Invalid data type (attempting to write invalid data into a field, e.g. alphanumeric characters into a numeric field.

Errors occur in order, i.e. if E5 is returned, then E1-E4 have will not occur.

Passing Primary Keys

Some fields in certain tables store reference IDs of a related table. For these fields, you must pass the primary key of the desired record to link. These are available by using the fGetDataBuilderData function, the first column returned by which is always the primary key (ID) of each record. This allows you to apply your own code to determine which ID to use for a particular field. In some cases (for example account codes) this could be hard-coded (after first running fGetDataBuilderData to determine desired IDs), but in others (for example contacts) you may want to run fGetDataBuilderData to determine the correct ID before each write is made.

Contacts

fWriteContact

Parameters:

lngAPIAuth - provide your API Authorization Number
strKey - provide your current transaction key.
lngContactID - pass 0 to create a new contact record, or pass the primary key of a contact to edit. xmlData - using the XML format below, pass the fields you wish to enter into the contact. 

<Contact>
    <Level1>
    <CompanyName>ABC, Inc.</CompanyName>     (String, max 250 characters)
    <StreetAddress>     (String, max 1000 characters)
    1234 Main St.
    Unit 1
    </StreetAddress>
    <City>Fort Myers</City>     (String, max 200 characters)
    <State>FL</State>    (String, max 200 characters)
    <PostalCode>33908</PostalCode>    (String, max 50 characters)
    <Country>USA</Country>    (String, max 200 characters)
    <CompanyPhone>(239)555-9238</CompanyPhone>    (String, max 50 characters)
    <CompanyFax>(239)555-2391</CompanyFax>    (String, max 50 characters)
    <Skype>sype.id.1234</Skype>    (String, max 50 characters)
    <CompanyEmail>support@systemize-software.com</CompanyEmail> 
    (String, max 200 characters)
    <Website>http://www.systemize-software.com</Website>    
    (String, max 200 characters)
    <FirstName>John</FirstName>    (String, max 200 characters)
    <MiddleName>A B</MiddleName>    (String, max 200 characters)
    <LastName>Doe</LastName>    (String, max 200 characters)
    <Salutation>Mr.</Salutation>    (String, max 50 characters)
    <Suffix>Jr.</Suffix>    (String, max 50 characters)
    <Title>Software Engineer</Title>    (String, max 200 characters)
    <ContactPhone>(239)555-2393</ContactPhone>    (String, max 50 characters)
    <ContactFax>(239)555-2910</ContactFax>    (String, max 50 characters)
    <Cell>(239)555-1000</Cell>    (String, max 50 characters)
    <Pager>(239)555-2000</Pager>    (String, max 50 characters)
    <ContactEmail>aford@systemize-software.com</ContactEmail>    
    (String, max 200 characters)
    <Correspondance>Yes</Correspondance>    (Yes or No as string)
    <Invoice>No</Invoice>    (Yes or No as string)
    <Delivery>Yes</Delivery>    (Yes or No as string)
    <Source>Trade Show</Source>    (String, max 200 characters)
    <Notes>These are some notes.</Notes>    
    (String, max 8000 characters)
    <Custom1>Info</Custom1>    (String, max 200 characters)
    <Custom2>Info</Custom2>    (String, max 200 characters)
    <Custom3>Info</Custom3>    (String, max 200 characters)
    <Custom4>Info</Custom4>    (String, max 200 characters)
    <PostRequest>Yes</PostRequest>    (Yes or No as string)
    <Post>No</Post>    (Yes or No as string)
</Level1>
</Contact>

Sales Quotes

fWriteSalesQuote

This function will return the document number of the newly created (or edited) quote as a long integer.

Parameters:

lngAPIAuth - provide your API Authorization Number
strKey - provide your current transaction key.
strSite - pass the name of the site to create or edit the quote on.
strDocNo - pass a zero to create a new quote (the newly created quote number ill be used in sequence, and returned by the function), or pass an existing quote number to edit an existing quote.
xmlData - using the XML format below, pass the fields you wish to enter into the quote. 

<Quote>
    <Level1>    (Level 1 is the general information about the quote. 
    There can only be one level 1 per function call.)
        <QuoteToContactID>12345</QuoteToContactID>    (numeric)
<DeliverToContactID>12345</DeliverToContactID>    (numeric)
<DestributorContactID>12345</DistributorContactID>    (numeric)
<InternalContactUserID>12345</InternalContactUserID>    (numeric)
<QuoteDate>12-Aug-2008</QuoteDate>    (string, with date formatted as DD-MMM-YYYY)
<PaymentTermsID>12345</PaymentTermsID>    (numeric)
<FreightTermsID>12345</FreightTermsID>    (numeric)
<TermsID>12345</TermsID>    (numeric)
<CurrencyID>12345</CurrencyID>    (numeric)
<ShippingValue>12345</ShippingValue>    (numeric)
<HandlingValue>12345</HandlingValue>    (numeric)
<Notes>Notes</Notes>    (string, max 8000 characters)
<Internal Notes>More Notes</Notes>    (string, max 8000 characters)
<Custom1>Info</Custom1>     (string, max 200 characters)
<Custom2>Info</Custom2>     (string, max 200 characters) 
    <Level2>    (Level 2 creates a record for each line of the quote. There can be
     multiple level 2 records for each level 1.)
        <LineNumber>1</LineNumber>    (numeric) (Pass a zero to create a new line, 
        or a positive integer to edit an existing line on an existing quote.)
        <PriceListID>12345</PriceListID>    (numeric)
        <PartID>12345</PartID>    (numeric)
        <Qty>4</Qty>    (numeric)
        <DiscountEach>350.25</DiscountEach>    (numeric)
        <LeadTime>1</LeadTime>    (numeric)
        <Taxable>Yes</Taxable>    (Yes or No as string)
            <Level3>    (Level 3 creates a records for options against any line 
            of the quote. There can be multiple level 3 records for each level 2.
             Existing options will be replaced for any line for which level 3s are 
             added to an existing quote.)
                <PartID>12345</PartID>    (numeric)
                <PriceEach>85.99</PriceEach>    (numeric)
                <Quantity>6</Quantity>    (numeric)
            </Level3>
            <Level3>
                <PartID>12345</PartID>    (numeric)
                <PriceEach>5</PriceEach>    (numeric)
                <Quantity>1</Quantity>    (numeric)
            </Level3>
    </Level2>
    <Level2>
        <LineNumber>2</LineNumber>    (numeric)
        <PriceListID>12345</PriceListID>    (numeric)
        <PartID>12345</PartID>    (numeric)
        <Qty>2</Qty>    (numeric)
        <DiscountEach>0</DiscountEach>    (numeric)
        <LeadTime>3</LeadTime>    (numeric)
        <Taxable>No</Taxable>    (Yes or No as string)
    </Level2>
</Level1>