Integrate VNTANA with Glossi

Glossi connects directly to VNTANA so a 3D asset marked ready in VNTANA is pulled into Glossi, rendered against a template, and returned to the same asset as a new version with the renders attached. Status and tag changes in VNTANA drive the workflow in both directions, so VNTANA stays the system of record throughout.

This page is the reference for teams building or operating the integration on either side.

How It Works

Glossi polls your VNTANA workspace every few minutes for assets that are ready. Nothing needs to call Glossi for the integration to work.

Polling is used rather than events because VNTANA emits webhooks for review-state changes but not for tag changes, and a tag change is what signals new work. Polling is also self-healing: a missed event cannot strand an asset, because the next sweep sees it again.

An optional webhook is available to reduce latency once VNTANA can emit an event on tag change.

The Workflow

Each row is a state Glossi watches for or writes. Tag names are configured per workspace; the values below are the ones agreed for the current integration.

Because the ready tag (GI) and the delivered tag (ACN_GI) are distinct, new work and in-flight work never collide.

Important Every tag in the table must already exist in the VNTANA workspace. Glossi applies tags but does not create them. A missing tag stops the workflow at that step with a clear error in Glossi.

Rework after a rejection

A rejection reopens the SKU in Glossi and pulls the reviewer's notes (attachment file names are listed; the files stay in VNTANA). Each connection's SKUs — states, rejection notes, and failures — are listed under the connection in Settings → Workspace → VNTANA.

Rework is started by a person, from that list, with Start rework — a rejection means the scene needs changing first, so Glossi never re-renders automatically. Starting rework applies the ACN_GI_IP tag and WAITING_REVIEW status to every scan, re-renders the SKU's project (or each scan's project, for single-product templates), and delivers the new renders as a fresh version containing only the new render package.

Asset Naming and SKU Pairing

A single product can be scanned more than once. Glossi groups scans into one SKU using the asset name, and the SKU always moves through tagging, review, and delivery as one unit.

The shared key is the name with a trailing _B removed, so VN0A5JMI_BLK and VN0A5JMI_BLK_B form one SKU.

Rules that matter in practice:

• Every scan of the SKU must arrive before production starts. Glossi counts the SKU's product records in VNTANA (Name, Name_B, Name_C, ...) — tagged or not — and waits until that many scans are tagged and in review. Create all of a SKU's records before tagging the first one; a SKU missing a sibling waits rather than rendering an incomplete product.
• Scans may arrive at different times. Glossi accumulates them across polls; they do not need to be tagged together.
• Only a trailing _B is treated as the pair suffix. A colorway code containing _B mid-name is not split.
• Per-angle AI edits ride along with the template. If a template's angles have AI edits configured in the studio (a prompt, reference image, or brand style on a bookmark), every VNTANA render of that angle is edited automatically and the edited image is delivered in the same package, on the same version, alongside the raw render. Nothing is delivered until every configured edit has finished.
• The templates decide how the SKU renders. A template whose scene stages multiple products renders every scan of the SKU together in one combined scene, and each scan receives the complete render package. A template staging a single product runs each scan through it individually — its own scene, its own renders — and each scan receives only its own renders. With multiple templates selected (up to three), each contributes its own render package and a scan receives the union of everything produced for it, delivered onto a single new version. Status and tag updates always apply to every scan together, and nothing is delivered until every render batch is done.

If a SKU waits more than 24 hours without all of its scans, Glossi raises an alert so a half-tagged product does not sit unnoticed.

Connecting a Workspace

The connection is made once, from Glossi, by a workspace admin.

1. Generate an Authentication Key in VNTANA

1. Sign in to the VNTANA platform
2. Open your profile from the upper-right corner
3. Select the Authentication Key tab
4. Choose Generate and copy the key

Important Use a shared service account rather than an individual's login. The key carries that user's workspace access and appears as that user in VNTANA's audit trail. If they leave, or generate a new key for any reason, the previous key stops working and the integration halts.

2. Add it in Glossi

