OneTrail × Odoo Integration

• Introduction what OneTrail is and why we integrate it with Odoo
• Module 1 OneTrail Product Integration
• Module 2 OneTrail PO Integration
• Setup checklist

OneTrail is a Dutch B2B integration platform for the IT and telecom trade. Its Trading Partner Network (TPN) links resellers, retailers, distributors and manufacturers, so that each company can exchange product, order and invoice data electronically with many trading partners through a single connection instead of building a separate link to every supplier.

For a reseller, OneTrail acts as one standardised window onto all connected IT distributors (for example TD SYNNEX and Ingram Micro). The main services it provides are:

• Product Data Index (PDI) a central product catalogue in which specifications from manufacturers, distributors and content providers are combined and standardised. Every product gets a unique PDI number, and all products are classified with the international UNSPSC code system.
• Live distributor offers for each product, the current purchase price, stock per warehouse and expected availability (ATP) date of every connected distributor.
• Electronic ordering (EDI) purchase orders are sent to the distributor electronically, and the distributor's replies come back the same way: receipt acknowledgement, order confirmation and dispatch advice (including shipped quantities and serial numbers).
• Special bids manufacturer project pricing for a specific end customer, published to the distributors that may sell at that price.

An IT reseller typically sources its products from several distributors. When Odoo is the ERP, it is where sales orders, purchase orders, stock and invoicing are managed, while OneTrail is where the distributor data and order messages live. Without a connection between the two, the purchasing and sales teams have to bridge the gap by hand checking prices and stock on distributor portals, typing products into Odoo, re-entering orders and following up confirmations by e-mail. This is slow, error-prone and does not scale with a catalogue of thousands of products that change price and stock every day.

Integrating OneTrail directly into Odoo removes this manual work and makes Odoo the single place to quote, buy and track OneTrail products:

In short, the integration gives the business accurate, up-to-date product data, faster and error-free purchasing, better margin control and full visibility of every order from quote to delivery.

The integration is split into two modules. The Product Integration module is the foundation: it holds the shared OneTrail configuration, keeps products and vendor pricing in sync, and lets users pull new products from OneTrail. The PO Integration module builds on it and handles the full purchase-order lifecycle, special bids and the intercompany dropship flow.

Communication runs in two directions. OneTrail pushes messages to Odoo through six authenticated webhooks; each webhook answers immediately and hands the work to a background queue job, so large volumes never block OneTrail or Odoo users. In the other direction, Odoo calls the OneTrail REST APIs when a user searches for a product, refreshes a product, checks availability or sends an order.

Figure 1 Integration architecture

Both modules rely on a small set of identifiers to match OneTrail data with Odoo records. Getting these right in master data is the single most important setup step.

This module connects OneTrail with Odoo to keep product and stock information in sync automatically. Whenever OneTrail publishes a change to a product, a distributor price or a stock level, the update is pushed to Odoo in real time and applied to the product and its vendor lines. Users can also search the OneTrail catalogue directly from Odoo and create a fully configured product, with all distributor prices, in a single step.

• Real-time sync of product data, distributor prices, stock and availability (ATP) dates through two authenticated webhooks.
• Built for volume: feeds are split into small background jobs, each product is processed in isolation, and only fields that actually changed are written.
• Live OneTrail search by PDI number or barcode, from the product list or directly on a sales order line, with one-click product creation.
• Automatic pricing: an expected purchase price is calculated from distributor offers, and the sales price is derived from a configurable markup.
• Flexible exclusions by category (including sub-categories), product type, brand, warehouse and Apple-authorised vendors.
• Sandbox and Production environments with a single switch.
• Monitoring: e-mail alerts for failed jobs, stuck jobs and missing feeds, plus automatic cleanup of finished jobs.
• Full audit trail: every OneTrail change is logged in the product chatter with old and new values.

A single configuration record, found under Settings → OneTrail Administration, drives the whole integration. It stores the connection details and all business rules used by both modules.

