Welcome

We blend strategy, design and engineering to build intelligent systems that help businesses in Saudi Arabia and the GCC grow and stand out.

Urwa

One API that connects any system to e-invoicing, WhatsApp, online stores and payments

  • A Shfrah product
  • Integration
  • SaaS
  • At a glance

Sector

Integration

Platforms

Web · REST API · SDKs · Webhooks

Modules

8

Integrations

8

Screens

4

Total duration

22 weeks

Urwa connects any system — ERP, POS, e-commerce, hospital or government — to ready-made connectors over one REST API: ZATCA e-invoicing, WhatsApp Business, Salla, Zid, Foodics, payments, SMS, Nafath and the SPL National Address. The platform handles signing, retries, observability and usage metering, so engineering teams build each integration once and ship it with confidence.

Urwa: screen 1
Operations console: requests per minute, error rate, latency and the health of every connector on one screen.
  • Challenge

  1. 01

    Every system builds its own ZATCA Fatoora integration from scratch — certificates, signing, the hash chain and QR — then breaks on the next spec update.

  2. 02

    WhatsApp, marketplace and payment integrations are rebuilt in every project, with scattered keys, inconsistent data formats and no shared documentation.

  3. 03

    Webhooks are lost whenever the receiving system is down, with no retries and no record of what was sent and when.

  4. 04

    When a provider fails, the team cannot tell whether the fault lies in its own system, the integration or the provider, and diagnosis drags on for hours.

Who it is built for

  • CTO

    Reliable integrations with clear security controls, without a dedicated team per provider

  • Integration developer

    Clear docs, a sandbox and test keys to get going in the first hour

  • Site reliability engineer

    A log and a trace for every request, and alerts before customers notice

  • Tax compliance officer

    The ZATCA status of every invoice and the reason for any rejection, in one place

  • Software vendor (ISV)

    Offers integrations to its own customers under its brand, with full tenant isolation and usage-based billing

  • Modules

What the system does

Connected modules working on one set of data.

  • 01

    Ready connectors

    ZATCA, WhatsApp, Salla, Zid, Foodics, payments, SMS, Nafath and National Address behind one data schema

  • 02

    E-invoicing engine

    UBL 2.1 generation, hashing, stamping, counters and QR; clearance or reporting; CSID onboarding and renewal

  • 03

    Unified API & SDKs

    OpenAPI 3.1 REST, Node.js, Python, Java, .NET and PHP SDKs, and idempotency keys

  • 04

    Webhooks

    HMAC signatures, exponential-backoff retries and a dead-letter queue with manual replay

  • 05

    Keys & access

    API keys and OAuth 2.0 clients with scopes, plus per-tenant rate limits and quotas

  • 06

    Observability

    Per-request logs, OpenTelemetry traces, and error rate and latency per connector

  • 07

    Developer portal

    Interactive docs, a sandbox, test credentials and simulated provider errors

  • 08

    Metering & billing

    Counts requests, invoices and messages per tenant, with price plans and a monthly bill

Where the AI works

  • AI · 01

    A private in-Kingdom language model explains ZATCA validation messages such as BR-CO-15 and BR-KSA-37 in plain language and points to the field to fix.

  • AI · 02

    Anomaly detection on per-connector error rate, latency and volume alerts on unusual drift before a static threshold trips.

  • AI · 03

    A mapping assistant proposes how fields in the customer system map to the unified schema, from field names and sample payloads.

  • AI · 04

    A developer-portal assistant answers from the docs and generates code samples in the language the developer uses.

  • Screens

The system as the client's team and customers use it.

Urwa: screen 2
E-invoice log: the ZATCA status of each invoice, why it was held or rejected, its request path and a suggested fix.
Urwa: screen 3
Developer portal: sandbox keys, a ready SDK sample and the sandbox request log, from sign-up to the first invoice.
Urwa: screen 4
Webhooks: every delivery signed, retried with exponential backoff, and a dead-letter queue replayed in one click.
  • Architecture

Independent services, in-Kingdom data, and integrations over documented APIs.

Channels

  • Customer systems: ERP, POS & stores
  • SDKs: Node, Python, Java & .NET
  • Console & portal: Ops console & dev portal

Edge

  • API gateway: TLS & per-tenant rate limits
  • Auth server: API keys & OAuth 2.0

Services

  • Connector runtime: Mapping & provider calls
  • E-invoicing engine: UBL, stamping & clearance
  • Webhook dispatcher: Signing & retries
  • Metering & billing: Usage & monthly bills