1. Go to Settings → Workspace
2. Find the VNTANA section and choose Connect workspace
3. Paste the Authentication Key and select Verify key
4. Pick the VNTANA workspace to watch and up to three Glossi templates to render with — every SKU produces one render package per selected template

Important If your organization runs on a dedicated VNTANA instance (the platform URL looks like platform.yourcompany.vntana.com), fill in the optional API host field with https://api-platform.yourcompany.vntana.com before verifying. Keys from a dedicated instance are rejected by the shared VNTANA API, so without the host the key will appear invalid even though it is correct.

Glossi validates the key before storing anything and lists every VNTANA workspace it can reach, so one key can connect several workspaces without generating another.

The key is encrypted at rest and never displayed again. To replace it, paste a new one in the same section.

3. Set the export settings

The template decides what the renders look like: the angles, the backdrop, the aspect ratio, any AI edits. The connection decides what file each render becomes. Under the connection you can set:

• Format: PNG (8-bit), TIFF (16-bit, for post-production deliverables), or JPEG (maximum quality, tagged sRGB IEC61966-2.1). With JPEG, every delivered image is a JPEG, AI-edited angles included
• Resolution: 720p, 1080p, 4K, or a custom pixel size (320 to 3840 px on the longer edge)
• Post processing: Workspace default, On or Off. A photographic finishing pass applied to each PNG or JPEG after it renders; On uses more usage per image, Off delivers images as rendered. Workspace default follows the Post Processing switch under Settings → Workspace
• File names: a pattern for the delivered files, such as {Style Number}_{Color Code}_{item}

Name tokens read the VNTANA product's attributes by name (so {Style Number} uses the attribute of that name on the record receiving the file), plus {item} for the bookmark or shot the render came from, {scan} for the asset name, and {sku} for the shared SKU key. An AI-edited angle is named after its source angle with _AI appended. Leave the pattern empty to keep Glossi's own render names.

What Glossi Calls

Every request uses the workspace-scoped refresh token derived from your Authentication Key. The account behind the key needs access to each connected workspace.

Three behaviours worth knowing:

• Tag writes preserve everything else. Glossi reads the asset, changes only the tag in question, and writes the remaining fields back unchanged.
• Review status splits by direction. Moving an asset into review (WAITING_REVIEW) goes through send-for-review, with the connected account as the reviewer of record — your team assigns its real reviewers in VNTANA as usual. Decision states (APPROVED, REJECTED, CUSTOMER_*) go through reviewed-status.
• Renders are attached to a new version. Delivery creates a version with keepOriginalFile: true, so no 3D file is re-uploaded and the existing model carries forward.

Optional Webhook

Glossi exposes an endpoint VNTANA can call when an asset changes. It is not required — polling already covers the workflow — and it exists so the integration can react in seconds rather than minutes once VNTANA can emit an event on tag change.

Endpoint:

POST https://api.glossi.io/webhooks/vntana

A GET on the same URL returns a machine-readable summary of the contract below, which is useful while building.

Headers

Payload

Any event name is accepted. Only two fields are required:

{
  "event": "asset.tags.updated",
  "client": { "uuid": "vntana-workspace-uuid" },
  "product": { "uuid": "vntana-asset-uuid" }
}

Glossi uses the payload only to identify the asset, then reads that asset's current state from the VNTANA API before acting. This means the event can be named anything, extra fields are ignored, and re-delivering the same event is harmless.

Setup

1. Create a webhook in VNTANA pointing at the endpoint above
2. Copy the secret VNTANA generates for it
3. Paste that secret into Settings → Workspace → VNTANA → Webhook in Glossi

Glossi shows when the last delivery arrived, so you can confirm the connection end to end.

Responses

Glossi answers before doing any work, so a delivery never waits on rendering. Failed deliveries do not need replaying — the next poll picks up anything missed.

Verifying a signature

const crypto = require("crypto")

const signature = crypto.createHmac("sha256", webhookSecret).update(`${timestamp}#${rawBody}`).digest("hex")

Sign the raw request body. Re-serialising parsed JSON changes key order and whitespace, which changes the digest.

Troubleshooting

Errors that need attention appear against the connection in Settings → Workspace → VNTANA.