• Environment selects Sandbox or Production; the matching base URL, Username and Password are used for all outgoing API calls.
• Vendors lists the distributors (with a GLN) whose offers are requested from OneTrail; OneTrail Purchase Companies lists the companies allowed to create OneTrail purchase orders.
• Selling Price Markup and Brands Excluded control automatic sales pricing; Exclude Category, Exclude Product Type and Stock exclusion sellers control what is skipped.
• Allow vendor RealTime Backend asks OneTrail to query distributors live rather than return cached data.
• Alert Notification Users receive all monitoring e-mails. The read-only Product API and Stock API fields show the webhook URLs to give to OneTrail.

OneTrail sends product and price changes to /webhook/product_feed_updates. The endpoint checks the caller's credentials, accepts JSON or XML, and splits the product list into chunks (200 products per job by default) that are queued on the root.product_feed channel. OneTrail receives an immediate 202 Accepted response with the job IDs.

• Each product is matched on PDI number or Internal Reference and processed inside its own savepoint, so one bad record never stops the batch.
• A PostgreSQL advisory lock per PDI prevents two workers from updating the same product at the same time; locked products are retried automatically.
• Category (via UNSPSC), brand, product group, sales price and the Buy + MTO routes are updated only when they differ from the stored values.
• The distributor's vendor line is created or updated with price, stock, ATP date and vendor product code; duplicate vendor lines are cleaned up.
• A feed line with status Delete removes that distributor from the product. Excluded categories, excluded product types and Apple vendor mismatches are skipped.
• Chunk size (onetrail.product_feed.chunk_size) and row-lock timeout (onetrail.queue.lock_timeout, default 5s) are adjustable system parameters.

Figure 2 Product feed processing flow

1. OneTrail posts the product feed to /webhook/product_feed_updates.
2. Valid Basic Auth (login + API key)? No → return 401 Unauthorized.
3. Parse the JSON / XML payload and validate ProductCatalog.product.
4. Split products into chunks (default 200) and queue one job per chunk; return 202 Accepted with job IDs.
5. For each product (own savepoint), take an advisory lock on the PDI. Lock held → mark "retry" (the job is re-queued if every product needs a retry).
6. Find the product by PDI / Internal Reference. Not found → skip.
7. Map category (UNSPSC), brand, product group, price and routes; write only changed fields.
8. Vendor known, status not "Delete", not excluded, Apple rule OK? No → skip the product, or remove the vendor line if the status is "Delete".
9. Create / update the vendor line: price, stock, ATP date, vendor code, sync dates.
10. Post a change log on the product (only if something changed).

Stock-only changes arrive on /webhook/stock_updates as JSON with Content-Type text/plain. After authentication, one queue job on the root.stock_updates channel processes the whole message.

• For each product the job reads the PDI, distributor GLN, stock quantity, net price and EAN.
• It updates the distributor's OT Quantity Available and Last Stock Update date, and updates the product barcode if a new EAN is received.
• If the distributor is new for that product, a vendor line is created with the received price.
• The expected purchase price and sales price are recalculated and the change is logged on the product.

Figure 3 Stock update processing flow

1. OneTrail posts a stock update to /webhook/stock_updates.
2. Content-Type text/plain and valid JSON? No → return 400.
3. Valid Basic Auth? No → return 401.
4. Queue one job on channel root.stock_updates.
5. For each product, read PDI, vendor GLN, stock, net price and EAN.
6. Product and vendor found, not excluded, Apple rule OK? No → skip (reason logged).
7. Update the barcode if the EAN changed.
8. Update vendor stock and stock sync date (create the vendor line with price if new).
9. Recompute the expected purchase price and sales price (markup).
10. Post a change log on the product.

Users in the Manage Onetrail Product group can search the live OneTrail catalogue from a dialog. The dialog opens from the OneTrail button on the product list, or from the "Search on Onetrail..." option in the product dropdown of a sales order line.