AI

  • Anomaly detection: Error & latency drift
  • Fix assistant: Explains rejections
  • Mapping assistant: Field mapping

Data

  • PostgreSQL: Tenants, config & invoices
  • Kafka: Events & delivery queues
  • ClickHouse: Request logs & traces
  • Vault · HSM: CSIDs & private keys

Integrations

  • ZATCA Fatoora: Clearance & reporting
  • WhatsApp Cloud API: Messages & templates
  • Salla · Zid · Foodics: Orders & catalog
  • Payments · SMS: Payment provider & SMS
  • Nafath · SPL: Identity & National Address

Connections

  • Customer systems to API gateway: REST
  • SDKs to API gateway: HTTPS
  • Console & portal to API gateway
  • SDKs to Auth server: OAuth
  • Console & portal to Auth server
  • API gateway to Connector runtime
  • API gateway to E-invoicing engine
  • API gateway to Metering & billing: usage
  • Connector runtime to Kafka: events
  • Connector runtime to ClickHouse: logs
  • E-invoicing engine to Vault · HSM: sign
  • E-invoicing engine to PostgreSQL
  • E-invoicing engine to Fix assistant
  • Connector runtime to Anomaly detection
  • Connector runtime to Mapping assistant
  • Webhook dispatcher to Kafka: consume
  • Metering & billing to ClickHouse
  • Anomaly detection to ClickHouse
  • E-invoicing engine to ZATCA Fatoora: REST
  • Connector runtime to WhatsApp Cloud API
  • Connector runtime to Salla · Zid · Foodics
  • Connector runtime to Payments · SMS
  • Connector runtime to Nafath · SPL

Stack

  • Go
  • NestJS
  • Next.js
  • PostgreSQL
  • Redis
  • Kafka
  • ClickHouse
  • OpenTelemetry
  • Kubernetes
  • Vault · HSM
  • Workflow

An e-invoice through Urwa

  1. 01

    The system sends the invoice in the unified schema

    Customer systemREST API · SDK

  2. 02

    Key, scope and rate-limit check

    AutomaticAPI gateway

  3. 03

    Map to UBL 2.1 and pre-validate business rules

    AutomaticE-invoicing engine

  4. 04

    Hash, counter and chain; stamp simplified invoices

    AutomaticVault · HSM

  5. 05

    Clearance for standard, reporting for simplified

    AutomaticZATCA Fatoora

  6. 06

    Store the cleared invoice and QR

    AutomaticPostgreSQL · Object storage

  7. 07

    Signed webhook to the system, with retries

    AutomaticWebhook dispatcher

  8. 08

    Review, fix and resubmit held or rejected invoices

    Compliance officerConsole · Fix assistant

  9. 09

    Meter usage into the monthly bill

    AutomaticMetering

  • Data & API

The core entities and relations, and a live example from the API.

Tenant

  • iduuidPK
  • nametext
  • planenum
  • parent_iduuidFK
  • rate_limit_rpmint
  • statusenum
  • created_attimestamptz

ApiCredential

  • iduuidPK
  • tenant_iduuidFK
  • kindenum(api_key,oauth_client)
  • prefixtext
  • secret_hashtext
  • scopestext[]
  • envenum(sandbox,live)
  • last_used_attimestamptz
  • revoked_attimestamptz

Connection

  • iduuidPK
  • tenant_iduuidFK
  • connectorenum
  • configjsonb
  • secret_reftext
  • statusenum
  • health_checked_attimestamptz

EgsUnit

  • iduuidPK
  • connection_iduuidFK
  • serialtext
  • csid_reftext
  • csid_expires_attimestamptz
  • icvbigint
  • last_hashtext

EInvoice

  • iduuidPK
  • egs_unit_iduuidFK
  • uuiduuidunique
  • numbertext
  • typeenum(standard,simplified,credit,debit)
  • icvbigint
  • hashtext
  • statusenum
  • zatca_messagesjsonb

RequestLog

  • idtextPK
  • tenant_iduuid
  • connection_iduuid
  • methodtext
  • pathtext
  • statussmallint
  • latency_msint
  • trace_idtext
  • attimestamptz

WebhookEndpoint

  • iduuidPK
  • tenant_iduuidFK
  • urltext
  • eventstext[]
  • secret_reftext
  • activebool

WebhookDelivery

  • idtextPK
  • endpoint_iduuidFK
  • eventtext
  • payload_reftext
  • attemptsmallint
  • response_codesmallint
  • next_retry_attimestamptz
  • statusenum(delivered,retrying,dead)
  • Tenant 1—∞ ApiCredential
  • Tenant 1—∞ Connection
  • Connection 1—∞ EgsUnit
  • EgsUnit 1—∞ EInvoice
  • Connection 1—∞ RequestLog
  • Tenant 1—∞ WebhookEndpoint
  • WebhookEndpoint 1—∞ WebhookDelivery
