User Guide

What this page is for

Creates a new Central Identity, creates the first company (tenant) linked to it, and activates a trial covering every module automatically.

Who can access this

Anyone new to Zervixo — no prior permission needed; the person who registers becomes Company Admin automatically.

Required permission

None (public page, pre-login)

Field reference

• Company name: Automatically becomes a unique subdomain, e.g. yourcompany.zervixo.com
• Full name: Your own name as the first account owner
• Email: Used for login and the verification link
• Password: Must meet a minimum complexity bar

Button reference

• Create account: Creates the Central Identity and the company together in one step, and logs you in automatically

Record states

• Email unverified (before clicking the activation link)
• Email verified (after clicking the sent activation link)

Workflow

1. Open the public registration page.
2. Enter the company name, your name, email, and a strong password.
3. Click "Create account."
4. You are logged in automatically and redirected to the dashboard.
5. Check your email and click the verification link — the welcome email only sends after this step.

Practical scenario

"Al-Asala Restaurant" registers for the first time: the owner enters the company name, personal email, and a password, and immediately gets a dedicated subdomain and an empty dashboard ready for setup, with a trial covering every module already active.

Screenshot from the live system

Common errors and how to resolve them

• I didn't receive the verification email — Check your Spam folder, or use "Resend verification link" from the account page.
• Company name already taken — Choose a different name — every company needs a unique subdomain.

What this page is for

Sets the Base Currency every journal entry and financial report is built on, regardless of any individual sale's own transaction currency.

Who can access this

Company Admin only.

Required permission

manage company settings

Field reference

• Base currency: A dropdown of available currencies (e.g. SAR, USD, EUR) — used everywhere no other currency is explicitly specified

Button reference

• Save: Saves the change immediately — there is currently no extra confirmation step even if prior transactions exist (see the errors section below)

Workflow

1. From the sidebar, open "Company Settings."
2. Choose the base currency from the dropdown.
3. Click "Save."

Practical scenario

A company that mainly deals in US Dollars changes the base currency from the default Saudi Riyal to USD before recording its first invoice — every subsequent invoice and report then displays in USD.

Screenshot from the live system

Common errors and how to resolve them

• I changed the currency after recording invoices — The system currently does not block or warn about this — change the base currency before starting any real financial activity to avoid old and new reports disagreeing (a real gap documented in the system review).

What this page is for

A branch represents a real company location (e.g. Riyadh branch); a warehouse represents a physical storage location that can be linked to a branch — every stock movement happens inside a specific warehouse.

Who can access this

Company Admin only.

Required permission

manage company settings

Field reference

• Branch name: A clear location name, shown on invoices issued from it
• Warehouse name: A clear name for the physical stock location
• Linked branch: Which branch this warehouse belongs to

Button reference

• Create new: Opens the add-branch/add-warehouse form

Workflow

1. From the sidebar, open "Branches" and create your first branch.
2. From the Inventory menu, open "Warehouses" and create one linked to the branch.

Practical scenario

A distribution company has two branches: Riyadh and Jeddah. Each has its own warehouse — a sale recorded from the Jeddah branch automatically deducts stock only from the Jeddah warehouse, never from Riyadh's.

Screenshot from the live system

Common errors and how to resolve them

• I don't see the warehouse when creating an invoice — Confirm the warehouse was actually created and that your account has access to its branch.

What this page is for

The only real path to add a user — creates a time-limited, secure invitation; no real membership exists before acceptance. If the email already has a Zervixo account, it's linked to your company without creating a duplicate identity.

Who can access this

Company Admin, or any user explicitly granted invite company users.

Required permission

manage users, invite company users, or assign company roles

Field reference

• Full name: The invitee's name
• Email: Determines whether this is a brand-new user or an existing Zervixo account holder
• Phone: Optional
• Language & timezone: Applied to the new user's account after acceptance
• Branches: Which branches they'll have access to
• Roles: One or more roles granted immediately on acceptance
• Extra permissions: Individual permissions on top of the chosen role
• Send invitation email: On by default; turn off to copy the invite link manually instead of sending
• Invitation expiry: From 1 to 30 days
• Personal message: Optional, included inside the invitation email

Button reference

• Invite teammate: Opens the full invitation form

Record states

• Pending — not yet accepted
• Accepted
• Expired
• Revoked
• Failed delivery

Workflow

1. From the "Users" page, click "Invite teammate."
2. Fill in the name, email, role, and any extra permissions.
3. Click send — a brand-new email gets an invitation email; an existing account holder sees the invitation inside their own app to accept.
4. After acceptance, the user appears in your company's list with their role and permissions immediately.

Practical scenario

The restaurant owner invites a new accountant: enters her email, picks the "Staff" role, grants only "use AI assistant," and leaves the invitation email on. She receives an email, clicks "Accept," sets a password, and immediately appears in the restaurant's user list.

Screenshot from the live system

Common errors and how to resolve them

