Skip to main content
Avalara Help Center

Install Avalara CertCapture E-Commerce SDK (Software Development Kit)

This article applies to:Avalara CertCapture

In order to install the CertCapture E-Commerce SDK, you must insert a JavaScript tag into your application’s webpage (typically done by your company’s web developer). This lets your website both call for and receive information from the Admin Console's GenCert technology (the SDK).

Requirements

The GenCert API functionality is delivered through a JavaScript “include script” hosted by CertCapture. You need to reference this script on any page that uses the API. Some basic understanding of JavaScript and custom scripting is required in order to properly process callback actions to customize functionality.

In addition to the “script include”, a CertCapture registration is required. This registration consists of the following parameters:

  • Client ID: Identifier for the client that the API connects to.
  • Registration Key: A specific registration key assigned per API instance.
    • Admin level users can find the registration key in: Company Settings > Company Details > CertExpress Settings.
  • IP Address: The IP address of the server that is hosting the application utilizing the API.

Installation

Installation of the API is accomplished via a JavaScript tag included on any application page that requires use of the form:

<script language="JavaScript" src="https://app.certcapture.com/gencert2/js?cid=[client id]&key=[registration key]">
  • cid: Identifier for the client that the API connects to.
  • key: A specific registration key assigned per API instance.

Use

Once you've added the source script to the page, the form needs to be initiated with some initialization JavaScript. This can be handled via a body.onload trigger or a manual trigger. If it's manually triggered, a custom body.onload function needs to be written to ensure that the script source is completely downloaded before an attempt is made to initialize or generate the form.

Initialization

GenCert.init(container, options)
        container: DOM object selected to be the form parent
        options: JSON style parameter object (option parameters below)

Creates a new certificate generation form object tied to a parent DOM element supplied by <container>. This form is initially dormant until the show() function makes it visible. There are a number of options that you can use to provide pre, post, and callback functionality. Additionally, for the form to function properly, a customer number and certificate zone must be provided. This can be included in the constructor options or by specifically calling the setCustomerNumber() and setShipZone() functions.

Constructor

Callback Functions (triggered automatically if defined)

onInit After constructor has finished loading
beforeShow Called before the form is shown
afterShow Called after the form is shown
beforeValidate Before form validation
onValidateSuccess After form validation success, before submit
onValidateFailure After form validation failure
onCertSuccess After submission, when certificate is successful.  Access the generated certificate id with "GenCert.certificateIds".
onCertFailure After submission, when certificate is failure
onCancel User cancels the certificate generation process
onManualSubmit Called when a Manual Submit zone/template is chosen
onNotNeeded Called when a Zone that does not charge sales tax is chosen
onUpload Called when a document is uploaded.  Access the generated certificate id with "GenCert.certificateIds".

Callback Function Important Behaviors

The callbacks defined above will default to an empty function call (does nothing) except for the functions listed below:
onCertSuccess

This callback is usually overridden to perform a customized action such as user navigation after a certificate is successfully created.

onCancel This callback should generally be used to reinitialize GenCert or provide user navigation.
onManualSubmit This callback should generally be used to reinitialize GenCert or navigate the user elsewhere.

Customer Data (Prefilled customer data - inner JSON object with string data fields)

Customer
name

address1

address2

city

state
country
zip

Certificate Data

Syntax Description
customer_number String identifying customer number or unique identifier
ship_zone String identifying exposure zone where a certificate is needed.  Parameter should be a valid US or Canadian state/province in proper case, ex: ('California').  Does not accept lower case or upper case names.

Additional Options

submit_to_stack Defaults to false. Sends certificate to be validated via data entry
preview Defaults to false. Allows user to quickly view the generated certificate for printing purposes. Certificate is not generated in CertCapture
customer_list Defaults to false. Append a page to the generated certificate PDF that includes "Customer Number", "Customer Name", and "Customer Address" of each customer associated with the certificate. Must be called at initialization of GenCert API.
hide_sig Defaults to false. Signature not required. Certificate get sgenerated in CertCapture
upload_only Defaults to false.  Allows uploading an existing prefilled certificate only.
fill_only This option disables upload. A certificate can only be filled via form submission.
show_files Shows a link to download the certificate after the process has been completed.

Additional functions

Here's a list of additional functionality for further customization:

Additional Functions: Descriptions:
setCustomerData(customer) Sets form prefilled with customer data. Function must follow the standard convention below:
GenCert.setCustomerNumber('CustomerTestGencert4'); // create customer
customer = new Object();
customer.name = 'TEST NAME';
customer.address1 = '1300 EAST CENTRAL';
customer.city = 'San fransisco';
customer.state = 'CA';
customer.country = 'US';
customer.zip = '89890';
GenCert.setCustomerData(customer);
GenCert.setShipZone('California');
setCustomerNumber(custnum) Sets the form unique identifier for customer number, to identify the customer to which the certificate should be applied. Parameter custnum should be an alphanumeric unique identifier for the customer filling out the form. The customer number must be supplied via either the constructor options or this function. 
setShipZone(zone) Sets the zone to which the transaction is shipping and/or where the certificate would apply (this is NOT the customer’s ShipTo state). Parameter state should be a valid US or Canadian state/province in proper case, ex: ('California').  Does not accept lower case or upper case names.
The ship zone must be supplied via either the constructor option or this function.
show() Shows the form in the parent container.
hide() Hides the form in the parent container.

Example script

HTML/JavaScript:

<html>
    <head>
        <!-- Please note: You will need to input your client id and registration key in
             the call below for this example to work
        -->
        <script src="
https://app.certcapture.com/gencert2/js?cid=<client_id>&key=<registration_key>"></script>
    </head>
    <body>
        <div id="form_container"></div>
        <script>
            GenCert.init(document.getElementById("form_container"), {

                // Set customer and zone information to pre-determine form
                // The zone and customer must set to start the process!!!
                ship_zone: 'New York',
                customer_number: '123456',
            });
            GenCert.show();
        </script>
    </body>
</html>

Download a printable PDF version of this information here.

Questions? Contact your CertCapture representative. If you have any questions or concerns about the GenCert API, please reach out to your Avalara representative or Avalara Support.