Integration via URL

Open the editor with a plain link to the TronDesigner Integration Site — a page hosted by TronDesigner that loads the integration script and opens the editor for you. Use it where you can't add JavaScript: e-mails, ERP or CRM screens, QR codes, server-side redirects.

TIP

Example: URL Integration · source

How it works

	Production	Development
Integration Site	https://integration.trondesigner.com	https://integration-dev.trondesigner.com

The customer opens a link such as https://integration.trondesigner.com/editor?apiKey=…&…. The page reads the query string, builds EditorArguments from it and opens the editor as a full-page dialog. When the editor closes, the page opens the link's returnUrl (token links only) or shows This window can be closed now.

There are three ways to put the configuration into the link:

Format	The link contains	Use it for
Simple parameters	API key and a few codes	Catalog products, product models, existing print jobs.
Full JSON	API key and a URL-encoded EditorArguments JSON	Anything the editor arguments support.
Token	Only a signed token	Links created by your server; the configuration can't be read or changed in the URL.

The link runs in the customer's browser outside your site, so you don't receive browser events. Use webhooks and the REST API to get the result — see Get the result back.

Choose the API key

The simple and JSON formats take a website integration API key in apiKey. Because the editor runs on the Integration Site, the API checks the Integration Site's host name against the key:

• add integration.trondesigner.com to the key's allowed domains (Admin Portal → Settings → API Keys → Website Integration API Keys), or
• use your instance's key tagged Integration Site in that list, if it exists.

The key is visible in the link, like it is in your web pages. Never put a REST API key into a link.

Simple parameters

Append parameters to https://integration.trondesigner.com/editor. Names are case-sensitive; URL-encode the values (Left chest → Left%20chest).

Exact product

https://integration.trondesigner.com/editor?apiKey={API_KEY}&supplierCode=PFC&productCodes=10086021&positionCodes=front&technologyCodes=PAD03

Product model

https://integration.trondesigner.com/editor?apiKey={API_KEY}&supplierCode=PFC&modelCode=100860

Existing print job

https://integration.trondesigner.com/editor?apiKey={API_KEY}&printJobGuid={PRINT_JOB_GUID}&openMode=Edit

Parameter	Value
apiKey	Website integration API key. Required.
supplierCode	Supplier code from Admin Portal → Settings → Suppliers, e.g. PFC.
productCodes	A product variant code. Repeat the parameter for several variants: productCodes=A&productCodes=B.
modelCode	A product model code. The customer chooses the variants (Partial data mode); productCodes then preselect variants.
positionCodes	A print position code. Repeat for several print options.
technologyCodes	A print technology code, paired with positionCodes by order. Both must occur the same number of times.
printJobGuid	GUID of an existing print job.
openMode	Edit or View (default) — used with printJobGuid.
showSelectedVariants, showSelectedPrintOptions	None (default), Selected, All or Missing — see Editor arguments. Used with the product parameters.
showQuantityInputs, alwaysShowImageSelect	true to turn the option on — see EditorOptions. Used with the product parameters.
customerIdentity	Your ID of the customer, like data-td-customer-identity in Loading the integration script.

The page uses the first combination that applies:

1. options (see below), if it contains valid JSON.
2. printJobGuid, with openMode.
3. supplierCode + modelCode — Partial data mode, with optional productCodes, positionCodes and technologyCodes.
4. supplierCode + productCodes + positionCodes + technologyCodes — Exact data mode.

If positionCodes and technologyCodes occur a different number of times, the editor doesn't open (the browser console shows Position codes and technology codes must have the same length). There is no dataMode parameter — the data mode follows from the parameters you use.

Full JSON in options

Pass a complete EditorArguments object as URL-encoded JSON in the options parameter. Everything the editor arguments support works here, including custom properties, order data and the result action:

