Idarat Hisabat Al Mahal — API integration & OpenData services

1. Authentication & multi-tenant shops

إدارة حسابات المحل identifies each merchant by phone number; on login, the cloud backend restores the entire shop dataset. We mirror this into an /auth/phone + OTP flow that returns a signed token scoped to shop_id. Multi-branch owners get a listing endpoint to enumerate every branch and its employee roster, useful for franchises moving onto a centralized ERP.

2. Sales, purchase & return invoices

Invoice records carry header (customer/supplier, date, cashier, payment method), line items (SKU, qty, unit price, discount, tax), and totals. Our /invoices endpoint supports pagination, PDF re-rendering with the shop logo, and Bluetooth-printer payload export — directly reusable for ZATCA-compliant XML generation with embedded PDF/A-3.

3. Inventory & expiry alerts

Products searchable by name or QR scanner map to /products, /stock-movements, and a /expiry-alerts stream. Merchants who enable the optional 2-months-before-expiry warning, or the configurable low-stock threshold, produce event streams that downstream replenishment engines and dead-stock analytics can subscribe to.

4. Customers, suppliers & dunning

Receivables and payables are tracked per counterparty. Our /contacts and /statements endpoints surface balance aging, last-payment date, and the original SMS/WhatsApp reminder template used by the shop owner — enabling unified dunning workflows across a group of stores.

5. Cashier, expenses & payroll

Every withdrawal, deposit, expense category, and salary payment is a ledger row tied to a cashier session. We normalize them into an OpenFinance-style /transactions feed (amount, currency, category, counterparty, running balance) so SME finance teams can reconcile daily tills against bank statements.

6. Employee permissions & audit trail

The app lets shop owners grant per-employee access to invoices, inventory, or reports. We expose that RBAC matrix plus an audit log (who/when/what) through /employees and /audit-events, which plugs into SOC2-style review cycles and internal-control reporting for larger franchise owners.

Scenario A — ZATCA Phase 2 bridge for Saudi shops

Context: a SAR 375K+ turnover shopkeeper already using إدارة حسابات المحل must integrate with ZATCA's Fatoora portal before the 30 June 2026 wave deadline. We read invoice headers/lines from the app, build the required XML with UUID, cryptographic stamp, and sequential numbering, embed a PDF/A-3, and push to Fatoora via HTTPS. Involved data: sales + return invoices, tax lines, customer VAT number. This maps OpenData → national e-invoicing rail.

Scenario B — ERP & accounting handover

Context: a growing retailer is migrating from إدارة حسابات المحل to Daftra, Qoyod, Wafeq, Mezan or Zoho Books. Instead of re-keying thousands of invoices, we expose /invoices, /contacts, and /stock-movements and run a one-way replication job. This reuses the cloud-restore dataset and preserves full history, a classic OpenData portability use case.

Scenario C — Multi-branch consolidation

Context: a franchise owner runs 6–20 shops, each on a separate phone running إدارة حسابات المحل. We build a central backend that polls every shop_id, merges inventory and sales, and produces a consolidated P&L. Data involved: shop roster, daily sales aggregates, expense lines. Maps cleanly to an OpenFinance "multi-account" API shape.

Scenario D — WhatsApp / SMS dunning automation

Context: the app already lets owners send manual reminders to debtors via SMS or WhatsApp. We wrap /contacts + customer balance into a scheduled job that fires templated messages through the WhatsApp Business API, with configurable aging buckets (30/60/90 days). Involved data: customer ledger, overdue balances, preferred channel.

Scenario E — Cash-flow dashboard for lenders

Context: a MENA fintech lender wants a real read of SME cash flow before extending micro-loans. With merchant consent, we stream /transactions (sales, expenses, cashier movements) and /inventory turnover KPIs into the lender's risk engine. This mirrors OpenBanking-style "account information service provider" flows but on retail operations data rather than bank statements.

Request: authenticate a shop

POST /api/v1/mahal/auth/phone
Content-Type: application/json