• Duplicate invitation to the same email — The system blocks a second pending invitation to the same email in the same company — use "Resend" on the existing one instead.
• The invitation expired before acceptance — Click "Resend" from the pending invitations list — this automatically extends it 7 more days.

What this page is for

Defines a new role (e.g. "Accountant") and grants it a specific permission set, instead of manually granting every permission to every user.

Who can access this

Company Admin only.

Required permission

manage roles

Field reference

• Role name: A clear name shown when adding users
• Permissions: A multi-select list of every available permission, grouped by module

Button reference

• Create role: Opens the new-role form

Workflow

1. From "Roles & Permissions," click "Create role."
2. Type the role name.
3. Select the required permissions from the list.
4. Save — the role is now selectable when inviting or editing any user.

Practical scenario

A company creates an "Inventory Officer" role with only manage inventory — every employee given this role can view and edit inventory but cannot reach Sales or Accounting.

Screenshot from the live system

Common errors and how to resolve them

• I can't see the Roles page at all — You need the manage roles permission itself just to see this page — ask your Company Admin for it.

What this page is for

Browse available modules, see pricing and required permissions, and subscribe.

Who can access this

Company Admin only (this page was corrected during the system review — it used to be open to any authenticated user).

Required permission

manage company settings

Field reference

• Module name: A short description of what it does
• Monthly price: Shown per module before subscribing

Button reference

• Subscribe: Immediately creates a subscription, an invoice, and a trial license — activation happens before payment; the invoice remains unpaid until it's settled

Workflow

1. From "Available Modules," browse the marketplace.
2. Click "Subscribe" on the module you want.
3. It appears immediately in "Installed Modules," with a new invoice in "Invoices & Payments."

Practical scenario

A manufacturing company subscribes to the "Manufacturing" module — it appears immediately in the sidebar, and a subscription invoice arrives that can be settled via bank transfer.

Screenshot from the live system

Common errors and how to resolve them

• The module doesn't appear in the sidebar despite subscribing — Reload the page — permissions and menus refresh on each new request.

What this page is for

Upload a transfer-proof file (image or PDF) for Zervixo's team to review and confirm payment.

Who can access this

Company Admin only.

Required permission

manage company settings

Field reference

• Proof file: An image or PDF of the transfer receipt — currently the only field available (no separate amount/date/reference field exists yet — a real gap documented in the system review)

Button reference

• Upload proof: Sends the file for the platform team's review

Record states

• Pending Review
• Approved
• Rejected

Workflow

1. From "Invoices & Payments," open the due invoice.
2. Click "Upload proof."
3. Choose the transfer receipt file.
4. Wait for the platform team's review — the status updates automatically on approval or rejection.

Practical scenario

A company transfers its subscription amount by bank, photographs the transfer receipt, and uploads it against the invoice. Hours later they get notified the payment was approved and the subscription activated.

Common errors and how to resolve them

• My proof was rejected — Check the rejection reason written by the review team, and re-upload a correct proof against the same invoice.

What this page is for

Review bank-transfer proofs uploaded across all companies, approving to activate a subscription or rejecting with a clear reason.

Who can access this

Platform Super Admin only (is_staff).

Required permission

Central Admin panel access (is_staff)

Field reference

• Rejection reason: Required on rejection — shown to the company so they can correct the proof

Button reference

• Approve: Activates the subscription immediately and prevents duplicate approval of the same payment
• Reject: Requires a rejection reason before saving

Workflow

1. Open the "Payments" list in the central Admin panel.
2. Select a "Pending Review" payment.
3. Open the attached proof file and verify it.
4. Click "Approve" or "Reject" (with a written reason).

Practical scenario

The Zervixo team reviews 5 new transfer proofs each morning, opens each file, confirms the amount and bank reference, then approves the valid ones and rejects unclear ones with a reason.

Common errors and how to resolve them

• I accidentally approved the payment twice — The system explicitly blocks this — duplicate approval of the same payment is prevented.

What this page is for

Explains the license lifecycle: Trial → Active → Grace → Expired/Disabled, and guarantees no data is ever lost on expiry.

Who can access this

Company Admin (receives the alerts), and any user attempting to use the expired module.

Required permission

None — this is automatic system behavior

Record states

• Trial
• Active
• Grace
• Expired
• Disabled
• Cancelled

Workflow

1. You receive alerts at 30, 14, 7, 3, and 1 days before expiry, and on the expiry day itself.
2. On expiry, the company enters a temporary "Grace" period.
3. After that, if not renewed, the module moves to "Disabled."
4. Your existing data remains fully preserved — never deleted.
5. After renewal, the module works again immediately with all its previous data.

Practical scenario

A company's Manufacturing subscription expires without renewal. It enters Grace, then the module is disabled: users see a clear renewal message instead of a confusing error page, and every old BOM and work order remains exactly as it was.

Common errors and how to resolve them

• I see a read-only message but need to edit — This is expected during expiry — renew the subscription to restore write access. (System-review note: in some pages even reading is currently blocked too — a known, documented scope for improvement.)

