# Integration overview

Your connector sits between a channel and Mirakl Connect, and it keeps the two in step.
It exchanges information with the Mirakl Connect Channel Platform in two directions:

* It calls Mirakl Connect's REST APIs to push updates.
* It receives Mirakl Connect's events when something changes there.


This page describes that model.

## Where your connector sits

Your connector is a middleware between two platforms: Mirakl Connect and one channel.
Neither of them is yours, and both of them keep their own state.

* **Mirakl Connect** is where sellers manage their stores, their catalog, their offers, and their orders.
It turns a seller's actions into the APIs you call and the events you receive, and it holds the canonical record of everything that crosses the boundary.
The **Channel Platform** is the part of it you build against.
* **The channel** is an external marketplace or platform, where a seller lists their products and buyers place orders.
It has its own APIs, its own identifiers, and its own rules.
Mirakl does not operate it.
* **Your connector** sits between the two and keeps them in step.
It translates in both directions, it calls Mirakl Connect's APIs, and it receives its events.
This documentation is written for the person who owns it.


```mermaid
graph LR;
    platform["Mirakl Connect Channel Platform"]

    subgraph connector["Middleware"]
        integration["Channel Connector"]
        localstate[("Mapping and delivery state")]
        integration <--> localstate
    end

    channel["Channel (external platform)"]

    platform -.->|"Events"| connector
    connector -->|"APIs"| platform
    connector -->|"APIs"| channel
    channel -.->|"Events"| connector
```

### Data flows both ways

Everything your connector does falls into one of two directions.

* **You call Mirakl Connect.**
Your connector calls the **Channel Platform REST APIs** to push updates: to submit orders, to report on the fulfillment and the returns, to apply the catalog configuration, and to publish a store's business information.
These calls are request and response, they are authenticated with OAuth2, and they are served under the base path `/api/channel-platform`.
For how to obtain and use a token, refer to [Authorization](/content/product/connect-channel-platform/developer-guide/authorization).
For the mechanics of a call, refer to [Calling the APIs](/content/product/connect-channel-platform/developer-guide/calling-the-apis).
* **Mirakl Connect notifies you.**
Mirakl Connect emits **events** when something happens there that you must know about or act on: a change to a store, a catalog update, or an order action to perform.
You do not poll Mirakl Connect for these events, because it publishes them to a queue or a topic that you own and consume.
For how the events reach your connector, refer to [Receiving events](/content/product/connect-channel-platform/developer-guide/receiving-events).


Your calls are synchronous, and you start them.
The events are asynchronous, and Mirakl Connect starts them.
Most real workflows use both.

For the operations you call and the events you consume, grouped by business domain, refer to the [API and event directory](/content/product/connect-channel-platform/getting-started/api-and-event-directory).

## Where the state lives

There is one canonical record for each business entity, and it is not in your connector.

* **Mirakl Connect holds the canonical business state**: the channels, the stores, the products, the offers, the prices and the stock, the orders, and the returns.
When a seller changes something there, it records the change and notifies you.
When you push an order or a status update, it records that too.
* **The channel holds its own state**: its listings, its orders, and the identifiers it assigns.
Your connector reads and writes this state through the channel's own API.
* **Your connector holds the state that links the two**: the mapping between the Mirakl identifiers and the channel identifiers, plus whatever you need to process the events safely, such as which events you have already handled, so that a repeat delivery is a no-op.
Mirakl Connect does not keep this correlation for you.
It is the core of what your connector owns.


## What Mirakl Connect guarantees, and what you own

The boundary of responsibility is sharp.
Design your connector around it.

**Mirakl Connect guarantees:**

* A single, **consistent event payload**, whatever transport you receive the events over.
The envelope and the body are the same across every supported destination.
* **At-least-once delivery** of every event, with **automatic retries** on a windowed-backoff schedule when a delivery fails.
* **Ordering for each partition key.**
Events that share a business key, such as one order, one product, or one offer, are delivered in order relative to each other.
* **REST APIs secured with OAuth2**, under a stable base path, so that your calls authenticate the same way across every domain.


**Your connector owns:**

* **Idempotent processing.**
Because delivery is at-least-once, the same event can arrive more than once.
To handle a duplicate must be safe and must have no extra effect.
This is the direct consequence of the delivery guarantee above.
* **Acting on the commands, and confirming them.**
Some events tell you a fact.
Others ask you to **do** something, such as to accept an order, create a shipment, or process a return, and they expect you to report the outcome back through the REST APIs.
* **The mapping.**
You map the Mirakl entities, statuses, and identifiers to and from the channel's own, in both directions.
* **The reconciliation.**
The delivery has no dead-letter queue: once the retries are exhausted, Mirakl Connect does not deliver an event again.
Your connector is responsible for detecting the gaps and recovering the state it missed, on its own.
Plan to reconcile proactively, rather than to rely on a repeat delivery.


## Related pages

* [Business use cases](/content/product/connect-channel-platform/developer-guide/business-use-cases): the flows you implement, which ones are yours, and where to start.
* [API and event directory](/content/product/connect-channel-platform/getting-started/api-and-event-directory): the concrete REST operations and event types, grouped by business domain.
* [Authorization](/content/product/connect-channel-platform/developer-guide/authorization): how to obtain and use a token for the calls you make.
* [Calling the APIs](/content/product/connect-channel-platform/developer-guide/calling-the-apis): the base path, the `channel_id` parameter, and synchronous against asynchronous operations.
* [Receiving events](/content/product/connect-channel-platform/developer-guide/receiving-events): the event envelope, the supported destinations, and how to configure each one.