• Search by PDI number or barcode (GTIN). If the product already exists in Odoo, the user is told so instead of creating a duplicate.
• Results show one row per distributor with price, total stock (excluded warehouses are ignored for PDI searches), latest ATP date and vendor product code. Apple products only show Apple-authorised vendors.
• Confirming creates a storable product with PDI, barcode, category, brand, product group, tracking and Buy + MTO routes, plus a vendor line for each selected distributor.
• When started from a sales order the new product is placed on the line; from the product list, the new product form opens.

Figure 4 Search OneTrail and create a product

1. User opens "OneTrail Search" (product list button, or "Search on Onetrail..." on a sales order line).
2. User in group "Manage Onetrail Product"? No → the option is not shown.
3. Enter a PDI number or barcode (GTIN).
4. Already exists in Odoo? Yes → show "Found in Odoo".
5. Call GET /productApi/v1/products (Sandbox or Production, filtered by the configured vendor GLNs).
6. Show one row per vendor: price, stock (excluded warehouses ignored), ATP date, vendor code.
7. User selects vendor rows and confirms.
8. Create the product: PDI, barcode, category, brand, product group, tracking, Buy + MTO routes.
9. Create / update vendor lines (Apple products only for Apple vendors).
10. Product is added to the sales order line, or opened in form view.

The OT Product Updates button on the product and product variant forms fetches the latest data for that product from OneTrail on demand. It updates category, brand, product group, barcode and routes, refreshes every distributor's price, stock, ATP date and vendor code, and posts a before/after summary in the chatter. The button refuses to run for excluded categories or product types, or for products without a PDI number.

Each OneTrail product shows an Expected purchase price, calculated from its vendor lines. If at least one distributor has stock, it is the highest price among the distributors that have stock; if none has stock, it is the highest price overall.

When a Selling Price Markup is configured, the sales price is set to expected purchase price ÷ markup. For example, a markup value of 0.85 gives a sales price about 17.6% above cost.

Brands listed under Brands Excluded keep their manually managed sales price.

The expected purchase price is also shown on sales order lines and is used as the default purchase cost for MTO and dropship lines.

From a sales order line, a vendor wizard lists every distributor for the product with price, OT stock, ETA, lead time and last price and stock sync dates. Selecting a row sets that distributor as the line's supplier and updates the line's purchase cost, so the salesperson can choose the best offer before the order is confirmed.

The module adds a UNSPSC-based category structure so OneTrail classifications map automatically to Odoo categories.

• Import UNSPSC Category (on the product category list) reads an XLSX or CSV file with Segment, Family, Class and Commodity codes and names, and builds the four-level category tree.
• Product Class is set on a category and inherited by its sub-categories; products get their class from their category.
• OT Product Group mirrors OneTrail's product groups and carries a default tracking mode (none, lot or serial). It is applied to a product the first time the group is set, and is not changed afterwards.
• Products whose UNSPSC code or group is unknown fall back to a default "uncategorised" category and default group.

Product Class and OT Product Group are stored on stock moves, move lines, quants, stock valuation layers and the sales analysis report. This allows inventory, valuation and sales reports to be grouped and filtered by these OneTrail dimensions.

Scheduled actions and job hooks keep the integration visible and the queue table small. All alerts go to the Alert Notification Users.

• Failed job alert an e-mail is sent immediately whenever a queue job fails, with the job name, channel and error.
• Stuck jobs (hourly) alerts when jobs remain pending or enqueued for more than 2 hours.
• Missing stock / product feed (daily) alerts when no stock update or product feed job has been received in the last 4 hours.
• Delete Done Queue Jobs (daily) removes finished jobs older than the configured threshold (30 days by default); a manual wizard is also available.

The Manage Onetrail Product group controls who can search OneTrail and create products from it. Webhooks do not use a browser session; they authenticate with HTTP Basic Auth, where the username is the Odoo user login and the password is an Odoo API key for that user.

This module connects OneTrail with Odoo for purchase orders. Purchase orders to OneTrail distributors are recognised automatically, checked against live availability, and sent electronically to OneTrail. The distributor's acknowledgement, order confirmation and dispatch notice then flow back into Odoo, updating the order and preparing the receipt. The module also manages manufacturer special bids and automates the intercompany dropship flow between the main company and its subcompanies.