What this page is for

Creates a new renewal invoice and returns the module to Active status once paid.

Who can access this

Company Admin only.

Required permission

manage company settings

Workflow

1. From "Installed Modules," open the module you want to renew.
2. Click "Renew."
3. A new renewal invoice is issued — follow the same payment-proof upload steps.
4. Once the payment is approved, the module works again immediately.

Practical scenario

7 days before the Sales module subscription expires, the admin gets an alert, clicks "Renew" directly from the same page, transfers the amount, and the module continues working without interruption.

Common errors and how to resolve them

• I renewed but the module is still disabled — Renewal creates a new invoice that must first be paid and approved — activation happens after payment approval, not at invoice creation.

What this page is for

Links your company's own merchant account to a gateway the platform has enabled, activating online payment for your customers.

Who can access this

Company Admin only.

Required permission

manage company settings

Field reference

• Gateway: Only from among the gateways the Zervixo platform has enabled
• Test/Production mode: Test or Production
• Currency: The transaction currency through this gateway

Button reference

• Test connection: Verifies the setup is correct before relying on it for real transactions

Workflow

1. From "Integrations," open "Payment Gateways."
2. Pick the gateway available to you.
3. Enter your own merchant account details for that gateway.
4. Click "Test connection" to confirm.
5. Activate it to start receiving your customers' online payments.

Practical scenario

An online store wants to accept online payments from its customers: connects its Creem account from the Integrations page, tests the connection successfully, and every invoice's payment link becomes ready to send directly to customers.

Screenshot from the live system

Common errors and how to resolve them

• 0 — Is this the same place I pay for my own Zervixo subscription?
• 1 — Not at all — this is your own gateway for your own customers, entirely separate (different tables and settings) from "Invoices & Payments" for your own Zervixo subscription.

What this page is for

Records a customer's details once, reused automatically across every future quotation and invoice for them.

Who can access this

Any user with manage sales.

Required permission

manage sales

Field reference

• Name: The customer's or company's name
• Email/phone: Contact details
• VAT number: Required if you'll issue them tax invoices later

Workflow

1. From "Sales" → "Customers," click "Create customer."
2. Enter the name, contact details, and VAT number if applicable.
3. Save.

Practical scenario

A new customer requests their first quotation — their name and VAT number are recorded once, so every future quotation and invoice for them is just one click to select from the list.

Screenshot from the live system

What this page is for

Presents a formal price offer to the customer before committing to a real sales order.

Who can access this

Any user with manage sales.

Required permission

manage sales

Field reference

• Customer: From the pre-registered list
• Line items: Products/services, quantity, price per line
• Validity: The quotation's expiry date

Button reference

• Convert to sales order: Appears only after the customer accepts — creates a real SalesOrder linked to the same line items

Workflow

1. Create the customer first if they don't exist.
2. From "Quotations," create a new one and select the customer.
3. Add line items and prices.
4. Send the quotation to the customer.
5. Upon acceptance, click "Convert to sales order."

Practical scenario

A restaurant requests a monthly-supply quotation from its supplier — a quotation is created with items and prices, the restaurant approves, and it converts automatically into a real sales order with the same data, no re-entry needed.

Screenshot from the live system

What this page is for

A real sales document that links the customer to inventory, warehouse, and branch, and generates the delivery and invoice from it later.

Who can access this

Any user with manage sales.

Required permission

manage sales

Button reference

• Confirm: Actually reserves the required stock in the chosen warehouse
• Create delivery: Appears after confirmation, creates a delivery document ready to execute

Record states

• Draft
• Confirmed
• Partially delivered
• Fully delivered
• Invoiced

Workflow

1. Create a sales order directly, or convert one from an accepted quotation.
2. Choose the warehouse it will be delivered from.
3. Click "Confirm" — stock is reserved immediately.
4. Create a delivery when ready to actually deliver.

Practical scenario

A sales order for 100 units of a product is confirmed, immediately reserving 100 units specifically from the Riyadh warehouse, so no other sales order can reserve the same quantity.

Screenshot from the live system

Common errors and how to resolve them

• I can't confirm the order — Check the requested quantity is actually available in the chosen warehouse — the system blocks over-reserving beyond available stock unless negative stock is explicitly allowed.

What this page is for

Issues a real invoice that creates a genuine debit/credit accounting entry and appears in receivables reports.

Who can access this

Any user with manage sales.

Required permission

manage sales

Field reference

• Invoiced lines: Only part of the quantity can be invoiced if delivery was partial
• Currency: Can differ from the base currency — the exchange rate at invoicing time is stored

Workflow

1. From the confirmed sales order, click "Create invoice."
2. Line items pre-fill with whatever remains un-invoiced.
3. Review VAT and the total.
4. Issue the invoice — the accounting entry is created automatically.

Practical scenario

A partial delivery of 60 out of 100 units is invoiced — the first invoice covers only the 60, and the remaining 40 stays invoiceable later once delivery is completed.

Screenshot from the live system

