# Matjrah Developers Center

> Matjrah is a multi-store commerce platform. Partners can build public catalog apps, private invite-only apps, or merchant-owned direct API/Webhook integrations.

## Canonical links

- Developer Center: https://developers.matjrah.com/
- Select an integration path: https://developers.matjrah.com/integrations
- API reference: https://developers.matjrah.com/docs
- Guides index: https://developers.matjrah.com/guides
- Developer account and Sandbox guide: https://developers.matjrah.com/guides/developer-sandbox
- Public ERP app guide: https://developers.matjrah.com/guides/erp-app
- Private ERP app guide: https://developers.matjrah.com/guides/connect-erp
- General app guide: https://developers.matjrah.com/guides/general-app
- Public shipping/courier app guide: https://developers.matjrah.com/guides/courier-app
- Salla-to-Matjrah developer guide: https://developers.matjrah.com/guides/salla-to-matjrah
- Salla-to-Matjrah AI-agent playbook: https://developers.matjrah.com/agents/salla-to-matjrah.md
- Arabic visual ERP guide: https://developers.matjrah.com/guides/erp-integration/
- English visual ERP guide: https://developers.matjrah.com/guides/erp-integration/en/
- Arabic visual shipping guide: https://developers.matjrah.com/guides/shipping-integration/
- English visual shipping guide: https://developers.matjrah.com/guides/shipping-integration/en/
- Arabic merchant guide: https://help.matjrah.com/الاعدادات/دليل-ربط-متجرك-مع-أي-نظام-خارجي-عبر-api-و-webhooks

## Choose an integration path

1. ERP/accounting app: for ERP, accounting, WMS or inventory vendors serving many merchants. Build a public Normal/ERP app, or a private app for one store.
2. Shipping app: for courier and logistics providers creating AWBs, labels and tracking updates. Use the Shipping app type and shipping contract.
3. General app: for analytics, marketing, operations, automation and other partner products. Start with a Normal app and only the scopes the documented use case needs.
4. Merchant-owned connection: for one merchant connecting an existing internal or accounting system. Use a private app built by the vendor/implementer, or direct API + Webhooks from the merchant dashboard.

## Environments and Sandbox

- A Developer account manages apps; it is not a merchant store.
- The self-service Sandbox installation issues an isolated test token and delivers signed sample events to the app Webhook.
- The self-service Sandbox installation does not create a normal store domain, merchant-admin login, trial/paid subscription, or production tenant.
- Gateway reads and writes against orders, products, inventory or shipments require a provisioned active test store with seeded tenant data. Coordinate certification testing through dev@matjrah.com.
- A production merchant separately installs or approves the app and receives independent scopes and credentials. Never reuse Sandbox credentials in production.

## ERP examples

- Odoo: start with order.created to create a Sales Order, map products by SKU, then return stock and fulfillment updates.
- SAP Business One or SAP S/4HANA: use an integration service to map Matjrah orders and product identifiers to the relevant SAP documents and item codes.
- Microsoft Dynamics 365 or Business Central: use a service or Power Automate where appropriate, with explicit source-of-truth rules.
- Smaller/custom ERP: start with one order event and one safe inventory or status write before expanding.

These are implementation examples, not claims that an official ready-made app exists for every product.

## Familiar app-platform model

The distribution model is familiar to partners who already build for Salla and other commerce platforms: an app is registered once, reviewed, and installed separately by each merchant with explicit scopes and per-store credentials. Matjrah's endpoints, payloads, event names and authentication contract remain Matjrah-specific; do not copy another platform's API contract.

## Migrating a Salla app

Read https://developers.matjrah.com/agents/salla-to-matjrah.md before editing code. Preserve the existing Salla adapter during discovery, inventory its OAuth, endpoints, events, scopes and persistence, then add a separate Matjrah adapter around the shared business logic. Map behavior rather than endpoint names. Matjrah uses a signed app.installed lifecycle event and a per-store ait_ token, cursor pagination, raw-body HMAC-SHA256 Webhook verification and mandatory Idempotency-Key headers on writes. Anything outside the published Matjrah API must be reported as a gap rather than implemented against an invented contract.

## Focused 24-hour prototype

An experienced implementer using an AI coding assistant can often prototype a narrow Sandbox flow in one focused day: receive one order event, validate and deduplicate it, map one or a few SKUs, and perform one safe API operation. This is an MVP target, not a production guarantee. Production requires secure secret storage, idempotency, retries, rate/error handling, monitoring, tenant isolation and merchant acceptance testing.

Never send API keys, install tokens, customer data or production payloads to an AI tool unless the organization has approved that tool and its data controls.

## Support

- Integration support: mailto:dev@matjrah.com
- Partnerships call: https://calendly.com/matjrah/30min