Skip to main content
TOTVS Protheus is the ERP from TOTVS used by thousands of Brazilian companies for sales, invoicing, finance, inventory and production. The TOTVS Protheus destination creates sales orders (pedidos de venda) in your Protheus from a table in your Lakehouse, for example orders captured by an e-commerce, a sales app or a partner system. The connector only sends new orders: it does not send changes or cancellations. To avoid creating the same order twice, each order carries an id from your table, which the connector writes in the item field Pedido Cliente (C6_PEDCLI) and looks up in Protheus before sending anything. When it cannot be sure (the id is used by another order, Protheus does not answer, the field was not filled), it does not send the order and the run fails with the reason, so you can check it. See Limits for what this check cannot cover. It uses the same Protheus REST service and the same kind of access as the TOTVS Protheus source.
Orders are created in your production Protheus. The Dry run setting is on by default: the connector then checks every order against Protheus with read-only queries and shows what it would create, without creating anything. Turn it off only after a dry run shows the expected result, and then run with Max records per run set to 1 and check that order in Protheus before raising the limit.
The Pedido Cliente field (C6_PEDCLI) of the orders created by Nekt holds the connector’s order id. Do not clear it or reuse it for anything else (for example, the buyer’s purchase order number): without it the connector cannot tell that the order already exists. The order id must fit in that field: up to 9 characters in a standard Protheus (or the size of the field in yours).

​
Before you start: set up Protheus