What this page is for

Closes the invoice fully or partially based on the actual amount paid, and automatically updates the remaining balance.

Who can access this

Any user with manage sales.

Required permission

manage sales

Field reference

• Amount: Can be partial if paid in installments
• Payment method: Cash, transfer, card, etc.

Workflow

1. From the invoice, click "Record payment."
2. Enter the actual amount paid and the payment method.
3. Save — "remaining amount" updates automatically, and the invoice becomes "fully paid" once the remainder reaches zero.

Practical scenario

A 1,000 SAR invoice, the customer pays only 600 first — the payment is recorded, "remaining: 400 SAR" shows, until a second payment fully closes the invoice.

What this page is for

Generates a unique UUID, a hash chain, a QR code, and an XAdES-B digital signature for every tax invoice, then submits it to ZATCA.

Who can access this

Any user with sales-invoicing permission, provided ZATCA integration is enabled for the company.

Required permission

manage sales + ZATCA integration enabled

Workflow

1. Issue a normal sales invoice first.
2. A UUID, QR code, and digital signature are generated automatically for it.
3. The invoice is submitted to ZATCA (Clearance or Reporting depending on invoice type).
4. ZATCA's response is stored alongside the invoice for audit.

Practical scenario

A retail shop issues a Simplified invoice to a walk-in customer — it's automatically submitted as "Reporting" to ZATCA within the allowed window, and a QR code appears ready to print on the paper receipt.

Note: this part is currently blocked in this guide because it needs real third-party access (not because the feature is missing) — see the accompanying report for the exact status.

Common errors and how to resolve them

• The invoice is stuck "submitting" for a long time — It automatically retries with increasing delays (10, 30, 60, 300, 900 seconds) up to 5 times — check the error log if the issue persists.

What this page is for

A formal purchase document specifying supplier, items, quantities, and prices, going through a real approval chain before it can be received.

Who can access this

Any user with manage purchases.

Required permission

manage purchases

Button reference

• Approve: First verifies the current user is actually authorized to decide, per the configured approval chain

Record states

• Draft
• Pending approval
• Approved
• Partially received
• Fully received
• Billed

Workflow

1. Create the supplier first if they don't exist.
2. Create a purchase order directly, or convert one from an approved internal purchase request.
3. Send it for approval per the company's configured approval chain.
4. Once approved, it's ready for a goods receipt.

Practical scenario

A purchasing officer creates a purchase order for 500 units of raw material, automatically routed to their manager for approval per the approval chain, and it cannot become a goods receipt before that approval.

Screenshot from the live system

Common errors and how to resolve them

• I can't approve the order even though I'm a manager — Authorization is checked against the approval chain configured specifically for this document type — confirm you're actually added as an approver on that specific chain.

What this page is for

Genuinely increases stock balance on receipt confirmation, supporting partial receipt across multiple batches.

Who can access this

Any user with manage purchases.

Required permission

manage purchases

Field reference

• Received quantity: Can be less than what was ordered (partial receipt is allowed)
• Rejected/damaged quantity: Excluded from the good quantity added to stock
• Warehouse: Chosen specifically at receipt time, not when the purchase order was created

Workflow

1. From the approved purchase order, click "Create receipt."
2. Choose the warehouse receiving the goods.
3. Enter the quantity actually received (and rejected, if any).
4. Click "Confirm" — stock balance increases immediately.

Practical scenario

A 500-unit purchase order arrives with only 300 in the first batch — a partial receipt of 300 is recorded, stock genuinely increases by 300, and the purchase order stays "partially received" until the remaining 200 arrive.

Screenshot from the live system

Common errors and how to resolve them

• Stock increased twice for the same receipt — Structurally not possible — every stock change goes exclusively through one responsible service that prevents direct writes or duplication.

What this page is for

Defines how Zervixo reads a custom API and which request is responsible for listing, creating, updating, or deleting each data type.

Who can access this

A Company Admin with permission to manage company settings.

Required permission

manage company settings

Field reference

• Request purpose: Defines what the request does, its direction, and when it is used. Example: Products — List with GET imports products, while Products — Update with PUT/PATCH sends a supported update.
• Field mapping: Comes after choosing the purpose and defines how values move inside the request. Example: data.items[*].sku → SKU and data.items[*].price → selling price; it does not by itself decide when the request runs.
• External field path: Where the value lives in the JSON response, such as data.items[*].id.
• Zervixo field: The matching internal field where that value is stored.

Button reference

• Test connection: Checks only the URL and authentication; it does not activate synchronization.
• Save and suggest fields: After choosing the purpose, saves it and analyzes JSON to suggest several mappings; for example, sku → SKU and price → selling price.
• Add a mapping: Manually completes a field missing from suggestions; for example, data.items[*].barcode → product barcode, without changing the purpose.
• Activate connection and sync: Starts synchronization after at least one enabled request is assigned a purpose.

Workflow