{
  "phone": "+9665XXXXXXXX",
  "country": "SA",
  "device_id": "android-4f3a...",
  "otp_channel": "sms"
}

// 200 OK
{
  "shop_id": "mahal_8812",
  "access_token": "eyJhbGciOi...",
  "refresh_token": "rt_19f4...",
  "branches": [
    {"branch_id": "br_1", "name": "Main Store"},
    {"branch_id": "br_2", "name": "Warehouse"}
  ],
  "scopes": ["invoices:read","inventory:read","transactions:read"]
}

Request: pull sales invoices for ZATCA submission

GET /api/v1/mahal/invoices
  ?shop_id=mahal_8812
  &type=sale
  &from_date=2026-04-01
  &to_date=2026-04-30
  &page=1&page_size=100
Authorization: Bearer <ACCESS_TOKEN>

// 200 OK (excerpt)
{
  "data": [{
    "invoice_id": "inv_40021",
    "uuid": "9f2d3a8e-...-b7",
    "sequence": 4021,
    "issued_at": "2026-04-03T11:42:11+03:00",
    "customer": {"name":"Ali M.", "vat":"3000XXXXXX00003"},
    "lines": [
      {"sku":"8901234567890","qty":2,"unit_price":15.00,
       "tax_rate":0.15,"tax_amount":4.50}
    ],
    "totals": {"subtotal":30.00,"tax":4.50,"grand":34.50},
    "pdf_a3_url": "https://cdn.example.com/inv_40021.pdf"
  }],
  "next_page": 2
}

Webhook: low-stock & expiry alert

POST https://your-erp.example.com/hooks/mahal
X-Mahal-Signature: sha256=3f7c...
Content-Type: application/json

{
  "event": "inventory.alert",
  "shop_id": "mahal_8812",
  "branch_id": "br_1",
  "kind": "expiry_60d",
  "sku": "8900000123456",
  "name": "Yogurt 200g",
  "expiry_date": "2026-06-20",
  "current_stock": 38,
  "min_stock": 24,
  "generated_at": "2026-04-22T07:05:00Z"
}

// Retry policy: exponential back-off up to 24h
// Verify X-Mahal-Signature with HMAC-SHA256(secret, body)

Deliverables checklist

• OpenAPI 3.1 spec for all endpoints listed above
• Protocol & auth report (token lifetime, refresh behaviour, cloud-restore flow)
• Runnable server code in Python (FastAPI) or Node.js (NestJS)
• Connector libraries for Daftra, Qoyod, Wafeq, Zoho Books, Mezan
• ZATCA Phase 2 XML + PDF/A-3 packager and UBL 2.1 validator
• Test harness with fixture shops, fixture invoices, and signed webhooks
• Deployment notes (Docker, rate limits, observability, log retention)

Regulatory alignment

For Saudi Arabia we follow ZATCA's e-invoicing rules — Phase 1 (generation, live since December 2021) and Phase 2 (integration with the Fatoora portal, rolled out in waves through 2023–2026). Every ZATCA invoice we generate carries a UUID, cryptographic stamp, sequential number, and embedded PDF/A-3, as mandated by the Wave 24 regulations targeting SAR 375K+ turnover taxpayers. For UAE merchants, output formats are aligned with FTA VAT and emaraTax. Personal data handling respects the Saudi Personal Data Protection Law (PDPL, fully enforceable from September 2024) and, where a merchant serves European customers, the GDPR principles of minimization and purpose limitation.

Consent & scope control

Integrations only activate after the shop owner authorizes the scope — we implement explicit consent screens listing invoices, inventory, transactions, and contacts as separate toggles. Refresh tokens are revocable at any time, OTP logs are retained for 90 days, and we strip employee national IDs from API responses unless the merchant explicitly opts in. This keeps the studio aligned with a least-privilege, authorized-access model rather than bulk scraping.

Daftra

