Feirawell for VTEX: setup and help

Feirawell shows your customer's VTEX orders next to their Zendesk ticket, in English, Portuguese or Spanish, and lets the agents you choose add an order note, start handling or cancel, with every action logged on the ticket. $9 per agent per month after a 14-day trial.

What you need

• Zendesk Support (any plan that allows Marketplace apps) and admin access to install.
• A VTEX account and permission to create application keys and roles in it.

Create the VTEX app key

1. VTEX admin > Account settings > Account management > Roles > New role, for example "Zendesk Feirawell". Add these License Manager resources:
   • OMS > View order and List Orders (the sidebar)
   • OMS > Change order workflow status (only if you turn on Start handling or Cancel)
   • Checkout > Orders Full Access (only if agents add order notes)
2. Application keys > Generate key, give it the role, and copy the app key and app token (VTEX shows the token once).

Install

Follow the installation guide on the listing: the account name (mystore for mystore.myvtex.com), the app key and the app token. Zendesk keeps the key and token as secure settings, inserted into request headers by Zendesk's proxy only for mystore.vtexcommercestable.com.br.

Several VTEX accounts and brands

• Account label: the name agents see (default: the account name).
• Account brands: Zendesk brand ids that open this account first.
• Accounts 2 and 3: fill in the account name to turn one on, then its own key, token, label and brands. Agents switch accounts at the top of the sidebar.

How orders are found

For each email on the requester's Zendesk profile, for each CPF or CNPJ written in the ticket (check digits validated) and for each VTEX order id in the ticket, Feirawell asks VTEX's order search, reads up to 10 candidate orders in full, and keeps an order only when its customer email or document is exactly the requester's. VTEX's search also returns near matches (another Ana Souza); those are counted and never shown. An order id from the ticket that belongs to someone else is named with a masked email so the agent can look it up on purpose.

Limits from VTEX: its search indexes new orders after about four minutes; it covers the last two years; it refuses a "+" in the search, so plus-addressed emails are skipped (the sidebar says so). Accounts with VTEX data masking hide order emails: such an order is shown only when VTEX found it by the requester's own email, with a badge.

The lookup box takes an order id, an email, a CPF or CNPJ, or a full name.

Actions

Every action shows a confirmation with exactly what will happen, then writes an internal note and a feirawell_* tag on the ticket. Who may take actions takes admin, agent (everyone), role ids, or group:<id>, separated by commas. Default: admin.

Feirawell never sends a write twice. If VTEX's answer is lost, it reads the order to see what happened; an order note (which VTEX can't read back) is reported as unconfirmed instead.

Language

Each agent sees Feirawell in their Zendesk language (Portuguese, Spanish, otherwise English). Set Language to en, pt-BR or es to fix one language for everyone. Ticket notes are written in the acting agent's language.

Troubleshooting

• 401: the key or token is wrong or revoked; create a new key and paste both.
• 403: the key's role is missing a resource above.
• 404 or "web page instead of VTEX data": the account name is wrong.
• Nothing found: see "How orders are found" for VTEX's limits; look the order up by id.

Privacy

Runs in the agent's browser; nothing stored outside Zendesk and VTEX, no export, nothing sent to Great Work. Full policy: https://greatwork.company/apps/feirawell-for-vtex/privacy.

Questions: hello@greatwork.company, a person replies within one business day.