This article is a simple introduction to our new Javascript SDK client for browsers. For more information contact support. To use our API you require an enterprise plan and an API key: [email protected].

What can you do with the SDK?

The alpha release of the JS Client allows you to:

  • Post tickets onto boards with file-uploads.
  • Create your own custom contact, lead forms that post to your boards
  • Create and save estimates, with price breakdowns, specs, files and auto-invoicing.
  • Create and send invoices, with specs, price breakdowns and files.

Getting started (browser)

To load the Tudodesk JavaScript SDK, use a script tag like the one in the following example:

<script async defer
  src="https://unruffled-davinci-fe957f.netlify.com/tudo-sdk-latest.min.js">
</script>

How do I get my API access key

To access the Tudodesk API you need an enterprise account and an invitation to use it. Follow the link below for more information.
Request your API credentials and key

Hooks

Hooks add a layer of security by allowing the domain adminstrator to set-up a "hook" endpoint to accept requests from the API. Each hook is mapped to a board. Before you can post submissions from the API the domain Adminstrator will need to set-up the required hook and provide the  hook_id .  

To initialize the SDK you need:

  •  api_key  
  •  hook_id   the ID of the hook you are posting to.
  •  device   a unqiue string that describes the widget you are building.
  •  geo   true or false. If set true we will append GEO data to the submission.
  •  tax_id  required if you are posting an estimate or invoice.
  •  tax_rate   default tax rate (number).
Tudodesk.initialize({api_key:"[API_KEY]",hook_id:"[hook_id]","device": "contact form","geo":true,tax_id:"[tax_id]",tax_rate:20});

Hello World example

The simplest form of using the API

Tudodesk.initialize({api_key:"[API_KEY]",hook_id:"[hook_id]","device": "contact form"});

var payload={"firstname":"John","lastname":"Doe","email":"[email protected]","name":"Hello World"};
//
// Posts a new ticket to the designated board with the title 'Hello World'
//
Tudodesk.ticket.submit(payload,true,function(res){console.log(res);});

The document Helper

The document helper is used for creating more advanced documents.

var estimate = Tudodesk.document({firstname:"John",lastname:"Doe",email:"[email protected]",name:"Test estimate",ref:"abcd"});

You can pass the helper directly to the submit function

Tudodesk.ticket.submit(estimate,false,function(res){console.log(res);});

The helper has the following methods

  • set(property, value)
  • line.money(obj);
  • line.item(obj)
  • addSpecification(str)
  • storeFile(name,url,callback)

Using the Helper to send an estimate

You will need to set-up a hook on the estimate or invoice board. Contact your domain administrator.

Tudodesk.initialize({api_key:"[API_KEY]",hook_id:"[hook_id]","device": "contact form","geo":true,tax_id:"[tax_id]",tax_rate:20});

//
// Here we are using the document helper.
//
var estimate = Tudodesk.document({firstname:"John",lastname:"Doe",email:"[email protected]",name:"Test estimate",ref:"abcd"});

//
// We add two item lines #1,#2 (prices are nett)
// the api will calculate any tax using the tax_rate and tax_id passed when // SDK is initialzed.
//
estimate.line.money({name: "item #1", unit:10});
estimate.line.money({name: "item #2", unit:20,qty:2});

//
// We pass 'false' as the second property instructing the API to mark the
// document as sent. This will fire the autosend event.
//
Tudodesk.ticket.submit(estimate,false,function(res){console.log(res);});

Setting properties

estimate.set("info": "-18mm MDF -Multiple shelves -Heavy duty hindges");
estimate.set("ref": "TUDO10910");
// Billing address
estimate.set("address", "Flat 1 john does place");
estimate.set("city", "New york");
estimate.set("region", "NY");
estimate.set("zipcode", "112012");
estimate.set("country", "United States");

//Shipping address
estimate.set("address_destination", "Flat 2, John does place, New York, NY 112012. United States");
estimate.set("phone", "900-100-2000");
// mobile long id with country code
estimate.set("mobile", "001600700300");

Setting specifications on documents (summary)

Whe you create a document such as an Estimate or an Invoice you can store additional information about the proposal or purchase that is not stored in the money lines. For example you might what to add specifications such as sizes, color, type of finish and so on.

You can add customer specifications to a document as follows:

estimate.set("info","Custom build specification as follows:");
estimate.addSpecification("Width: 300mm");
estimate.addSpecification("height: 250mm");
estimate.addSpecification("25mm MDF board");
estimate.addSpecification("Heavy duty locks, handles and hidges");
estimate.addSpecification("Custom detail and artwork");

Attatching files

Multiple files can be added by passing a file name and URL to the file attachment. The URL should be accessible via a web-browers. You can use basic authentication in your URL should this be required.

estimate.storeFile("googlelogo_color_272x92dp.png","https://www.google.co.uk/images/branding/googlelogo/1x/googlelogo_color_272x92dp.png",function(ev){
  //
  // note we use the async callback to wait before we submit the document.
  //
  Tudodesk.ticket.submit(estimate,false,function(res){console.log(res);});

});

The following file types can be uploaded.

  • PDF files (PDF)
  • Powerpoint files (PPT, PPTX)
  • Excel files (XLS, XLSX)
  • Word files (DOC, DOCX)
  • ODF word processing documents (ODT)
  • ODF presentation documents (ODP)
  • Image files (gif, tiff, jpg, jpeg, png)
  • HTML files.

For full documentation on the current JS SDK contact [email protected]

Did this answer your question?