# How to add an AI chatbot to TOTVS Protheus

> Source: https://netray.co/integrations/totvs-ai-chatbot
> Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems.
> Section: Integrations

## Short answer

Build the chatbot as a separate web or portal component that calls read-only Protheus services, answers only from returned data, and respects each user's branch and role. It can run fully on-prem with an open-weight model if data must not leave.

## System

TOTVS Protheus

## Capability

ai-chatbot

## Intro

Protheus users spend a lot of time navigating menus to answer small questions: where is my order, what is the balance of this item, which title is blocked. A chatbot is useful when it answers those directly, with the ERP record behind each answer, in the language the user speaks.

There are two audiences. Internal staff want a chat panel in an intranet page or in a TOTVS portal. Customers and suppliers want a portal widget that shows only their own orders and invoices. The second case needs stricter identity mapping than the first.

Grounding is the core of the design. The bot should fetch data through tools, show what it used, and say so when it cannot find an answer, rather than generate plausible but invented statuses.

## Use Cases

### Internal order desk assistant

**Description:** Staff ask for the status, blocks and delivery date of a sales order, and the bot returns SC5/SC6 data in a short answer with the invoice number.

### Supplier portal for PO confirmations

**Description:** Suppliers authenticate, see their open purchase order lines, and ask the bot to explain what is expected and by when.

### Customer self-service tracking

**Description:** Customers ask where their delivery is, with the bot reading the order and shipment tables for their account only.

### Procedure help for new users

**Description:** Answers how-to questions from your internal procedure documents, such as how to register a pre-note, with links to the right screen name.

### Finance Q&A

**Description:** Controllers ask for overdue titles by customer or a payment forecast for the week, using read-only SE1 and SE2 views.

## System Surface

- Read-only REST services on the application server or a gateway that wraps SQL views, as the data source for every chatbot answer.
- Protheus users and groups, and for external users a portal identity table you control, mapped to customer or supplier codes in SA1 or SA2.
- Document sources for how-to answers: procedure PDFs, wiki pages, and exported help text, indexed for retrieval.
- TOTVS Fluig or an existing intranet where a chat widget can be embedded, if your landscape has one.
- Message channels such as web chat widgets or a team chat tool as front ends, with Protheus as the system of record.

## How It Works

### Define the scope and the refusal rules

**Detail:** List the question types the bot will answer, and the ones it must decline, such as pricing for other customers or payroll.

### Expose a small tool API

**Detail:** Build endpoints for order status, stock, invoices and titles, each returning compact JSON with branch scoping and a maximum row count.

### Add retrieval for documents

**Detail:** Index procedures and product documentation in a vector store, with titles and versions, so how-to answers cite a source.

### Pick the model and run it

**Detail:** An open-weight model through vLLM or Ollama for on-prem, or an approved hosted model for non-sensitive scopes. Test in Portuguese, English and Spanish if users need them.

### Map identity

**Detail:** Resolve the logged-in user to a Protheus user or an external customer code, and inject allowed branches into every tool call server-side.

### Embed and monitor

**Detail:** Place the widget in the portal, log conversations with consent, review unanswered questions weekly, and add tools where gaps appear.

## Example Flows

### Customer asks where an order is

**Trigger:** A logged-in customer types: where is order 5120?

**Steps:**

- Bot checks that order 5120 belongs to the customer's code.
- Tool returns status, invoice and carrier data.
- Bot answers with the expected delivery and the invoice number.
- If the order is not theirs, bot says it cannot find it.

**Result:** Fewer status calls to the order desk, and no cross-customer leaks.

### New buyer asks how to enter a pre-note

**Trigger:** A buyer asks the internal bot for the process.

**Steps:**

- Bot retrieves the procedure document for pre-notes.
- It summarizes the steps and names the menu path in your Protheus.
- It links to the source page for confirmation.

**Result:** Faster onboarding with answers that come from your own procedures, not generic guesses.

## On Prem

A chatbot over Protheus can run entirely inside your network: the widget on an intranet or customer portal in a DMZ, the orchestration service and an open-weight model on local GPUs, and tool calls to Protheus over internal REST. For external customer access, keep the model and ERP internal and expose only the chat endpoint through a reverse proxy with authentication. This avoids sending customer and order data to a third-party model provider, which helps with LGPD and with customers who contractually restrict where their data is processed.

## Security

- Enforce identity and branch scoping in the tool layer, never in the prompt alone.
- Rate-limit and authenticate the chat endpoint, and block prompt content from reaching internal tools directly.
- Do not let the bot return fields outside a whitelist; redact CPF, CNPJ of others and prices not owned by the user.
- Retain conversation logs only as long as needed, with notice to users under LGPD.

## Options

### Use a chatbot module from TOTVS or its ecosystem, if licensed

**Fit:** Suitable for common FAQ and process help; check how deeply it reads your data and customizations.

**Effort:** Days to weeks, subject to licensing.

### Build an in-house bot on a framework with your REST tools

**Fit:** Fits teams that can build and maintain the tool API and the front end.

**Effort:** One to two months for internal and customer scopes.

### Partner build with a private model, such as Netray

**Fit:** Fits sites needing on-prem, multilingual answers and a controlled rollout.

**Effort:** A pilot in a few weeks, then scope expansion.

## Pitfalls

- Letting the model answer from general knowledge when a tool returns nothing, which yields confident wrong statuses.
- Using one service account for all users, so the bot cannot tell which customer is asking.
- Ignoring Portuguese status vocabulary; internal codes need readable translations in tool output.
- No feedback loop. Unanswered questions are the roadmap for new tools.
- Embedding the widget before testing prompt injection through order notes and free-text fields.

## Faq

### Can a chatbot read live Protheus data?

**Answer:** Yes, through read-only REST services or views that the bot calls as tools. It should answer only from those results and show which record it used. That keeps answers current and checkable, unlike a bot trained on a static export.

### Can customers use it?

**Answer:** Yes, with strict identity mapping. Authenticate the customer in your portal, map them to their account code, and apply that filter server-side in every tool call. Test thoroughly that one customer can never see another's orders.

### Does it need to be in Portuguese?

**Answer:** Most Protheus users will expect Portuguese, and many industrial sites also need English or Spanish. Modern open-weight models handle these, but test with your real status terms, abbreviations and mixed-language notes.

### Can it run without internet?

**Answer:** Yes. Host the model, retrieval store and orchestration on local servers, and connect to Protheus over the internal network. Updates then come through your own release process, which suits air-gapped or restricted plants.

### What stops it from making things up?

**Answer:** Design, not hope. Require tool results for ERP facts, instruct the model to say when nothing was found, cite the record fields, and test with questions whose answers you know. Review failures weekly and tighten the tools.

## Search terms

totvs protheus chatbot, ai chatbot for totvs, protheus chatbot integration, add chatbot to protheus, protheus customer portal chatbot, totvs erp virtual assistant, protheus ai assistant on-prem, chatbot protheus pedido de venda, protheus supplier portal ai, totvs protheus llm chatbot

---
Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json