Development cycle

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 Account 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.

Developing the API request

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.

Please note: if you wish to use the quote block, the saved blocks approach must be used with the API. Some worked examples can be found here.

If you're using a template

1. Create your template, inserting Account Tokens in place of content that will be replaced by the API.
2. Grab the template ID from the URL you see when editing the template. https://app.qwilr.com/#/page/**your-template-id-here**
3. Add this under the templateId field.
4. Add any Account Tokens used on your template to the substitutions object in the JSON.
5. 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 Account Tokens throughout the template in place of content that will be replaced by the API.
3. Save each block, when tokens have been inserted.
4. Retrieve saved block ID's
   1. For all saved blocks: using the API. Get Saved Blocks 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.

Calling the API

Access token

Which user's access token for the API call is important as created pages will by default be owned by that user, with their contact details appearing in the acceptance email.

The recommended approach is to have a dedicated user for the API integration, with the name and email address you'd like to use for subsequent correspondence (e.g. a support or help desk contact). This will also allow for the details of the user to change, if required, without affecting the API integration since the access token can remain the same.

If the page owner needs to be programmatically set to another user, provide that user through the ownerId field when creating the page.

Post-accept redirect

Qwilr has a feature to redirect the buyer after they accept a proposal. The redirect URL can be customised through the API. Our customers have used this to redirect their buyers to specific areas of their website, or to their payment gateway.

Creating the page, under acceptSettings > postAcceptance you can find the post-accept options. These options, if provided, will override what's set on the template.

In addition, Qwilr will append a pageId parameter to the redirect URL, which will enable the target system to get the page details, should that be required.

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 Get Page 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.