• Automatic OT PO detection: orders for an allowed company and a vendor with a GLN become OneTrail purchase orders.
• Live pre-check of price and stock before sending, with tools to split short or unavailable lines into a new order.
• Electronic ordering: one click sends the order to OneTrail; the order is then locked against changes.
• Automated responses: acknowledgement, confirmation and dispatch messages update status, quantities, prices, dates and serial numbers.
• Complete status history of every OneTrail status change on each order.
• Special bids with a shared quantity pool per product, automatic activation and expiry, and special pricing on sales and purchase lines.
• Intercompany automation: dropship routing, auto-confirmation, cost propagation and invoice/bill synchronisation between companies.
• Safe operation: each inbound message type can be paused with a restrict switch.

Every purchase order has an Order Type of Normal PO or OT PO. It is set automatically when the order is created or the vendor changes: the order becomes an OT PO only if its company is listed under OneTrail Purchase Companies and the vendor has an OT Vendor GLN.

• OT POs show the OT Status badge and an Allow Partial Delivery option (sent as Partial or Complete fulfilment).
• The standard Confirm Order button is hidden for OT POs, because confirmation comes from the distributor through OneTrail.
• After an order is sent, its vendor, currency, delivery details, dates and lines are locked. Resetting the order to draft sets the status back to Not Sent.

