Urwa
One API that connects any system to e-invoicing, WhatsApp, online stores and payments
-
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.

-
Challenge
-
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.
-
02
WhatsApp, marketplace and payment integrations are rebuilt in every project, with scattered keys, inconsistent data formats and no shared documentation.
-
03
Webhooks are lost whenever the receiving system is down, with no retries and no record of what was sent and when.
-
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.



-
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
-
01
The system sends the invoice in the unified schema
Customer systemREST API · SDK
-
02
Key, scope and rate-limit check
AutomaticAPI gateway
-
03
Map to UBL 2.1 and pre-validate business rules
AutomaticE-invoicing engine
-
04
Hash, counter and chain; stamp simplified invoices
AutomaticVault · HSM
-
05
Clearance for standard, reporting for simplified
AutomaticZATCA Fatoora
-
06
Store the cleared invoice and QR
AutomaticPostgreSQL · Object storage
-
07
Signed webhook to the system, with retries
AutomaticWebhook dispatcher
-
08
Review, fix and resubmit held or rejected invoices
Compliance officerConsole · Fix assistant
-
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
/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.
-
01
Discovery & integration inventory
- Inventory of systems, providers and volumes
- Unified schema and security requirements
2 weeks -
02
Architecture & API design
- OpenAPI spec and error model
- Multi-tenancy and key management design
3 weeks -
03
Core & e-invoicing
- Gateway, identity and webhooks
- E-invoicing engine and compliance checks in the ZATCA sandbox
7 weeks -
04
Connectors
- WhatsApp, Salla, Zid, Foodics, payments and SMS
- Nafath and National Address
5 weeks -
05
Observability & developer portal
- Logs, traces and alerts
- Docs, sandbox and SDKs
3 weeks -
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
