We recommend you contact Avalara Professional Services before you install and configure the ecommerce Software Developer Kit (SDK) for help with implementation.
If this is your first time using the CertCapture SDK, plan your implementation before you begin installation.
- Client ID - Identifier for the client that the API connects to, located in your CertCapture account at Company Settings > Company Details > Company Information.
- Registration Key - A specific registration key assigned per API instance, located in your CertCapture account at Company Settings > Company Details > Webportal Registration.
- IP Address - The IP address of the server hosting the application and using the API.
- Cid - Identifier for the client that the API connects to
- Key - The registration key assigned per API instance, located in your CertCapture account at Company Settings > Company Details > Webportal Registration
Initialize the form
The GenCert.init function 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. Specify the DOM object and JSON style parameter in the function, based on the example below.
- Container - DOM object selected to be the form parent
- Options - JSON style parameter object (option parameters below)
There are a number of options that you can use to provide pre, post, and callback functionality. A customer number and certificate zone must be provided for full functionality. This can be included in the constructor options or by specifically calling the setCustomerNumber() and setShipZone()functions.
Use functions to construct a script
Use the functions in this section to construct a certificate form. The following callback functions will trigger automatically if defined:
|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"|
The following callback functions are common functions that should be overridden for custom website behavior:
|Callback functions (Important Behaviors)|
|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|
The following callback functions relate to customer data that can be populated in your form:
|Customer data (Prefilled customer data - inner JSON object with string data fields)|
The following functions relate to customer certificates and shipping zones:
Certificate data (syntax and description)
|certificate_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.|
The following functions allow greater customization of the form before, during, and after submission:
|Additional options and functions|
|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.|
|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';
|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.|
// Set customer and zone information to pre-determine form