Before sending, the OT Realtime Check button asks OneTrail for current price and stock for every line with a PDI number (POST /productApi/v1/products/bulk, filtered by the vendor's GLN).

• Price differences larger than €0.01 are corrected on the line automatically and noted in the chatter (lines linked to a special bid are not changed).
• Insufficient stock and products not found open the Quantity Mismatch wizard, which also lists other distributors that have enough stock.
• In the wizard, selected lines are moved to a new purchase order (the shortfall, or the whole line if not available), linked to the original order and sales order.
• If the order mixes OneTrail and non-OneTrail products, a wizard first offers to move the non-OneTrail lines to a separate normal purchase order.

The Send to Onetrail button validates the order and posts it to the OneTrail order exchange API. The response is recorded in the chatter and the status moves to Sent, or Send Error if OneTrail rejects the call.

• Checks before sending: at least one line, vendor GLN, company GLN, warehouse GLN (unless it is a dropship), and a PDI number on every product.
• Order content: order reference, currency, order and delivery dates, delivery type (warehouse or dropship), ship-to and bill-to parties with GLN and address, and all lines with PDI, vendor product code, quantity, unit of measure, price, discount, taxes and special bid number.
• The configured shipping cost line is excluded from the message.

Each OT PO carries an OT Status, and every change is stored in the PO history with the old status, new status, date and user.

OneTrail sends the distributor's receipt acknowledgement to /webhook/po_receive. A queue job finds the purchase order by its reference and sets the status to Received OK when the exception code is 000E, or Received Error otherwise, with the error description posted in the chatter.

The distributor's order confirmation (Pip3A4) arrives on /webhook/po_update and is processed by a queue job.

• The overall decision sets the status: Accept → Order Accepted, Change → Order Changed, Reject → Order On Hold, Delete → Order Deleted.
• Lines marked Accept, Change or Add update quantity, unit price, ship date and OneTrail line number; new lines are created when needed. Lines marked Reject or Delete, and products missing from the message, get quantity 0.
• A comparison table (Odoo vs OneTrail quantity, price and ship date, with differences in red) is posted in the chatter. Any shipping charge from OneTrail is logged for comparison only.
• Accepted or changed orders are confirmed automatically; rejected or deleted orders are cancelled.

The advance shipment notification (Pip3B2) arrives on /webhook/po_dispatch. For each shipped item, the job finds the purchase order, its receipt, the product (by PDI) and the order line (by OneTrail line number).

• The expected delivery date is set on the stock move, and the shipped quantity is filled in on the receipt.
• For serial-tracked products, the serial numbers in the message are created and assigned automatically.
• A dispatch summary is posted on both the receipt and the purchase order. The receipt is left for the warehouse to validate.

Figure 5a OT purchase order: creation, check and sending

1. Purchase order created (manually, or from a sales order via MTO / Buy).
2. Company allowed for OT and vendor has a GLN? No → Normal PO (standard Odoo flow).
3. Order Type = OT PO, OT Status: Not Sent.
4. Optional: OT Realtime Check (POST /productApi/v1/products/bulk).
5. Price / stock / not-found issues? Yes → price auto-corrected; the Quantity Mismatch wizard moves lines to a new PO.
6. Send to Onetrail (validate GLNs and PDI, build order JSON).
7. API OK? No → OT Status: Send Error (user fixes and resends). Yes → OT Status: Sent (PO header and lines locked).

Figure 5b OT purchase order: distributor responses and receipt

1. Acknowledgement webhook (/webhook/po_receive): code 000E → Received OK; otherwise → Received Error.
2. Confirmation webhook (/webhook/po_update): vendor decision.
3. Reject / Delete → cancel the PO.
4. Accept / Change → update quantity, price and ship date; post the comparison table in chatter; confirm the PO. Optionally create a back order for the remaining quantity.
5. Dispatch webhook (/webhook/po_dispatch): fill the receipt with shipped quantity, serial numbers and delivery date.
6. User validates the receipt: cost is synced up the chain and dropship pickings are auto-validated.

When a distributor confirms less than was ordered, the Create Back Order button on the confirmed OT PO creates a new purchase order for the difference between the expected (originally ordered) quantity and the confirmed quantity. Back orders are linked to the original order and shown in the OT Back Orders smart button.

Back orders keep the link to the originating sales orders, so the goods flow to the right customer deliveries when received.

If a Shipping Cost Product is configured, a shipping line (quantity 1, price 0) is added automatically when an OT PO is confirmed.

When sales orders generate purchase orders through MTO or dropship routes, the module adjusts Odoo's standard merging so OneTrail orders stay consistent.

• New demand is only added to an OT PO that has not yet been sent; otherwise a new purchase order is created.
• Lines for the same OneTrail product and vendor are merged regardless of cost (OneTrail sets the final price); special bid lines are always kept separate.
• When one PO line serves several sales orders, all of them are recorded on the line and their deliveries are linked correctly when the PO is confirmed.

Manufacturers grant special bids: a reduced price for a specific end customer, valid for a period and up to a maximum quantity. OneTrail sends these to /webhook/special_bid, and the module manages them under Purchase → Special Bids.

• A new bid reference creates a bid in Action Required status with end customer and validity dates; an existing bid only has its dates updated and its product lines added or refreshed.
• The distributor is matched by GLN. Each product is matched by manufacturer part number (Internal Reference) and gets a bid line (maximum quantity) plus a special vendor pricing line.
• Products not found in Odoo are noted in the chatter and a To-Do activity is created for the Special Bid Responsible Users.
• A bid becomes Active automatically once it has a customer, today is within its validity dates, and every product has a maximum quantity; it becomes Expired after its end date (checked daily). It can also be set active manually.
• On a sales order line the salesperson picks the bid; the bid cost (highest bid price) becomes the purchase cost, and the bid is carried through to the generated PO line.
• Each bid line tracks Reserved (draft POs), Consumed (confirmed POs) and Remaining quantity. Ordering beyond the remaining quantity shows a warning and a chatter note, but is not blocked.
• Special bid pricing lines are hidden from the normal vendor list on the product, and a smart button shows the product's special bids.

Figure 6 Special bid processing and use

1. OneTrail posts a special bid to /webhook/special_bid; a queue job is created (channel root.ot_special_bid_update).
2. Bid reference exists? No → create the bid (Action Required) with customer and validity dates. Yes → update validity dates only (customer and lines kept).
3. Match the distributor by GLN (a missing GLN is noted in chatter).
4. For each product, find it by MPN. Not found → chatter note and To-Do activity for responsible users.
5. Create / update the bid line (max quantity) and the special vendor pricing line.
6. Auto status: Active when a customer is set, today is in the date range and all max quantities are above 0; Expired after the end date (daily cron).
7. Salesperson picks the bid on a sales order line: bid cost = highest bid price.
8. Procurement carries the bid to the PO line; the pool tracks Reserved / Consumed / Remaining; over-use only warns.

Settings → Intercompany Administration defines the Main Company, its Subcompanies, and two switches: Auto-confirm Purchase Orders and Auto Sync Invoices & Bills. With this set up, subcompanies sell OneTrail products that the main company buys from distributors.

• A subcompany sales order may not mix OneTrail and non-OneTrail products; the order must be split.
• On a subcompany order line with a OneTrail storable product, the Dropship route and the main company as vendor are set automatically, with the purchase cost taken from that vendor line or the expected purchase price.
• Subcompany orders where all lines are OneTrail products with a supplier are confirmed directly, and the resulting intercompany PO to the main company is auto-confirmed when enabled.
• The main company's vendor price for OneTrail products is kept equal to the expected purchase price.
• When the main company validates the receipt from the distributor, the actual cost is pushed along the chain (main company SO line → subcompany PO line → subcompany SO line), and the linked dropship pickings are validated automatically.
• When an invoice is posted to a partner that is another company in the group, the matching vendor bill is created in that company and linked to its purchase order.

Figure 7 Intercompany dropship flow

1. Subcompany (Company B) creates a sales order with a OneTrail storable product.
2. Mix of OT and non-OT products? Yes → save blocked; split the order.
3. Line auto-set: Dropship route, main company as vendor, expected purchase price.
4. Sales order confirmed (fast-track when all lines are OT and a vendor is selected).
5. Intercompany PO to the main company auto-confirmed (if enabled).
6. Main company (Company A) sales order created by the intercompany rules.
7. Company A OT PO to the distributor (OneTrail PO flow).
8. Company A receipt validated.
9. Actual cost pushed: A SO line → B PO line → B SO line.
10. Linked dropship pickings auto-validated.
11. Posted invoice creates the matching bill in the partner company (Auto Sync Invoices & Bills).

The OneTrail Administration form gains the webhook URLs for acknowledgement, order confirmation, order dispatch and special bids, plus three restrict switches. When a restrict switch is on, messages of that type are still accepted but ignored by the queue job useful during maintenance or testing.

All inbound webhooks use HTTP Basic Auth (Odoo login + API key), accept JSON, strip "tns:" namespace prefixes, and return 202 Accepted once the job is queued.

The following steps bring a new database to a working state. Steps 1–6 are needed for product sync; steps 7–10 add purchasing and intercompany.

1. Install queue_job (with workers running) and the Python package xmltodict, then install the Product Integration module followed by the PO Integration module.
2. Create a dedicated integration user, generate an API key for it, and give OneTrail the user's login and API key for the webhooks.
3. In Settings → OneTrail Administration, choose the environment and enter the Sandbox and/or Production URL, username and password.
4. Enter the OT Vendor GLN on each distributor contact and add them to Vendors; tick Is Apple Supplier where applicable.
5. Import the UNSPSC category tree, set Product Classes, and create OT Product Groups with their codes and tracking modes.
6. Set the Selling Price Markup, exclusions and Alert Notification Users; give the Product API and Stock API URLs to OneTrail.
7. Set the Onetrail GLN on each purchasing company and warehouse, and add the companies to OneTrail Purchase Companies.
8. Optionally choose a Shipping Cost Product and Special Bid Responsible Users; give the acknowledgement, confirmation, dispatch and special bid URLs to OneTrail.
9. For intercompany use, set the Main Company and Subcompanies under Intercompany Administration, tick Main Company on the company record, and enable Inter-Company Transactions.
10. Test end-to-end in Sandbox: search a product, send a PO, and confirm that acknowledgement, confirmation and dispatch messages update the order.