1. Enter connection details, click Test connection, then create the connection.
2. Upload a Postman/OpenAPI file or create requests manually.
3. Review every request purpose; list, create, update, and delete are independent operations with separate requests and purposes.
4. Test the request to capture a response, then click Save and suggest fields.
5. Review suggestions and add missing mappings with Add a mapping.
6. Activate the connection and synchronization when the required requests are ready.

Practical scenario

A Postman file contains List Products and Create Order: the system usually recognizes both purposes from their names and suggests product fields when a JSON example exists; the admin reviews suggestions and manually adds missing fields before activation.

Common errors and how to resolve them

• Connection test passed but activation does not work — The test proves only URL reachability and authentication. Assign at least one enabled request to a synchronization purpose first.
• Is mapping fully automatic? — It is suggested automatically when the request name is clear and a response example exists, but purposes and fields must be reviewed before activation.

What this page is for

Establishes a secure, encrypted connection between your Zid store and your Zervixo account, enabling product import and order receipt later.

Who can access this

Company Admin only.

Required permission

manage company settings

Field reference

• Connection status: Connected / Not connected / Error
• Last sync: Time of the last successful sync

Button reference

• Connect Zid: Opens Zid's own official login page to grant permission (OAuth) — no password is ever entered inside Zervixo itself
• Disconnect: Revokes the granted permission

Workflow

1. From "Integrations" → "E-commerce Platforms," click "Connect Zid."
2. Log into Zid and approve the requested permissions.
3. You're redirected back to Zervixo and the connection status shows "Connected."

Practical scenario

An online store wants to connect Zid: clicks "Connect Zid," logs in through Zid's own window, approves the permissions, and returns to Zervixo with the store now connected.

Note: this part is currently blocked in this guide because it needs real third-party access (not because the feature is missing) — see the accompanying report for the exact status.

Common errors and how to resolve them

• Connection status shows "Error" — Check the error log on the same page — the common cause is the granted permission expiring, which requires reconnecting.

What this page is for

Syncs Zid store products into Zervixo's own product catalog, enabling them to be linked to inventory and sales operations.

Who can access this

Company Admin only.

Required permission

manage company settings

Button reference

• Sync now: Starts pulling products from Zid

Workflow

1. After connecting the store, sync starts automatically per your Sync Policy (every 15 minutes by default), or click "Sync now" for an immediate sync.
2. Every new Zid product creates a real product in Zervixo's Inventory catalog, with its name, price, category, and quantity.
3. If a product's SKU coming from Zid matches an already-existing product with no prior link, it's turned into a mapping conflict instead of a duplicate (see the Resolving Mapping Conflicts article).

Practical scenario

A store with 200 products on Zid connects its account — the first sync creates 200 real products in the Zervixo catalog with the same names, prices, and quantities.

Note: this part is currently blocked in this guide because it needs real third-party access (not because the feature is missing) — see the accompanying report for the exact status.

Common errors and how to resolve them

• A product arrives from Zid with no SKU — It gets an automatic SKU in the form "zid-{product id}" instead of being left blank.
• An existing product's SKU didn't change after syncing — Deliberate — SKU is never overwritten on later syncs, so it can't undo a manual correction you made yourself.

What this page is for

Receives a webhook notification the moment a Zid order arrives, and checks it isn't a duplicate before processing.

Who can access this

Fully automatic — no direct user action.

Required permission

None (background process)

Workflow

1. A new order arrives on your Zid store.
2. Zid sends Zervixo a webhook notification immediately.
3. The system checks this event hasn't already been processed (duplicate prevention).
4. The order creates a real sales order in Zervixo, always in "Draft" status regardless of the order's own status on Zid.

Practical scenario

A customer buys from your Zid store — Zervixo receives an instant notification, and a real sales order with the same line items is created in Draft status, ready for you to review before confirming it.

Note: this part is currently blocked in this guide because it needs real third-party access (not because the feature is missing) — see the accompanying report for the exact status.

Common errors and how to resolve them

• Why is the order "Draft" in Zervixo even though it's confirmed on Zid? — Deliberate — the system never auto-maps Zid's own status onto Zervixo's status (which affects stock reservation and accounting), since that's a sensitive decision left to your review.
• A line item has no linked product — If the product isn't linked yet (a pending mapping conflict), the line is created with no specific product — link the product first from the Mapping Conflicts page.

What this page is for

Ensures the quantity shown on Zid matches the real Zervixo stock quantity after every sale.

Who can access this

Fully automatic.

Required permission

None

Workflow

1. Zervixo syncs stock quantity from Zid periodically per your Sync Policy (separate from order sync).
2. It reads the quantity reported by Zid and computes the difference against the current Zervixo balance.
3. The difference is applied through the exact same service responsible for every other stock movement, creating a real, reviewable stock movement — not a silent number change.

Practical scenario

Zid reports a product balance changed to 45 from 50 — Zervixo creates a real stock movement deducting 5 units from the integration's configured default warehouse.

Note: this part is currently blocked in this guide because it needs real third-party access (not because the feature is missing) — see the accompanying report for the exact status.