const args = {
  openMode: 'Create',
  dataMode: 'Exact',
  editorOptions: { showSelectedVariants: 'None', showSelectedPrintOptions: 'None' },
  printJob: {
    addProducts: { supplierCode: 'PFC', variants: [{ productCode: '10086021' }] },
    addPrintings: [{ printPositionCode: 'front', printTechnologyCode: 'PAD03' }],
    customer: { orderCode: 'SO-2026-0042' },
    customProperties: { cartItemId: '4711' },
  },
  editor: { result: { resultAction: 'Dialog', redirectUrl: 'https://shop.example.com/cart', closeDialog: [] } },
};

const url = new URL('https://integration.trondesigner.com/editor');
url.searchParams.set('apiKey', '{API_KEY}');
url.searchParams.set('options', JSON.stringify(args)); // URLSearchParams encodes the JSON
console.log(url.toString());

• The JSON is readable and editable by anyone who has the link. Don't put data in it that the customer must not change.
• Long configurations make long URLs. Browsers, e-mail clients and servers limit URL length; for large payloads use a token link instead.
• If the JSON can't be parsed, the page ignores options and falls back to the other parameters.

The Admin Portal uses this format too: Generate Editor Link on a print job's detail page creates an options link that opens the print job in Edit mode.

Token links generated by your server

Your server sends the configuration to the REST API and gets back a link that contains only a signed token. The configuration and the API key are stored by TronDesigner.

curl -X POST "https://api-v1.trondesigner.com/api/integration-site-links/generate-open-editor-link" \
  -H "Authorization: Bearer {REST_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "options": {
      "openMode": "Create",
      "dataMode": "Exact",
      "editorOptions": { "showSelectedVariants": "None", "showSelectedPrintOptions": "None" },
      "printJob": {
        "addProducts": { "supplierCode": "PFC", "variants": [{ "productCode": "10086021" }] },
        "addPrintings": [{ "printPositionCode": "front", "printTechnologyCode": "PAD03" }]
      }
    },
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Response:

{
  "linkToken": "eyJhbGciOiJIUzI1NiIs…",
  "link": "https://integration.trondesigner.com/?token=eyJhbGciOiJIUzI1NiIs…"
}

Send the customer to link.

• Authentication: a REST API key (Settings → API Keys → REST API Keys) in the Authorization: Bearer header. The license must include API Automation.
• apiKey (optional): the website integration API key the Integration Site uses for this link. It must belong to the same instance. Without it, the key tagged Integration Site is used; if there is none, the request fails.
• expiresAt (optional): ISO 8601 date and time. The link can be opened any number of times until then; without expiresAt it doesn't expire. Set it for links you send out, so that old links stop working. An expired or invalid token shows Link is no longer valid.
• returnUrl (optional): an absolute https (or http) URL. The Integration Site opens it when the editor closes, for any close reason. Other schemes are rejected with a validation error.

options takes the same structure as EditorArguments, so everything the editor arguments support works in token links too — result action and buttons (editor), customer and order data, custom properties, logos, printing display names and own-product data. editor.result.redirectUrl must be an absolute http(s) URL. The full request schema is in Swagger.

printJob.customer is also used for the editor session: the Integration Site opens the editor for the customer with that customerIdentity (and name, company and e-mail), like the data-td-customer-* attributes in Loading the integration script, so the customer sees their logos.

NOTE

Older requests that put customer next to printJob, or printing overrides (printPositionName, …), still work: TronDesigner moves these values to printJob.customer and the printing's *Display* fields. Use the new fields in new code.

Get the result back

When the customer saves, a print job is created as usual, but your page isn't involved:

• Receive the print job on your server with webhooks, then download what you need with the REST API.
• To match print jobs to your records, pass customerIdentity (simple format), or printJob.customer and printJob.customProperties in the options JSON. See Customers and orders.
• To bring the customer back to your site after they confirm, use the options format with editor.result set to Dialog, a redirectUrl and, optionally, closeDialog (without it the built-in texts are shown) — see Result actions.

See also

• Integration concepts — how URL integration compares with the integration script
• Editor arguments — the options structure
• EditorArguments — API reference
• REST API · Webhooks