Skip to main content
Qwilr API

Development cycle

The process of getting your integration up and running can take some time. We have some recommended best practices to make it as smooth as possible for you.

Spike your integration

Start by following our quick-start guide to creating a page from a template, with a token. Use this to confirm you can create a page from your system, altering the value of the custom token in JSON. This isn't about design, it's about proving data can be passed along successfully.

This will help you assess every further piece of work for complexity + difficulty.

Developing your collateral components

You can build and optimise your collateral through your entire development process. Like many design + development workflows, we recommend being more progressed with collateral design than your development, to ensure you're minimising any wasted development.

Build an example of an entire document as you want it to appear after being created using the API.

When you feel like you're 70-80% done, you can begin to design your implementation.

Designing your JSON structure

Based on the document you've designed, you'll need to assess whether you'll be using a template, or Saved Blocks to construct your page.

Should you use templates or saved blocks?

Saved blocks are more flexible than templates, at the expense of complexity.

Templates are great for cookie-cutter type pages with low variation of structure. Content Tokens can easily be placed throughout the document, but a restructure of the content is not possible as part of the API call.

Saved blocks are great for pick-n-mix type pages that have high variation of structure, based on custom logic. If you want to include or exclude entire sections of a "master template", iterate over a section of a document, or reorder certain parts of a page based on some business logic, then using Saved Blocks is right for you.

Once you've made this decision, you can write a set of mock-JSON to indicate how the document will be broken up, giving you an indication of where your solution will provide flexibility and where it will provide consistency.

Developing your Quote Block JSON

If you're using a template

  1. You'll need to retrieve the template ID from the URL you see when editing the template. https://app.qwilr.com/#/page/**your-template-id-here**
  2. Add this under the "templateId" field.
  3. Add any Custom Tokens used on your template to the Substitutions object in the JSON.
  4. Make sure you set a label like "test" so that you can easily clean-up test documents you create.

Your JSON might look something like this:

{
"templateId": "template-id-here",
"name": "Your Sales Doc Title",
"published": true,
"substitutions": {
"first_name": "Jane",
"company": "Acme",
"date_requested": "15th July"
},
"metadata": {},
"tags": [
"testing-qwilr-sales-doc"
]
}

This JSON has three Tokens - first_name, company, and date_requested, which will be substituted throughout the template.

If you're using Saved Blocks

  1. Create a template which might be considered a "master template" with all the relevant blocks you'll be using to assemble your final document.
  2. Insert your custom tokens throughout the template.
  3. Save each block, when tokens have been inserted.
  4. Retrieve saved block ID's
    1. For all saved blocks: using the API. retrieves a full list of blocks with block names.
    2. For a single saved block: under the Blocks primary nav item, find your saved block. Preview it, and click the three dots next to the save button.
  5. Order your saved blocks to create your document block-by-block, and include any tokens as substitutions.

Your JSON might look something like this:

{
"blocks": [
{
"id": "first-saved-block-id",
"foldable": {
"enabled": false,
"isFolded": false,
"label": "string"
}
},
{
"id": "second-saved-block-id",
"foldable": {
"enabled": false,
"isFolded": false,
"label": "string"
}
},
{
"id": "third-saved-block-id",
"foldable": {
"enabled": false,
"isFolded": false,
"label": "string"
}
},
{
"id": "fourth-saved-block-id",
"foldable": {
"enabled": true,
"isFolded": true,
"label": "string"
}
}
],
"name": "Your Sales Doc Title",
"published": true,
"substitutions": {
"first_name": "Jane",
"company": "Acme",
"date_requested": "15th July"
},
"metadata": {},
"tags": ["testing-qwilr-sales-doc"]
}

This JSON has three Tokens - first_name, company, and date_requested, which will be substituted wherever they appear in the saved blocks.

Testing

Testing page creation using Tags

When you're ready to start generating test documents, apply a tag so you can easily find + delete them from your pages list. We recommend something structured, like "test-v1" or similar, to keep things organised.

Create your page, passing in the appropriate tokens, tags, and meta-data, and generate your page.

WARNING: Do not "accept" any pages you are testing. Deleting accepted pages is not permitted, so we have a different method for testing the webhook component of integrations.

Testing page acceptance

To avoid having many "accepted" pages you can't delete, you can use the "preview eyeball" in the accept block of any page. This will take you through the same flow as accepting on the public page. You can preview accept as many times as you like and the document won't be locked.

At any point you can get this preview accept information using with the query parameter expand=previewAcceptance.

Note: Changing the number of accepters part way through the preview acceptance process will result in the incorrect value for the total number of accepters being returned. Completing the flow and starting again will return the updated value.

Testing webhooks

You can test pageAccepted webhook by completing the above preview Acceptance flow for all accepters, which will then send webhooks called pagePreviewAccepted.

Note that product meta-data in the accept webhook returns data that was received as part of page-creation with the API.

Launching your integration

When your testing is complete, and you have your final document, going live is as simple as removing your "testing" tag.