Common errors and how to resolve them

• Stock isn't updating despite sales on Zid — Confirm a default warehouse is configured for the integration, and that the Inventory sync policy is enabled (not set to manual-only) on the Sync Policy page.

What this page is for

Clarifies the current sync direction limit so a merchant isn't caught off guard selling a quantity that isn't actually available through Zid.

Who can access this

Any merchant selling the same product both from their physical branch and their Zid store.

Required permission

None (system behavior)

Workflow

1. You sell a product directly at the branch, or through a sales order inside Zervixo.
2. Stock inside Zervixo is deducted immediately and correctly.
3. The quantity shown on the Zid store itself does not update automatically -- because exporting from Zervixo to Zid isn't supported today.

Practical scenario

A product's last unit sells directly at the branch -- its Zervixo balance immediately hits zero, but it stays showing as available on the Zid store until you manually update it on Zid itself, or it's actually ordered through Zid and the mismatch is discovered.

Common errors and how to resolve them

• I sold the last unit at the branch and then got a Zid order for the same product — Monitor this manually today for products you sell both at the branch and on Zid -- update the quantity on Zid by hand until automatic export is supported.

What this page is for

Browse every module available in the marketplace (core or third-party) with pricing and ratings, before subscribing.

Who can access this

Company Admin only.

Required permission

manage company settings

Workflow

1. From "Marketplace," browse every module organized by category.
2. Open any module to see its description, price, and rating.
3. Click "Subscribe" — see the "Subscribing to a module" scenario for full detail.

Practical scenario

A company browses the marketplace looking for a new integration module, compares two options by rating and price, and subscribes to the best fit.

Screenshot from the live system

What this page is for

Sends metadata about a proposed module (name, description, repository link) for the team's review — this is currently a metadata-only page, not a code-upload or execution platform.

Who can access this

Any user — no special permission is currently required just to submit.

Required permission

No dedicated permission currently exists

Field reference

• Developer name: Your name or company name
• Email: For communication about the review status
• Module name: The proposed module's name
• Description: What the module does
• Repository URL: A link to the source code for review

Button reference

• Submit for review: Creates a submission record with status "Pending Review"

Workflow

1. From "Developer Apps," fill in the proposed module's details.
2. Click "Submit for review."
3. Wait for the Zervixo team's response.

Practical scenario

An independent developer wants to sell a shipping-service integration — fills the form with their module's details, submits it, and waits for the team's review.

Screenshot from the live system

Common errors and how to resolve them

• Where do I actually upload my module's code? — There currently isn't one — this is a metadata-only form (name, description, repo link), not a code-upload or automated-publishing platform. A real developer account with login, payout details, and version uploads doesn't exist yet, and is clearly documented in the system review report.

What this page is for

Reviews developer submissions, approving (which immediately creates a real module catalog entry in the marketplace) or rejecting with a clear reason.

Who can access this

Platform Super Admin only (is_staff).

Required permission

Central Admin panel access (is_staff)

Button reference

• Approve: Immediately creates a real module in the marketplace catalog — metadata review only, the developer's code is never executed
• Reject: Requires a written rejection reason

Workflow

1. From the central Admin panel, open "Module Submissions."
2. Review the submitted module's details and repository link.
3. Click "Approve" (it appears in the marketplace immediately) or "Reject" with a reason.

Practical scenario

The Zervixo team reviews a developer's new module submission, confirms the description is clear and the link is reasonable, then approves it — the module appears immediately in every company's marketplace.

Common errors and how to resolve them

• I approved the module — does that mean its code is now running? — No — approval here is metadata review and catalog publishing only. There is currently no execution environment or automated security scan for the developer's actual code.

What this page is for

Registers a WhatsApp Business number as a channel, so every message a customer sends to that number becomes a conversation that appears automatically in the inbox.

Who can access this

Any user with the "Manage communication channels" permission.

Required permission

communication_hub.channels.manage

Field reference

• Name: An internal label to tell the channel apart -- customers never see it
• Phone Number ID: Your WhatsApp Business account's phone number identifier from Meta -- the system does not issue this
• Access Token: A permanent access token from that same Meta account
• Webhook Verify Token: A string you choose yourself, used later when registering the webhook in Meta
• Default channel: Check this if it is the first channel you are connecting

Workflow

1. Before you start: get a Phone Number ID and a permanent Access Token from your Meta WhatsApp Business account.
2. From Communication Hub, open "Channels" then "New Channel."
3. Enter the name, Phone Number ID, and Access Token.
4. Choose your own Webhook Verify Token.
5. Enable "Default channel" if needed, and save.
6. Back in Meta's WhatsApp app settings, register the webhook URL using that exact same verify token.

Practical scenario

A beauty salon wants to take bookings over WhatsApp: the owner gets a Phone Number ID and Access Token from their WhatsApp Business account, links them in Communication Hub, registers the webhook in Meta, and from then on any customer message to that number appears immediately in the inbox.

