Hoppa till huvudinnehåll

The API and the import

Facts reach OrderEx in two ways. Your systems call the API for everything that happens from the day you connect them, and OrderEx onboarding imports a file with the history you already have, in a trial run. This page explains which to use for what.

Which to use​

The APIThe import
What forThe running flow: every order and fact as it happensThe history you already have, loaded in a trial run
Who runs itYour systemsOrderEx onboarding, with files you prepare
How it arrivesThe calls in these guides, one request per order or factFiles of JSON Lines, one record per line
When an order was placedWhen OrderEx receives itThe time in the record's placedAt
Personal dataThe fields Fields and personal data marksNone: the customer is only customerId

Both end up as the same facts, checked by the same rules: every import record goes through the same commands as the API, so a record the API would reject is rejected for the same reason.

The API for the running flow​

Connect each system to the API for the facts it knows about, as Getting started and The order lifecycle show: your shop creates each order with POST /api/v1/orders when the customer checks out, your warehouse system reports each shipment, and so on. Each fact is sent when it happens, with your own id for it, so a call sent again changes nothing. A reliable integration explains how to retry.

Do not load your history through the API. An order created through the API is placed when OrderEx receives it, so old orders would look new.

The import for your history​

The import loads the orders and facts you already have, so OrderEx can show where goods and money did not match before you connected. OrderEx onboarding runs it into your tenant during a trial run, and your systems never call it. Agree with your OrderEx contact which period to load and how to hand over the files.

Prepare the files​

  • Each file is JSON Lines in UTF-8: one JSON object per line, one record per object.
  • A record's type says what it is, and Fields and personal data lists the fields of each type. A record with a field its type does not take is rejected.
  • Every record names its order by channel and externalOrderNumber, the same pair your shop sends to the API.
  • Every time is the time in your system, such as placedAt, shippedAt or occurredAt, with its offset.
  • Each source has its own files: orders hold order and cancellation records, shipments hold shipment and tracking_event records, payments hold payment records and returns hold return records.

How OrderEx runs them​

  • Orders are imported first, then shipments, payments and returns. A record whose order or shipment is not there yet is rejected, and the file can be run again once it is.
  • Each order is imported all or nothing. A rejected order is reported with its reason and the line of the file it is on, and the rest of the file goes on.
  • The same file imported twice creates each fact once, since every fact carries your own id.
  • OrderEx imports only into a tenant in a trial run. Your production integration uses the API.

Next​

Reading data shows how to read orders, their timeline and their shipments back.