Cloud accounting suite for MENA SMEs across 50+ industries. Holds sales, purchase, inventory, and HR data; a frequent destination when a shop outgrows a phone-only ledger. Users typically want a unified transaction export between Daftra and إدارة حسابات المحل.

Qoyod

Saudi-based cloud accounting (launched 2016) with invoicing, inventory, and payroll. Integrates with Salla, Zid, and Jisr for web orders and GOSI. Cross-export of invoices from إدارة حسابات المحل into Qoyod is a common migration.

Wafeq

UAE-founded cloud accounting platform (Series A, $7.5M). Holds ledger, VAT returns, and bank feeds (Saudi Awwal Bank, Al Rajhi, HSBC, Wio). Shopkeepers often pair Wafeq's bank side with إدارة حسابات المحل's till side.

Mezan

Saudi-developed accounting platform designed around local regulations. Focuses on compliance and Arabic-first UX; a natural landing pad for a small shop moving from a single-phone ledger to a multi-user cloud book.

Zoho Books

Global accounting suite, FTA-approved in the UAE, with Arabic support. Holds invoices, bills, inventory, and banking; often receives exports from Arabic SME ledgers via CSV or API bridges like the one we build for إدارة حسابات المحل.

FirstBIT

FTA-approved ERP popular with UAE SMEs, with strong multi-warehouse inventory. When a retailer grows into multiple branches, we often bridge إدارة حسابات المحل data up into FirstBIT for consolidated reporting.

Cashier — ادارة حسابات المحلات

Another Arabic Android-first store accounting app (package com.ahmedelshazly2020d.sales_managers). Directly comparable feature set; owners sometimes keep both apps on separate branches and want consolidated reporting.

MicroPOS

POS-focused Android app for small shops. Holds product master, receipt journal, and cashier shift data. Teams integrating MicroPOS with ZATCA often reuse the same invoice-to-XML pipeline we build for إدارة حسابات المحل.

Vyapar

India-origin SME accounting & invoicing app with a large footprint in South Asia and growing MENA reach. Similar offline-first architecture; useful reference when designing sync and reconciliation flows for Arabic shops.

DEXEF & Wazen

Arabic desktop/cloud retail systems (DEXEF in Egypt, Wazen in Saudi) targeting larger shops and chains. Owners often consolidate data from إدارة حسابات المحل branches upward into DEXEF or Wazen for group-level financials.

About our studio

We are an independent technical studio specializing in App interface integration and authorized API integration. Our team combines mobile reverse engineering, payments, and SME accounting experience. For MENA retail work, we pay close attention to ZATCA, FTA, and the Saudi PDPL; for OpenFinance work, we lean on experience with ISO 20022, OAuth 2.0, and FAPI profiles.

• Protocol analysis of Android and iOS apps with compliant scope
• Open Data, Open Finance, and Open Banking adapters
• ERP connectors for Daftra, Qoyod, Wafeq, Zoho Books, Mezan, FirstBIT
• ZATCA Phase 2 XML/PDF-A/3 generation & Fatoora submission
• Source code delivery from $300 — runnable API source + docs, paid after delivery upon satisfaction
• Pay-per-call API billing — usage-based pricing, no upfront fee

Contact

Ready to turn إدارة حسابات المحل data into connected APIs? Share the target app name and your requirements and we will scope an engagement.

Open the contact page

Engagement models: fixed-scope source delivery (from $300) or hosted APIs billed per call.

Engagement workflow

1. Scope confirmation — which modules (invoices, inventory, transactions, contacts) and which destinations (ZATCA, ERP, BI).
2. Protocol analysis & API design — 2–5 business days depending on complexity.
3. Build and internal validation — 3–8 business days, including ZATCA sandbox round-trips where relevant.
4. Docs, samples, and test harness — 1–2 business days.
5. First delivery — usually 5–15 business days end-to-end; tax-authority approvals may extend timelines.

FAQ

What do you need from me?

How do you handle ZATCA Phase 2 specifically?

Is this authorized data access?