Integration architecture
Odoo EDI middleware and API integration
An Odoo EDI middleware integration links a trading partner's document service to the sales, delivery and invoice records in Odoo. The EDI service handles the agreed document route. The Odoo connection resolves item and location codes, applies business rules and leaves errors where someone can fix them.
An API is one way across that boundary. A managed file exchange can also work. The right choice depends on what your EDI provider exposes, how quickly you need a response and who will own a failed document.
The short answer
The EDI network or middleware receives the partner's X12 document and passes a usable message to Odoo through an API or agreed file format. The Odoo-side integration checks the partner, ship-to and item references before it creates or updates a sales order. The route and the record each need a named owner.
On the return trip, the integration reads an approved Odoo event, such as a confirmed shipment or posted invoice, builds the fields expected by the network and sends them with a stable document identity. Status and rejection messages come back into the same control loop.
Should middleware sit between EDI and Odoo?
Use the EDI service you already have when it can receive your trading partner's documents, expose a supported API or file exchange, and return delivery and rejection status. The Odoo work then begins at that service's boundary. Ask for its actual message samples and error responses before choosing a connector.
A direct AS2 or SFTP route makes sense when the trading partner accepts it and your team is prepared to own transport, translation, partner-specific maps and the exception queue. A web EDI portal can be enough for low volume if manual entry is controlled. The cheapest-looking route can become expensive when nobody owns the failures.
If a network is already named in your mandate, see how we approach SPS Commerce, TrueCommerce and Rithum. They explain where each network meets Odoo. Any platform certification should be verified with that platform.
Where the API sits
The boundary is easiest to reason about as three responsibilities with named owners.
Trading-partner side
The retailer or distributor publishes the implementation guide, document list, timing rules and test cases. Those rules remain authoritative regardless of the transport used near Odoo.
EDI service side
A network, VAN or middleware product receives and sends X12, handles the agreed connection, and may translate the partner format into its API model.
Odoo side
The connector resolves customers, ship-to locations, products, units and prices, then creates records under Odoo's access controls and business rules.
What must an 850 purchase order map before Odoo accepts it?
A retailer's 850 purchase order should become one Odoo sales order only after the buyer, delivery location, item and quantity make sense in your database. This illustrative mapping shows the decisions your team will need to make. Your trading partner's guide supplies the exact fields and rules.
| Incoming value | Odoo decision | If it does not match |
|---|---|---|
| Buyer and ship-to codes | Find the customer and delivery address agreed for this partner. | Hold the order for a location mapping decision. |
| Buyer item number | Resolve the buyer's item to the Odoo product and selling unit. | Flag the line; do not guess a substitute product. |
| Order number and change state | Match the document identity to an existing order before creating one. | Investigate a duplicate or changed order before retrying. |
| Quantity and requested date | Check the unit conversion and proposed fulfilment date against the sales workflow. | Send the discrepancy to the order desk for review. |
The same ownership continues outward: an 856 ship notice should reflect the validated delivery, and an 810 invoice should reflect the posted invoice. The partner's guide decides their exact fields and timing.
What happens when a document fails?
Suppose an 850 arrives with a buyer item number that has no approved Odoo product mapping. The integration should keep the original document and its partner order number, show the unmapped line to an owner, and leave the sales order unconfirmed. After the item is mapped, a controlled retry processes the same document identity and returns to the same order.
The response path needs the same discipline. A transport receipt or 997 acknowledgment does not prove the receiving application accepted the business content. The team should see what was sent, what came back, who owns the exception and when the next response is due.
Read the difference between a 997 acknowledgment and an 824 application advice.
The Odoo boundary
Odoo 19 provides an external JSON-2 API at the /json/2 endpoint. Available models, fields and methods depend on the database, and Odoo exposes that database-specific surface through its /doc page. Odoo's documentation also states that external API access is available on Custom plans.
A production connector should use a dedicated integration user with the smallest practical access rights. The API applies Odoo's record rules and field access to that user, so its permissions are part of the design and part of the test plan.
A custom module can provide narrow business methods when a multi-step operation must succeed or fail as one transaction. That keeps the external caller from assembling a fragile chain of generic record writes across several models.
The current Odoo reference: External JSON-2 API.
Controls that matter in production
Idempotency
Every inbound and outbound document needs a stable identity. A retry should return to the same Odoo record and document state rather than create a second order, shipment or credit.
Retry with a limit
Temporary failures need delayed retries. Permanent mapping or business-rule failures need an exception for a person. The system should tell those cases apart.
Status aging
A sent document needs an expected response and an aging rule. Delivered, syntactically accepted and accepted by the receiving application are separate states.
Traceable payloads
Support staff need the partner document number, the Odoo record, the normalized message and every response linked in one place, with sensitive data protected by access rights.
When an API route fits
An API route is a practical fit when the EDI service already offers a supported API, the supplier runs an Odoo edition that permits the required integration, and the team needs documents to land without portal rekeying. It is especially useful when status can be retrieved alongside the business document.
AS2 or SFTP may still be the required partner-facing transport. In that design the EDI service receives the X12 connection and presents an API boundary to Odoo. The two transports occupy different parts of the route.
If the current portal volume is low and keying is controlled, a web EDI tier can remain the cheaper answer. The decision should come from document volume, exception cost and the work hidden in the manual handoff.
Compare the routes: direct AS2 or SFTP, web EDI, and the integration engagement.
Official sources
Odoo's documentation defines the Odoo API surface, while X12 publishes the transaction-set definitions. Your trading partner's implementation guide governs the fields, codes and deadlines used in your relationship.
Odoo 19 External JSON-2 API · X12 transaction sets · Our plain-language X12 catalog
Map the route before choosing the connector
Bring the platform name, the transaction-set list and one sample order to the Requirement Check. We will identify the system boundaries, the Odoo records involved and the unanswered questions that belong in a scope.
Start the Requirement Check