Common errors and how to resolve them

• Webhook verification fails in Meta — Confirm the verify token registered in Meta matches the one you entered on the channel, character for character.
• "Channel limit reached" — Your current plan has hit its allowed channel count.

What this page is for

Opens a new inbound conversation from an already-connected channel and replies to it directly from the same screen.

Who can access this

Any user with the "View the communication inbox" and "Reply to conversations" permissions.

Required permission

communication_hub.inbox.view, communication_hub.conversations.reply

Button reference

• Send: Sends your reply to the customer through the same channel immediately
• Change status: Updates the conversation status (open/pending/resolved/closed/snoozed)

Record states

• Open -- the default status for a brand-new inbound conversation
• Pending
• Resolved
• Closed
• Snoozed

Workflow

1. After connecting a channel (see the WhatsApp channel scenario), wait for a real customer message, or have someone test the number.
2. Open "Conversations" from Communication Hub -- the new conversation appears at the top of the list.
3. Click it to view the message.
4. Type your reply in the message box and click send.
5. Update the status to "Resolved" once it is settled, or leave it "Open" if follow-up continues.

Practical scenario

A customer sends "Do you deliver today?" to a restaurant's connected WhatsApp number: the message appears immediately as a new "Open" conversation, the assigned staff member opens it and replies "Yes, until 11pm," and the conversation stays open until the customer confirms their order.

Common errors and how to resolve them

• No new messages appear even though the channel is connected — Confirm the webhook is registered and healthy in Meta's settings (see the channel connection scenario), and that the channel's health status is good.
• "More than 24 hours since this contact last messaged you" — A real WhatsApp-side restriction -- past 24 hours since the last inbound message, only a pre-approved template message can be sent, not a plain reply.

What this page is for

Sends an approved WhatsApp template to a group of customers at once, showing the real recipient count before sending and tracking each message afterward.

Who can access this

Any user with the "Manage campaigns" permission.

Required permission

communication_hub.campaigns.manage

Field reference

• Channel: The connected WhatsApp number the campaign sends from
• Segment: The targeted group of customers
• Template: Only Meta-approved templates on this channel are offered
• Template variables: Comma-separated values, in the same order as the template's {{1}}, {{2}}, ... placeholders -- a comma inside one value (e.g. a date written "16 September, 2026") is wrongly counted as two separate values

Button reference

• Send Now: Asks for confirmation, showing the real count of eligible recipients before actually sending

Record states

• Draft
• Sending
• Completed
• Cancelled

Workflow

1. Create a customer segment, or use an existing one (see the Segments page).
2. From Campaigns, click "Add campaign".
3. Pick the channel, the segment, and an approved template.
4. Type the template's variable values comma-separated, in the exact same order as the template.
5. Check the "estimated eligible recipients" count shown below the segment field.
6. Save the campaign, then click "Send Now" and confirm.
7. Watch the Sent/Delivered/Read/Failed columns on the campaigns list -- they update automatically as status updates arrive from Meta.

Practical scenario

A small shop owner wants to confirm recent orders with customers over WhatsApp: he builds a segment of last week's customers, picks the approved "order confirmation" template, fills in the customer name, order number, and delivery date (in a comma-free format like 2026-09-16), clicks Send Now, and watches each message move from Sent to Delivered to Read.

Common errors and how to resolve them

• The campaign ended "Failed" for every recipient with a parameter-count error — A variable value containing a comma (e.g. a date written "16 September, 2026") was split into two values, so the count no longer matched the template -- resend using a comma-free format inside each value.
• The eligible-recipient count is lower than the segment's member count — A segment member only counts as "eligible" if they are registered with a WhatsApp identity on the exact channel the campaign uses -- see the Segments page.

What this page is for

Creates a message template from a ready-made blueprint, submits it for Meta's review, and tracks its status until approved, before it can be used in any campaign or automation.

Who can access this

Any user with the "Manage templates" permission.

Required permission

communication_hub.templates.manage

Button reference

• Use template: From the Template Library -- creates a draft with its variable count auto-derived from the blueprint's text
• Submit to Meta: From the Templates page -- actually sends the draft for review, which can take minutes to hours
• Sync from Meta: Pulls the current real status from your WhatsApp Business account

Record states

• Draft -- not submitted yet
• Pending review
• Approved -- now usable in Campaigns and Automations
• Rejected -- Meta's real rejection reason shows on hover over the status

Workflow

1. From the Template Library, pick a blueprint, its category (Utility/Marketing/Authentication), and a language, then click "Use template" -- this creates a draft.
2. From the Templates page, open the draft and review its text and variable count.
3. Click "Submit to Meta".
4. Later, use "Sync from Meta" to pull its real current status.
5. Once "Approved", the template becomes selectable when building a Campaign or an Automation.

Practical scenario

A business wants a real order-confirmation template: they pick the "order confirmation" blueprint from the Template Library with the Utility category in English, review the draft, submit it to Meta, and after a while use "Sync from Meta" to find its status is now "Approved" -- it now appears in the list of templates available when building a campaign.