POST /v1/einvoices Issue an e-invoice, then clear or report it

Request

{
  "type": "standard",
  "egs_unit": "EGS-RYD-03",
  "number": "INV-26-118402",
  "issue_date": "2026-11-08",
  "issue_time": "11:02:40",
  "buyer": {
    "vat_number": "310122393500003",
    "national_address": {
      "building_no": "7421",
      "additional_no": "3184",
      "street": "King Fahd Rd",
      "district": "Al Olaya",
      "city": "Riyadh",
      "postal_code": "12214"
    }
  },
  "lines": [
    { "sku": "SRV-0042", "qty": 12, "unit_price": 3500.00, "vat_category": "S" }
  ]
}

Response

{
  "id": "einv_01M6Q8JX2T",
  "number": "INV-26-118402",
  "status": "cleared",
  "icv": 118402,
  "uuid": "6f4c1e2a-8b3d-4c7e-9a51-2d0f7b3e9c14",
  "hash": "q0Yb3Jp8…Z1k=",
  "totals": { "net": 42000.00, "vat": 6300.00, "gross": 48300.00 },
  "zatca": { "clearance_status": "CLEARED", "warnings": [] },
  "qr": "AQ1TYW1wbGUgU2VsbGVy…",
  "cleared_xml_url": "/files/einv/01M6Q8JX2T.xml"
}

Webhook event · einvoice.cleared

{
  "event": "einvoice.cleared",
  "id": "evt_01M6Q8K2V7",
  "einvoice": "INV-26-118402",
  "egs_unit": "EGS-RYD-03",
  "clearance_status": "CLEARED",
  "gross": 48300.00,
  "currency": "SAR",
  "at": "2026-11-08T11:02:42+03:00"
}
  • Integrations

  • ZATCA Fatoora

    Clearance and reporting in the integration phase, plus CSID onboarding

  • WhatsApp Business Cloud API

    Template messages, conversations, delivery and read receipts

  • Salla · Zid

    Orders, products and stock from online stores

  • Foodics

    POS orders, menus and branches for restaurants

  • Payment provider

    mada, Apple Pay and STC Pay through a SAMA-licensed payment provider

  • SMS gateways

    OTPs and notifications with sender names registered with CST

  • Nafath

    Sign-in and identity verification through the National Single Sign-On

  • SPL National Address

    National Address lookup and validation for shipping and invoices

  • Security & compliance

  • Data, logs and backups hosted inside the Kingdom.
  • National Cybersecurity Authority Essential Cybersecurity Controls (ECC) and Cloud Cybersecurity Controls (CCC).
  • Private keys and CSIDs stay in an HSM or Vault and are never exported, with scheduled rotation.
  • Full tenant isolation across data, keys and rate limits.
  • Every webhook signed with HMAC-SHA256 and a timestamp to block replay attacks.
  • Personal Data Protection Law (PDPL) alignment, with ID and mobile numbers masked in logs.
  • API keys stored only as hashes, and an immutable audit trail for every configuration change.
  • Delivery plan

Clear phases with measurable deliverables.

  1. 01

    Discovery & integration inventory

    • Inventory of systems, providers and volumes
    • Unified schema and security requirements
    2 weeks
  2. 02

    Architecture & API design

    • OpenAPI spec and error model
    • Multi-tenancy and key management design
    3 weeks
  3. 03

    Core & e-invoicing

    • Gateway, identity and webhooks
    • E-invoicing engine and compliance checks in the ZATCA sandbox
    7 weeks
  4. 04

    Connectors

    • WhatsApp, Salla, Zid, Foodics, payments and SMS
    • Nafath and National Address
    5 weeks
  5. 05

    Observability & developer portal

    • Logs, traces and alerts
    • Docs, sandbox and SDKs
    3 weeks
  6. 06

    Load testing & go-live

    • Load and penetration testing
    • Phased migration of systems
    2 weeks
Total duration
22 weeks
Team
Project manager, solutions architect, 3 backend engineers, a frontend engineer, an SRE/DevOps engineer, and a QA and security tester.

Performance

  • 99.95% API availability
  • < 80 ms Platform overhead at p95, excluding provider time
  • 99.99% Webhooks delivered after retries
  • < 15 min Sign-up to first successful sandbox call

Related work

All work

Have a similar project?

Start a project
Contact us