| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Contacts (contacts)
• Discuss (mail) • Invoicing (account) |
| Lines of code | 2131 |
| Technical Name |
eh_l10n_sa_address |
| License | OPL-1 |
| Website | https://www.erpheritage.com.au/ |
| Versions | 17.0 18.0 19.0 |
| Availability |
Odoo Online
Odoo.sh
On Premise
|
| Odoo Apps Dependencies |
•
Contacts (contacts)
• Discuss (mail) • Invoicing (account) |
| Lines of code | 2131 |
| Technical Name |
eh_l10n_sa_address |
| License | OPL-1 |
| Website | https://www.erpheritage.com.au/ |
| Versions | 17.0 18.0 19.0 |
Saudi National Address
Authoritative SPL endpoint on .gov.sa wired into every contact. Type the four-letter four-digit short address, click Fetch, every structured field populates. CR-based partner enrichment via Wathq API 17 lands the registered national address with a single click.
يتصل مباشرة بنقطة النهاية الرسمية للعنوان الوطني SPL على نطاق .gov.sa. اكتب العنوان المختصر المكون من أربعة أحرف وأربعة أرقام، انقر على زر الجلب، تمتلئ كل الحقول المهيكلة. إثراء بيانات الشريك من خلال رقم السجل التجاري عبر واجهة Wathq رقم 17 يجلب العنوان الوطني المسجل بنقرة واحدة.
Olaya 12345
Riyadh, Saudi Arabia
24.7136, 46.6753
Day in the life / يوم في الحياة العملية
A vendor onboarding lands on the AP clerk's queue. Twelve seconds later it is verified.
يصل تسجيل مورد جديد إلى قائمة موظف الحسابات الدائنة. بعد اثنتي عشرة ثانية، يكون موثوقاً.
Step 1. AP clerk pastes the vendor's 10-digit Commercial Registration into the partner form.
Step 2. Clerk clicks Lookup from CR. The Wathq API 17 returns the registered national address; the structured fields populate; an SPL verify runs in the same transaction.
Step 3. Verification badge flips to Verified. Building, secondary, postal, district, city, region all written. Audit row stamped, response hashed, API key redacted.
Step 4. Next bill from that vendor inherits the verified address straight onto the ZATCA Phase 2 XML. No retyping. No quality review.
الخطوة الأولى: يلصق موظف الحسابات الدائنة رقم السجل التجاري المكوّن من عشرة أرقام في نموذج الشريك.
الخطوة الثانية: ينقر على البحث بالسجل التجاري. تُرجع واجهة Wathq رقم 17 العنوان الوطني المسجَّل، تُملأ الحقول المهيكلة تلقائياً، ويجري التحقق من SPL في المعاملة ذاتها.
الخطوة الثالثة: تتحول شارة التحقق إلى موثوق. يُكتب رقم المبنى، الرقم الإضافي، الرمز البريدي، الحي، المدينة، والمنطقة. يُسجَّل صف التدقيق، يُحسب هاش الاستجابة، ويُخفى مفتاح الواجهة.
الخطوة الرابعة: تَرث الفاتورة التالية من المورد نفسه العنوان الموثوق مباشرةً إلى XML المرحلة الثانية من فوترة الزكاة. بلا إعادة كتابة. بلا مراجعة جودة.
Overview / نظرة عامة
What this module does, in one read.
ما يفعله هذا التطبيق، باختصار.
Connects Odoo partner records to the authoritative SPL National Address service on the .gov.sa runtime endpoint. Type the four-letter four-digit short address, click Fetch, the building number, street, secondary number, postal code, district, city, region, latitude and longitude populate from the live response.
يربط سجلات الشركاء في أودو بخدمة العنوان الوطني الرسمية SPL على نقطة النهاية .gov.sa. اكتب العنوان المختصر، انقر على زر الجلب، وتُملأ تلقائياً جميع الحقول: رقم المبنى، الشارع، الرقم الإضافي، الرمز البريدي، الحي، المدينة، المنطقة، خط الطول وخط العرض.
Adds a second one-click flow on the Commercial Registration number that calls Wathq API 17 to fetch the registered business address from the Ministry of Commerce open-data platform, then runs SPL verify in the same transaction so the partner lands in the Verified state with one motion.
يضيف تدفقاً ثانياً بنقرة واحدة عبر رقم السجل التجاري الذي يستدعي واجهة Wathq رقم 17 لجلب العنوان المسجَّل لنشاط الأعمال من منصة البيانات المفتوحة لوزارة التجارة، ثم يُجري التحقق من SPL في المعاملة نفسها حتى يستقر الشريك في حالة "موثوق" بحركة واحدة.
Caches region, city, and district master data on-demand from the live endpoint; never pre-seeded, never stale. Weekly cron refreshes the cache, nightly cron re-verifies stale partner records.
يُخزن بيانات المناطق والمدن والأحياء عند الطلب من نقطة النهاية الحية؛ لا بيانات مسبقة الزرع، ولا بيانات قديمة. مهمة أسبوعية لتحديث المخزن، ومهمة ليلية لإعادة التحقق من سجلات الشركاء القديمة.
Capabilities / الإمكانيات
Twelve things this module ships, no filler.
اثنتا عشرة ميزة، دون حشو.
Short address resolution
One click on a partner. RIYD2342 in, the full structured address out, with district and region resolved by SPL id.
حل العنوان المختصر: نقرة واحدة على سجل الشريك. أدخل RIYD2342، يخرج العنوان المهيكل بالكامل مع تحديد الحي والمنطقة عبر معرّف SPL.
Structured verify
Building + postal + secondary number trio passes through the verify endpoint and lands in a typed verification state.
تحقق مهيكل: ثلاثية رقم المبنى والرمز البريدي والرقم الإضافي تمر عبر نقطة التحقق وتنتهي في حالة تحقق مكتوبة.
Wathq API 17 lookup
10-digit Commercial Registration to verified national address. Fills the partner and verifies in one click.
بحث Wathq رقم 17: رقم سجل تجاري من عشر خانات يتحول إلى عنوان وطني موثوق. يَملأ الشريك ويتحقق منه بنقرة واحدة.
Reverse geocode
Latitude and longitude resolve to the nearest National Address record via SPL POI nearest.
ترميز جغرافي عكسي: خط الطول والعرض يُترجمان إلى أقرب سجل عنوان وطني عبر خدمة أقرب نقطة اهتمام في SPL.
Free-text wizard
Type a landmark or street name; SPL returns paged results. Pick a row, click Apply, the wizard writes everything back.
معالج البحث الحر: اكتب اسم معلَم أو شارع؛ يُرجع SPL نتائج بصفحات. اختر صفاً، انقر "تطبيق"، يكتب المعالج كل شيء.
Live, never seeded
Regions, cities, and districts cache on first use from the .gov.sa endpoint. New districts published by SPL appear the first time anyone touches them.
بيانات حية بلا زرع مسبق: تُخزَّن المناطق والمدن والأحياء عند أول استخدام من نقطة .gov.sa. الأحياء الجديدة التي يُصدرها SPL تظهر فور أول وصول إليها.
Append-only audit log
Every call writes: endpoint, request hash (key redacted), response hash, duration, user, timestamp. Refuses unlink. Refuses field writes.
سجل تدقيق غير قابل للحذف: كل استدعاء يُسجَّل: نقطة النهاية، هاش الطلب (مع إخفاء المفتاح)، هاش الاستجابة، المدة، المستخدم، الطابع الزمني. يرفض الحذف ويرفض تعديل الحقول.
Multi-company isolation
Per-company API keys, per-company cache, per-company audit. Three legal entities on one database keep their licences clean.
عزل متعدد الشركات: مفاتيح واجهة لكل شركة، مخزن لكل شركة، تدقيق لكل شركة. ثلاث جهات قانونية على قاعدة بيانات واحدة تحتفظ بتراخيصها منفصلة.
English plus Arabic
SPL serves region, city, and district names in either language. Cached rows carry both; the operator switches without invalidating data.
إنجليزي وعربي: يقدم SPL أسماء المناطق والمدن والأحياء بأي من اللغتين. الصفوف المُخزَّنة تحمل كلتيهما؛ المُشغل يبدل دون إبطال البيانات.
Sliding-window rate guard
Per company, per provider. Stops a tight-loop misclick from burning the daily quota.
حارس معدل بنافذة منزلقة: لكل شركة ولكل مزوّد. يمنع نقرات الخطأ المتكررة من استهلاك الحصة اليومية.
Auto re-verify cron
Nightly sweep re-runs verify on partners whose verification is older than the configured threshold; mismatches raise an activity.
إعادة تحقق تلقائية: مسح ليلي يعيد التحقق من الشركاء الذين تجاوز تحققهم العتبة المُعدَّة؛ حالات عدم التطابق ترفع نشاطاً.
ZATCA-ready dict
One method (_eh_sa_invoice_address_dict) returns the structured dict the e-invoice XML needs. No re-derivation from free text.
قاموس جاهز للزكاة الإلكترونية: طريقة واحدة (_eh_sa_invoice_address_dict) تُرجع القاموس المهيكل الذي يحتاجه XML الفاتورة الإلكترونية. بلا إعادة استخراج من نص حر.
Compared / مقارنة
Why this module outperforms a generic address connector.
لماذا يتفوق هذا التطبيق على أي موصِّل عناوين عام.
| Capability / الإمكانية | Generic connector / موصِّل عام | ERP Heritage Saudi National Address |
|---|---|---|
| Authoritative source / مصدر رسمي | Third-party reseller | .gov.sa runtime endpoint, direct |
| Short address one-click / عنوان مختصر بنقرة | Free-text only | Yes / نعم |
| CR-driven enrichment via Wathq / إثراء بالسجل التجاري عبر Wathq | Not included | API 17 wired |
| Master data refresh / تحديث البيانات الأساسية | Pre-seeded XML, rots fast | Live fetch + weekly refresh cron |
| Audit trail / مسار التدقيق | Application log only | Append-only DB table, key redaction |
| Multi-company / متعدد الشركات | Shared key | Per-company keys + isolation rules |
| Rate-limit guard / حد المعدل | None | Sliding window, per provider |
| Stale verification re-check / إعادة فحص التحقق القديم | Manual only | Nightly cron with mismatch activity |
| ZATCA Phase 2 hook / خطّاف فوترة الزكاة المرحلة الثانية | Re-derive from free text | Structured dict method ready |
No vendor names. The comparison is against the category, not any specific publisher.
بدون ذكر أسماء بائعين. المقارنة مقابل الفئة، وليس مقابل ناشر بعينه.
Workflow / تدفق العمل
From short address to verified record in four states.
من العنوان المختصر إلى السجل الموثوق في أربع حالات.
Default state. Operator has typed a short address, a CR number, or no input. Buttons are visible.
الحالة الافتراضية. كَتب المُشغل عنواناً مختصراً أو رقم سجل تجاري أو لم يدخل شيئاً. الأزرار ظاهرة.
SPL confirmed the record. Verified-at timestamp set. Response hash stored. Audit row written.
أكَّد SPL السجل. وقت التحقق مُسجَّل. هاش الاستجابة محفوظ. صف التدقيق مكتوب.
SPL returned a record but the structured fields disagree. Activity raised so the data team triages.
أرجع SPL سجلاً لكن الحقول المهيكلة لا تتطابق. يُرفع نشاط ليفرز فريق البيانات.
SPL had no record. Operator sees a clean message; no fields are silently mutated.
لا سجل لدى SPL. يظهر للمُشغل رسالة واضحة؛ لا تُعدَّل الحقول بصمت.
Why ERP Heritage / لماذا ERP Heritage
Engineered to the same bar as the rest of the suite.
مهندس بنفس معايير باقي المجموعة.
- One source of truth. Direct .gov.sa endpoint. No reseller in the path.
- Receipts on every call. Append-only audit table. SHA-256 of every response. Keys redacted.
- No noise. One menu, one form tab, two cron jobs. Zero email templates, zero notifications outside button clicks.
- Versions covered. Same code lineage shipped for Odoo 17.0, 18.0, and 19.0 at one price.
- Honest scope. ZATCA XML is wired through a hook, not a promise. The structured dict is ready; a downstream e-invoice module reads it.
- مصدر واحد للحقيقة. نقطة نهاية .gov.sa مباشرة. لا وسيط في المسار.
- إيصالات لكل استدعاء. جدول تدقيق غير قابل للحذف. SHA-256 لكل استجابة. المفاتيح مُخفاة.
- بلا ضوضاء. قائمة واحدة، علامة تبويب نموذج واحدة، مهمتان دوريّتان. لا قوالب بريد، لا إشعارات خارج النقرات.
- إصدارات مغطاة. نفس الشيفرة تُشحن لـ أودو 17.0 و18.0 و19.0 بسعر واحد.
- نطاق صادق. XML فوترة الزكاة موصول عبر خطّاف، لا وعد. القاموس المهيكل جاهز؛ تطبيق إلكتروني لاحق يقرأه.
Engineering / الهندسة
What the inside looks like.
كيف يبدو من الداخل.
Typed REST errors
SplAuthError, SplBadRequest, SplNotFound, SplServerError, RateLimitExceeded. Each maps to a translated UserError at the UI boundary.
أخطاء REST مكتوبة. كل خطأ يتحول إلى UserError مترجم عند حدود الواجهة.
Envelope tolerance
Parsers accept the documented SPL key variants (Addresses, addresses, Address, Data, results) so a contract tweak does not break the flow.
تسامح مع تنويعات أغلفة الاستجابة. تعديل عقد SPL لا يكسر التدفق.
Test matrix
36 Odoo tests plus 60 static and mocked checks. Every endpoint asserts URL, headers, params, and parsed return.
36 اختبار أودو زائد 60 فحصاً ثابتاً ومحاكاً. كل نقطة نهاية تؤكد المسار والترويسات والمعطيات والإرجاع.
Frequently asked questions / أسئلة شائعة
Yes. Register at the SPL developer portal on .gov.sa to receive two keys (primary and secondary). Both are stored on the company record and sent on every call.
هل أحتاج إلى مفتاح SPL؟ نعم. سجِّل في بوابة المطورين على .gov.sa لاستلام مفتاحين (أساسي وثانوي). يُخزَّنان على سجل الشركة ويُرسلان مع كل استدعاء.
No, by design. Regions, cities, and districts are fetched live from SPL the first time anyone uses them, then cached. A weekly cron keeps the cache fresh.
هل يأتي التطبيق ببيانات أساسية للمملكة؟ لا، عمداً. تُجلب المناطق والمدن والأحياء حياً من SPL عند أول استخدام، ثم تُخزَّن. مهمة أسبوعية تحافظ على نضارة المخزن.
Wathq API 17 (National Address by Commercial Registration) is wired and optional. Skip the subscription key and only the CR-lookup button hides; the SPL flow keeps working.
وماذا عن Wathq؟ واجهة Wathq رقم 17 (العنوان الوطني عبر السجل التجاري) موصولة واختيارية. اترك مفتاح الاشتراك فارغاً ويختفي زر البحث بالسجل التجاري فقط؛ يستمر تدفق SPL في العمل.
Odoo Community 17.0, 18.0, and 19.0. The Apps Store lists each version separately at the same USD 50 price.
أي إصدارات أودو مدعومة؟ أودو المجتمعي 17.0 و18.0 و19.0. متجر التطبيقات يُدرج كل إصدار بشكل منفصل بنفس السعر 50 دولاراً.
No. This module produces the structured address that a ZATCA e-invoicing module reads, exposed as partner._eh_sa_invoice_address_dict(). The XML wire format ships in a separate addon.
هل يُولِّد XML المرحلة الثانية لفوترة الزكاة؟ لا. ينتج هذا التطبيق العنوان المهيكل الذي يقرأه تطبيق فوترة الزكاة الإلكتروني، عبر partner._eh_sa_invoice_address_dict(). تنسيق XML يُشحن في إضافة منفصلة.
Stored per company. Masked in the settings form. Redacted to *** in every audit row.
كيف تُحمى مفاتيحي؟ تُخزَّن لكل شركة. تُقنَّع في نموذج الإعدادات. تُخفى إلى *** في كل صف تدقيق.
Yes. Every API key, cache row, and audit row carries a company_id; isolation rules enforce it.
هل يعمل في بيئة متعددة الشركات؟ نعم. كل مفتاح، وكل صف مخزن، وكل صف تدقيق يحمل company_id؛ قواعد العزل تَفرضه.
Email info@erpheritage.com.au. Implementation, customisation, training, and ongoing support all available.
قناة الدعم؟ راسلنا على info@erpheritage.com.au. التطبيق، التخصيص، التدريب، والدعم المستمر متاحة جميعاً.
Built by ERP Heritage
ERP Heritage publishes a tested, opinionated Odoo Community accounting suite. Every module ships with regression tests, audit-grade logs, and visual consistency. This one is the localisation entry point for any KSA deployment in the suite.
من تطوير ERP Heritage
تنشر ERP Heritage مجموعة محاسبية مختبرة وذات رأي لأودو المجتمعي. كل تطبيق يأتي باختبارات انحدار، وسجلات تدقيق على معايير عالية، واتساق بصري. هذا التطبيق هو نقطة الدخول للتوطين في أي نشر سعودي ضمن المجموعة.
Install now. USD 50, every supported version.
Buy once for 17.0, 18.0, or 19.0. Same code lineage, same support inbox.
ثبِّت الآن. 50 دولاراً، لكل إصدار مدعوم.
اشترِ مرة واحدة لـ 17.0 أو 18.0 أو 19.0. نفس الشيفرة ونفس قناة الدعم.
Odoo Proprietary License v1.0 This software and associated files (the "Software") may only be used (executed, modified, executed after modifications) if you have purchased a valid license from the authors, typically via Odoo Apps, or if you have received a written agreement from the authors of the Software (see the COPYRIGHT file). You may develop Odoo modules that use the Software as a library (typically by depending on it, importing it and using its resources), but without copying any source code or material from the Software. You may distribute those modules under the license of your choice, provided that this license is compatible with the terms of the Odoo Proprietary License (For example: LGPL, MIT, or proprietary licenses similar to this one). It is forbidden to publish, distribute, sublicense, or sell copies of the Software or modified copies of the Software. The above copyright notice and this permission notice must be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Please log in to comment on this module