Common errors and how to resolve them

• Submitting an "Authentication"-category template fails with a permission error from Meta — A genuine external Meta restriction -- Zervixo's Meta app does not yet have that specific category's permission grant, and this does not affect the Utility or Marketing categories, which submit normally.
• A template shows "Rejected" and I don't know why — Hover over the status badge on the templates list to see Meta's real rejection reason.

What this page is for

Checks sales invoices once a day and automatically sends a WhatsApp message for any invoice that is one day past its due date and not yet paid.

Who can access this

Any user with the "Manage automations" permission.

Required permission

communication_hub.automations.manage

Field reference

• Triggering record: Invoice
• When: Date reached
• Date field: The invoice's due date
• Offset in days: 1 -- meaning one day after the due date
• Conditions: Invoice status is not equal to "paid"
• Contact field: customer.phone -- reaches the invoice's customer's phone number through the relation
• Template variables: e.g. customer.name, invoice_number, total -- in the same order as the template's variables

Workflow

1. From Automations, click "Add automation".
2. Choose the triggering record: Invoice, and the event: "Date reached".
3. Set the date field to the due date, and the offset to 1.
4. Add a condition: status is not equal to "paid".
5. Pick the channel and a suitable approved (Utility) template.
6. Set the contact field to customer.phone.
7. Enter the template variables in the template's own order, e.g. customer.name, invoice_number, total.
8. Enable the automation and save.

Practical scenario

A customer's invoice becomes one day overdue overnight: the automation's daily check picks it up the next morning automatically and sends the customer a WhatsApp message reminding them by name, invoice number, and amount due -- with no action from the sales team.

Common errors and how to resolve them

• The automation is enabled but the customer received nothing — The customer's phone number must already be stored in full international format (e.g. 9665XXXXXXXX); a local-format number (starting with 0) now fails with a clear error in the automation log instead of silently sending to the wrong number, but it still will not reach the customer until the record is stored in international format.
• The automation never creates any send record at all — Check the Automation Log to see whether the conditions actually matched this invoice.

What this page is for

Shows that AI replies to product questions are genuinely grounded in the company's live inventory data, not a guess or general knowledge.

Who can access this

Any company that has enabled Smart Reply (see the AI Settings article) via the "Manage AI" permission.

Required permission

communication_hub.ai.manage

Workflow

1. Enable Smart Reply from its settings, with "Search active products", "Show sale prices", and "Show availability" turned on.
2. Set the channel's mode to AI or Hybrid.
3. From then on, any customer product question is answered automatically from real inventory data.

Practical scenario

A customer asks in Arabic: "Do you have divided paper plates available now, and what's the price?" -- Smart Reply answers with the product's real stored price and clearly states it is currently out of stock, because that is genuinely the product's status in the company's data. A different customer asks about a product the company doesn't sell at all -- Smart Reply clearly says it isn't carried and suggests a real product that actually exists instead of inventing one.

Common errors and how to resolve them

• Can Smart Reply invent a price or availability? — No -- it is explicitly instructed to be read-only and to rely only on real inventory data; if it isn't confident in an answer, it hands the conversation off to a human instead of guessing.
• A customer asked about a product that doesn't exist and got a different product back — Deliberate behavior -- when the requested product isn't carried, Smart Reply suggests a real alternative from the actual catalog instead of a dead-end reply.

What this page is for

Automatically links a new WhatsApp contact to an existing customer or lead record by matching their phone number, with no manual step.

Who can access this

Any user with the "View the communication inbox" permission.

Required permission

communication_hub.inbox.view

Workflow

1. A customer sends their first message to a connected WhatsApp number.
2. The system compares the last 8 digits of their phone number against existing customer records, then lead records -- regardless of whether either side stores a leading 0 or a full country code.
3. If exactly one record matches, the contact is linked to it automatically and customer context appears next to the conversation.
4. If nothing matches, a new lead is created automatically and linked.

Practical scenario

An existing customer, whose record has a phone number starting with a leading 0 (like 05xxxxxxxx), messages the company's WhatsApp number for the first time from that same number but in international format (966xxxxxxxxx): Communication Hub recognizes the last 8 digits match and links the conversation to that customer record automatically. But if that same number happens to be recorded on more than one customer record by mistake, the system deliberately leaves the contact unlinked rather than guessing -- which is exactly what happened in a real test environment where one phone number was duplicated across two different customer records.

Common errors and how to resolve them

• No customer context appears next to the conversation — Means the number either matched no customer/lead record, or matched more than one and was deliberately left unlinked to avoid a wrong guess. There is currently no manual-linking tool in the Communication Hub interface or on the customer/lead screen -- the real fix is correcting the duplicate data on the customer records themselves (e.g. consolidating the repeated number onto one record).
• Two different customers get wrongly linked to the same conversation — Not structurally possible -- the contact's display name is only ever used to show it; the actual linking relies exclusively on the phone number.