Protheus receives the orders through its integration layer, the EAI (standard message ORDER, routine MATA410). Ask your Protheus administrator to set up the items below. They are done once.
  1. REST service published over HTTPS. Nekt reaches your Protheus over the internet, so the REST service must be published with a valid certificate (for example https://erp.mycompany.com.br:8400/rest), with security on (SECURITY=1) and covering the company group that receives the orders. On TOTVS Cloud, use the REST address of your environment.
  2. EAI route (Configurador > Ambiente > Schedule > Cadastro de Rotas EAI): create a route whose product and application are NEKT (or the name you set in EAI source application), channel REST. The REST address of the route can stay empty: Protheus never calls Nekt.
  3. EAI adapter (Configurador > Ambiente > Schedule > Adapter EAI): routine MATA410, message ORDER, version 4.003, format JSON, Recebe = Sim, Envia = Não, method Síncrono (required: the connector stops if the adapter is asynchronous), route = the route above. If the ORDER adapter of purchase orders (MATA120) is also set up, both must use the same format.
  4. Company de/para (Configurador > Ambiente > Schedule > Emp.Fil Msg. Única): reference NEKT (the same name as the route), with the company and branch codes you type in the connection mapped to the same company group and branch in Protheus.
  5. A user for the integration, with access to the company and branch of the orders, permission to include sales orders (Faturamento, MATA410), and read access to the customer (SA1), product (SB1), payment term (SE4), TES (SF4), seller (SA3), price table (DA0) and sales order item (SC6) tables.
  6. Up-to-date Faturamento routines. The connector writes its order id in the item field Pedido Cliente (C6_PEDCLI) and reads it back to avoid duplicates. Recent builds of the ORDER adapter fill this field; if yours does not, the connector stops after the first order and asks for the update.
An asynchronous ORDER adapter is not supported yet. If Protheus answers that it queued an order for later processing, the run stops. Pause the destination’s schedule right away and set the adapter to Síncrono before the next run: while the adapter stays asynchronous, every run queues the same order again. Then check that order in the EAI monitor of Protheus, because the queue may still create it.

​
1. Add your TOTVS Protheus access

  1. In the Destinations tab, click on the “Add destination” button located on the top right of your screen. Then, select the TOTVS Protheus option from the list of connectors.
  2. Click Next and you’ll be prompted to add your access:
    • Protheus REST URL: the address of the Protheus REST service as reached from the internet, including the port and the REST path, for example https://mycompany.protheus.cloudtotvs.com.br:4050/rest. It must use https.
    • Username and Password: the Protheus user created for this integration.
    • Company code and Branch code: the company group (grupo de empresas) and branch (filial) where the orders are created, exactly as in Protheus (for example 01 and 0101).
    • Dry run (test mode): on by default. The connector checks every order and shows the first orders it would send and a summary in the run log, and creates nothing.
    • Max records per run: the maximum number of orders created per run; the others wait for the next runs. Leave it empty for no limit. Use 1 on the first real run.
    • EAI source application: the name of this integration in the Protheus EAI. Keep NEKT unless your administrator used another name in the route and company de/para.
    • Default TES: optional. The TES (3 characters, an outgoing TES) used for items that bring no TES of their own. Without it, Protheus applies its own rules (the product’s default TES or the TES Inteligente).
    • Enable partial success: when off, the run is marked as failed if any order was refused (the other orders are still created). When on, refused orders are only listed in the run log.
    • Verify SSL certificate (advanced): keep it on unless your server uses a self-signed certificate.
  3. Click Next.

​
2. Select your data to send

  1. Select the layer and then the table with your orders. Build it with a Query in the shape described below.
    Tip: The table can be found more easily by typing its name.
  2. Click Next.

​
Input table: one row per order item

The table has one row per item. The order columns (customer, payment term, date…) repeat on every item row of the same order, and the connector groups the rows by order_id. Column names must be exactly the ones below (upper or lower case); other columns are ignored. Example input table: This table creates two orders: PV000123 with two items and PV000124 with one.
Item discounts are not supported yet: send the net price in unit_price. An item_discount column is accepted when empty or 0; any other value refuses the order. Discounts will come in a later version, once confirmed on a real Protheus.
Keep codes as text columns in your Query. A code stored as a number loses its leading zeros (000045 becomes 45), and Protheus would not find the customer or product.

​
3. Configure your TOTVS Protheus data destination

  1. Describe your destination for easy identification within your organization. You can inform things like what data it sends, to which team it belongs, etc.
  2. To define your Trigger, consider how often new orders must reach Protheus. Orders already created are skipped on every run, so the table can keep old orders.
  3. Click Done.

​
How each run works

  1. The connector connects to Protheus and reads the orders of the table.
  2. It checks every order: required columns filled, quantities and prices greater than zero, the same customer and payment term on every row of the order.
  3. It looks each order_id up in the Pedido Cliente field of Protheus. An order found for the same customer and created through the EAI is counted as already exists, listed in the run log with its Protheus number, and skipped. If the id is in the Pedido Cliente of another order (another customer, or an order typed by hand), the order is refused with that reason.
  4. It checks in Protheus, with read-only queries, that the customer and store, products, payment term, TES, seller and price table exist and are not blocked.
  5. It checks that Protheus has no order created through the EAI, without an id in Pedido Cliente, with the same customer and the same products as an order of your table (in the last 30 days, or on the order_date of your orders). Such an order may be one created before without its id, or an order of another integration that also writes through the EAI. While one exists, the run creates no order at all and lists each Protheus order found. To release it:
    • if the Protheus order found is one of your table’s orders, fill its Pedido Cliente with that order_id: the next run counts it as already existing;
    • if it belongs to another integration, fill its Pedido Cliente with any value (or adjust that order).
  6. Dry run: it shows the first orders it would send and the summary N would be created / M already exist / K would be refused, and stops there.
  7. Real run: it sends the remaining orders one by one, each only once, up to Max records per run, and confirms each one in Protheus (including that Protheus kept its issue date and marked it as created through the EAI; if not, the run stops at once and asks you to pause the pipeline and contact support). The run log lists the orders created with their Protheus number, and the orders refused with the reason Protheus gave. If Protheus does not answer for an order and the order does not show up afterwards, the connector sends nothing else and the run fails; the next run looks that order up before sending it.
A refused order does not stop the others. When an order is refused, fix it in your table and let the next run create it. Orders already created are not sent again.
If the first orders sent are all refused with the same message, the connector stops sending: this usually means the EAI setup in Protheus is incomplete (adapter, route or company de/para). The message from Protheus is shown in the run log.

​
Limits

  • The duplicate check relies on the Pedido Cliente field: an order whose field was cleared or changed in Protheus can be sent again.
  • An order deleted in Protheus is no longer found: if its row is still in your table, it is sent again. Remove such rows from the table.
  • There is no lock between runs: do not schedule the destination more often than a run takes, so that two runs never send the same orders at the same time.
  • Item discounts are not supported yet.
  • Do not use it together with another EAI ORDER integration that leaves the Pedido Cliente field (C6_PEDCLI) empty for the same customers and products: its orders block Nekt’s writes until the field is filled.
  • Never reuse an order_id for a new order: an id already in Protheus for the same customer is treated as an existing order, even if the items differ.
  • The check for orders created without their id (step 5) only matters if your Protheus does not fill the Pedido Cliente field. It does not catch such an order if its products were changed afterwards in your table, or if it is older than 30 days and its issue date differs from the current order_date. Keep order_date as the order’s fixed date.

​
Check your new destination!

  1. Once completed, you’ll receive confirmation that your new destination is set up!
  2. You can view your new destination on the Destinations page. Run it with Dry run on and check the run log. Then turn Dry run off, set Max records per run to 1, run it again and check the new order in Protheus before raising the limit.
If you encounter any issues, reach out to us via Slack, and we’ll gladly assist you!