Custom providers from a swagger specification

Custom providers from a swagger specification

Sprint Logistics, ShipHero and Amazon MCF are built in (each via its adapter app). Any other 3PL with a REST API described by a swagger/OpenAPI specification can be added from the UI - no code - through the Provider Designer at Configuration > Providers. This is an Admin-only, technical exercise: expect to read the 3PL's API documentation while you do it.

How it works

A custom provider is a provider definition: the parsed API specification plus a set of flow mappings that tell the connector which of the API's operations implements each connector flow, how to build the request, and where in the response the interesting values live. Instances then select the provider by name like any built-in one, and capability gating, dashboards, logs and roles all behave identically.

Step by step

  1. New provider, name it. The technical code derives from the name.
  2. Swagger / Docs URL - paste either the raw OpenAPI JSON URL or the API's documentation page: the importer scans HTML and JavaScript for the spec location and also tries the well-known paths (/swagger.json, /openapi.json, /v3/api-docs, /swagger/docs/v2, …). Click Load from Swagger URL.
  3. The spec loads: title, version, base URL and the full operation list are parsed, and the auth type is guessed from the spec's security schemes (API-key header, Basic, bearer-with-refresh) - adjust if the guess is wrong.
  4. Flow mappings. For each flow you want (connection test, order push, order status, despatch details, order cancel, stock levels, product push, product list, supplier push, return label, returns list, warehouse list, carrier list) the designer suggests a likely operation by keyword; confirm or pick another. Then per mapping:
  5. Request template - JSON with ${...} placeholders filled from context (order, lines, shipping address, instance, mapped warehouse code, carrier code…), including $for/$do loops for line items.
  6. Response paths - dotted paths to extract the remote reference, status, tracking, line items, lot details and so on from the reply.
  7. Mark Ready, create an instance choosing the new provider, enter credentials, Test Connection.

Capabilities follow the mappings

A custom instance's capabilities are exactly its mapped flows: map order_push and orders light up; leave returns_fetch unmapped and the Returns switch never appears for it. The mapped-flow count on the Providers list shows coverage at a glance.

Reloading a changed spec

Reload Specification re-imports the API after the 3PL publishes changes. Parsed operations are replaced - flow mappings keep their templates and response paths but need their operation re-selected where identifiers changed. The confirmation dialog says exactly this before anything is touched.

Support contacts

Give every provider - built-in or custom - a primary support email and optional comma-separated secondary contacts. These power the Email Support button on failed Sync Log entries (see Sync Log and troubleshooting).

Custom provider slots

Custom providers are licensed as slots, counted per distinct provider definition - all instances of the same definition (staging and live included) share one slot. One slot is included with the core app; slot packs add 1, 5 or 10 more, available on the Odoo store or from sales@latasys.com. Built-in providers do not use slots: newer license keys name the ones they include (Sprint Logistics, ShipHero, Amazon MCF), while keys issued before this model keep their original numeric provider count. Provider changes are made centrally by LataSys and apply on the next daily license check without a new key.

Limits worth knowing

The generic executor covers request/response APIs that follow the spec. 3PLs needing exotic auth handshakes, non-JSON payloads, or behaviour that contradicts their own swagger are better served by a built-in adapter - contact LataSys and we will scope one.