How to automate email into TOTVS Protheus
Short answer
Read the shared mailboxes with a service, classify each message, extract the structured data and post it into Protheus through ExecAuto or custom routines such as pre-invoice entry, quotation updates or delivery date changes. Anything below a confidence threshold goes to a review queue instead of the ledger.
In Protheus environments, a surprising amount of purchasing and receiving still starts as email. Suppliers send the NF-e XML and PDF to a mailbox, quotation replies come back as attachments, and confirmation emails contain a date that somebody types into the order.
Brazil's fiscal model helps here: the NF-e XML is structured and carries the access key, so much of invoice capture is parsing, not guessing. The messy parts are everything around it: matching to the right purchase order, handling emails with several attachments, and non-fiscal documents.
Email automation here is about removing retyping at the edges of Protheus while keeping its rules in charge of what actually posts.
What teams use it for
Supplier NF-e XML into pre-invoice entry
Parse the XML from a fiscal mailbox, match to the purchase order by supplier and items, and create the pre-nota for the warehouse to complete, instead of keying lines by hand.
Quotation replies into the quotation map
Replies to an RFQ with prices in the body or a spreadsheet are parsed into quotation lines (SC8) so the buyer compares offers in Protheus rather than in Excel.
Delivery date changes from supplier emails
Detect a revised date in a reply, link it to the order line, and propose the change to the buyer with the original message attached.
Customer purchase orders to sales orders
Customer POs arriving as PDF or spreadsheet are matched to customer and item codes and drafted as sales orders for review by the order desk.
Fiscal and certificate attachments filing
Certificates, test reports and delivery notes are attached to the receiving record so the quality team finds them in one place.
TOTVS Protheus integration surface
- ExecAuto routines for pre-invoice and invoice entry (MATA140 and MATA103 family), purchase orders (MATA120), and sales orders (MATA410), applying business rules on write.
- Protheus REST services for lookups: supplier by tax id on SA2, product cross-reference, open purchase orders on SC7 by supplier.
- Fiscal document handling through TOTVS fiscal components and the TSS service for NF-e status, where the installation uses them, plus SEFAZ status for validation.
- Document attachment (banco de conhecimento) mechanisms in Protheus for linking files to records, with exact structures varying by release.
- User exits and workflow e-mail classes for outbound messages, and standard mail configuration in the AppServer for sending.
How it works
- 1
Connect to the mailboxes
Use Microsoft Graph, IMAP or Gmail API with a dedicated service account, reading only specific folders. Mark processed messages so nothing runs twice.
- 2
Classify the message
Decide whether it is an invoice, a quotation reply, a confirmation or noise. Simple rules handle XML attachments; a language model helps with free-text replies.
- 3
Extract the data
Parse NF-e XML deterministically. For PDFs and body text use extraction with field-level confidence, and keep the source text next to each field.
- 4
Match to Protheus master data
Resolve supplier by tax id, items by supplier code or product cross-reference, and the purchase order by number or by supplier and amounts within tolerance.
- 5
Post through ExecAuto or queue for review
High-confidence matches are drafted as pre-invoices; the rest wait in a review screen. Never post final fiscal entries without the normal validations.
- 6
Close the loop
Reply to the sender where useful, and store the original email with the Protheus document for audit.
Example flows
NF-e XML arrives in the fiscal mailbox
Trigger: A supplier emails the XML and PDF for a delivered order.
- Service extracts the XML and verifies the access key format and, optionally, its status.
- It looks up the supplier by CNPJ and the open order on SC7.
- A pre-invoice is drafted through ExecAuto with lines matched to order items.
- Differences in price or quantity are flagged for the receiving clerk.
Result: Receiving starts from a draft that matches the order, and exceptions are visible before goods are put away.
RFQ response with a spreadsheet
Trigger: A supplier replies to a quotation request with an Excel file.
- Service reads the sheet and maps columns to quotation items.
- Prices, lead times and payment terms are written to the quotation lines.
- The buyer sees a comparison and awards the winner in Protheus.
Result: Offers land in the system of record without manual transcription, with the original file attached.
Keeping data on-prem
Email content is sensitive: invoices carry tax ids and prices, and quotations carry negotiated terms. Run extraction inside your network so documents never go to a third-party API. For on-prem Protheus, host the service on a server that can reach the mail system and the AppServer, use deterministic parsing for the XML, and use an open-weight model on your own GPUs for the free-text and PDF cases. That keeps the whole path, from mailbox to ExecAuto call, inside infrastructure you control. If mail is in Microsoft 365, the Graph connection is the only external dependency and can be restricted to specific mailboxes with application access policies.
Security checklist
- Give the mailbox account the least access needed, scoped to specific folders, with no send rights unless replies are required.
- Scan attachments for malware before parsing, since supplier mailboxes receive hostile files.
- Check the sender against known supplier domains and contacts before trusting bank detail or date changes, to resist invoice fraud.
- Keep an immutable log linking email id, extracted fields and the Protheus document created.
Ways to get it done
Native fiscal document import in Protheus or TOTVS fiscal services
Effort: Configuration and training, no development.
Enough for pure NF-e XML capture when suppliers already send standard files.
In-house parser with ExecAuto write-back
Effort: Four to eight weeks for invoices plus one other document type.
Teams with TL++ skills that want custom matching rules.
Partner build with AI extraction and review queue, such as Netray
Effort: Pilot on one mailbox, extend by document type.
Mixed document types, free-text replies, and a need to keep models on-prem.
Pitfalls
- !Trying to post final entries from low-confidence extraction instead of drafts for review.
- !Matching by item description rather than supplier code or cross-reference, which collides across suppliers.
- !Ignoring emails with several XMLs or with the XML inside a zip.
- !Not handling NF-e cancellations and correction letters that arrive after the original.
Frequently asked questions
Can Protheus read supplier emails by itself?
Not in a general way. Protheus can send workflow emails and import fiscal XML files placed in a folder or received through TOTVS fiscal services, but classifying free-form email and matching it to orders needs an external service calling Protheus.
How does the data get into Protheus safely?
Through ExecAuto or custom routines that run the standard validations, usually creating drafts such as a pre-invoice. This avoids direct table inserts that skip business rules and fiscal checks.
Do we need AI for NF-e XML?
No. The XML is structured and should be parsed deterministically. AI earns its place on PDFs, quotation replies and free text, where fields must be inferred and a confidence score decides whether to ask a human.
How is invoice fraud prevented?
Verify the sender against known supplier contacts, require a call-back or approval for changes to bank details, and compare totals to the purchase order. Automation should add checks, not remove them.
Can this run on-premises with local models?
Yes. Parsing, matching and an open-weight model can all run on servers in your network, with only the mail connection reaching outside if you use Microsoft 365 or Gmail.
Want Email automation working on your TOTVS Protheus?
A free 30 minute assessment: we map the integration path for your version and setup, and where it should run.
Get a free assessment