Build a connector

A connector is the part that talks to a third-party system for Miridia. Miridia does not contain code for each provider. When Miridia must do an operation on a provider, for example "get the orders from the store", it sends an HTTP request to a connector. The connector translates the request into the API calls of the provider. Then it translates the answer back into the Miridia format.

A connector can be any HTTP endpoint that reads and writes JSON. For example, it can be an n8n workflow, an Azure Function, an AWS Lambda function, or a small web service.

This model has three advantages:

• A new provider is configuration, not a new Miridia release. The provider, its operations, and the connector addresses are data.
• You correct a connector without a change to Miridia. Deploy the connector again, or edit the n8n workflow.
• Miridia stays consistent. Each provider in a domain uses the same request and response shapes.

Domains and operations

Each provider belongs to one domain:

Each operation has a workflow title, for example GetOrders, CreateProduct, or GenerateShipmentQuotation. For each provider, each supported workflow title is bound to one connector address and one HTTP method. When Miridia needs the operation, it sends the request to the bound address.

Requests from Miridia to the connector

Each request from Miridia carries these headers:

The body is the JSON request for that workflow title. The field names use camelCase, and enum values are PascalCase strings. Read API conventions.

The connector must reply as follows:

• A 2xx status code means success. Miridia reads the body as the response of the workflow title.
• Any other status code means failure. Miridia shows the response body in the error, so return a short and clear message.
• An operation that returns a list uses this shape:

{
  "items": [],
  "totalCount": 0
}

Requests from the connector to Miridia

A connector can also call Miridia. It does this to deliver data from the provider, or to finish an operation that takes a long time. The connector authenticates as the business with an API key in the x-dispatch-api-key header. Read Authentication to create a key.

Each of these requests identifies the external record in a context object: the configured provider, the external identifier, and the identifier type. Miridia uses the context to link the external record to the Miridia record. Thus a second delivery of the same order updates the order and does not make a copy.

When the connector creates an order, send the external customer and the external order items. Leave the Miridia customer identifier and the Miridia order items empty. Miridia finds the matching customer and products from the external data, and then fills in these two fields.

Token refresh

Some providers, for example Xero and Zoho, issue access tokens that expire. When the connector refreshes a token, it must send the new token to Miridia:

{
  "configuredProviderId": "<configured-provider-id>",
  "accessToken": "<new-access-token>",
  "refreshToken": "<new-refresh-token>",
  "dateOfExpiration": "2026-10-01T12:00:00Z"
}

Miridia then sends the new token in the next request.

OAuth activation

For an OAuth provider, the provider returns the user to an OAuth handler after sign-in. The handler then activates the configured provider in Miridia, with POST /api/Integrations/{configuredProviderId}/activate/callback. This request uses a service token that Miridia issues to the handler, not a business API key. Contact us if your connector needs this step.

Long operations: use a callback

Do not keep the Miridia request open while a slow operation runs. Reply at once with a 2xx status, and do the work in the background. When the work is complete, send the result to the matching callback request.

Carrier quotations use this pattern:

1. A user creates a shipment in Miridia.
2. Miridia sends the GenerateShipmentQuotation request to each connected carrier connector.
3. Each connector replies at once. Then it asks the carrier for a price.
4. When the carrier answers, the connector sends the quotation to POST /api/v1/integration/shipments/quotations.
5. The quotation shows on the shipment, and Miridia raises the OnShipmentQuotationGenerated event.

Add a provider or an operation

To add a provider in a domain that exists, these steps are necessary. No Miridia release is necessary.

1. Add the provider to the catalogue, with its configuration type (for example OAuth or API key) and its configuration keys.
2. Bind a connector address to each workflow title that the provider supports.
3. Build and deploy the connector.

To add a new operation, a new workflow title and new request and response shapes are necessary. This is a change to Miridia. Contact us to plan it.

Test a connector

• Test each workflow title with a sample request that has all the headers above.
• Make sure that the connector returns a non-2xx status code when the provider fails. A 2xx status code with an empty body gives an empty record in Miridia.
• For a callback flow, test the complete loop: the request from Miridia, the reply, and the callback.

Related pages

• Integrations overview
• Workflows and events
• Integrations API reference
• Order integration API reference