Intégration Ejar : ce que la PropTech saoudienne rate

Cherchez « Ejar API integration » et vous trouverez des articles qui listent des points de terminaison bien rangés : POST /contracts/register, GET /contracts/{ref}/payments, POST /disputes/file. Cela ressemble à de la documentation. Aucun de ces articles ne cite de source, car il n'existe aucune source publique à citer.

Ejar (شبكة إيجار), le réseau électronique qui encadre chaque contrat de location en Arabie Saoudite, ne publie pas de portail développeur. Pas de page d'inscription, pas de clé sandbox, pas de spécification OpenAPI téléchargeable cet après-midi. Le compte X officiel de la plateforme répond directement à la question : pour toute liaison API entre Ejar et une autre plateforme, écrire à keyaccounts@nhc.sa. C'est l'intégralité de la voie publiée.

Cela compte plus qu'il n'y paraît. Si vous construisez ou achetez un logiciel de gestion locative pour le marché saoudien, c'est le modèle d'accès qui détermine l'architecture, et non l'inverse. Les équipes qui partent du principe « on appellera simplement l'API » construisent un système dont l'hypothèse fondatrice s'effondre au moment de la revue du contrat, six mois plus tard.

Le volume qui fait de ce sujet un vrai marché

Ejar a enregistré plus de 10 millions de contrats de location depuis son lancement, à un rythme d'environ 19 000 nouveaux contrats par jour. La répartition : 8,3 millions de contrats résidentiels (82,3 %) contre 1,7 million de contrats commerciaux (17,6 %). Depuis le début 2024 seulement, plus de 1,5 million de contrats ont été documentés — 1,2 million en résidentiel et 283 000 en commercial.

Ce sont les chiffres face auxquels un éditeur de logiciel de gestion locative se positionne. Un portefeuille de 500 unités génère de l'ordre de 40 enregistrements et 30 renouvellements par mois, chacun étant une session multi-étapes sur le portail qu'une personne exécute à la main — alors que les mêmes données existent déjà dans le système de l'entreprise. Le besoin est réel. La seule question est celle du câblage.

Ejar n'a pas d'API publique — concevez en conséquence

La voie d'intégration officielle est un programme, pas une inscription. Ejar opère un parcours d'intégration numérique avec les plateformes immobilières et les systèmes de gestion de biens, annoncé publiquement en 2022 avec une première cohorte de douze plateformes et élargi depuis. Des éditeurs comme Simaat annoncent leur accord de liaison technique comme une étape majeure — ce qui vous renseigne sur sa nature : un arrangement commercial et réglementaire, pas un identifiant en libre-service.

Trois conséquences en découlent, et chacune est une décision d'architecture :

Vous ne pouvez pas prototyper sur la production. L'environnement de test éventuel s'octroie, il ne se découvre pas. Votre plan de développement doit prévoir une phase où l'adaptateur Ejar est un bouchon alimenté par un jeu de fixtures vérifiées à la main — et il faut dire franchement aux décideurs que ces fixtures sont votre hypothèse, pas le contrat réel.

La surface d'API ne vous appartient pas. Quiconque vous montre des corps de requête Ejar exacts dans un billet public viole un accord ou les a inventés. Traitez ces articles comme du marketing, pas comme une référence. Quand le vrai kit d'intégration arrivera, attendez-vous à ce qu'il diffère de chacune de vos suppositions.

L'éligibilité précède le code. L'intégration s'adresse à une activité immobilière licenciée. Le courtier ou l'entité de courtage a besoin d'un enregistrement REGA valide, d'un registre de commerce en cours de validité et de comptes authentifiés via Nafath. C'est le même modèle d'accès que pour Etimad, Muqeem et SIMAH : l'agrément conditionne les identifiants, et les identifiants conditionnent le code.

La posture de planification honnête : comptez 8 à 16 semaines entre le premier contact et des identifiants fonctionnels, et construisez le système de sorte qu'il produise de la valeur avec un humain dans la boucle pendant toute cette période.

Règle de conception : Ejar est le registre de référence

L'erreur la plus coûteuse dans les logiciels de gestion locative saoudiens consiste à traiter sa propre base de données comme la source de vérité du bail.

Elle ne l'est pas. Un contrat non enregistré n'est pas un titre exécutoire — il ne peut pas être porté directement devant le tribunal d'exécution, et il n'est pas accepté pour le Compte Citoyen ni pour la sécurité sociale développée. L'objet juridique, c'est le contrat Ejar, identifié par son numéro de contrat. Votre base de données porte l'état opérationnel autour de lui : tickets de maintenance, statut de recouvrement, communication locataire, écritures comptables.

Cette distinction doit être visible dans le schéma. Une ligne de bail sans ejar_contract_number est un brouillon, pas un bail, et votre code doit refuser de facturer dessus :

type LeaseState =
  | { kind: "draft"; localId: string }
  | { kind: "submitted"; localId: string; submittedAt: Date }
  | { kind: "awaiting_parties"; localId: string; ejarRef: string }
  | { kind: "registered"; localId: string; ejarRef: string; startsOn: Date; endsOn: Date }
  | { kind: "terminated"; localId: string; ejarRef: string; terminatedOn: Date };
 
function canIssueRentInvoice(lease: LeaseState): boolean {
  // Seul un contrat enregistré chez Ejar est un instrument juridique facturable.
  return lease.kind === "registered";
}

L'état awaiting_parties est celui que les équipes oublient. L'enregistrement n'est pas un appel atomique unique : le contrat est saisi, puis le bailleur et le locataire reçoivent une notification SMS et doivent l'authentifier électroniquement — et c'est seulement alors que la documentation s'achève. Votre machine à états doit survivre à un contrat bloqué plusieurs jours parce qu'un locataire n'a pas ouvert un SMS. Modélisez cet état explicitement, exposez-le dans l'interface et donnez aux opérations une action de relance. Ne le cachez pas derrière un spinner.

Les règles 2026 qui cassent votre logique de renouvellement

La plupart des logiciels de gestion locative livrent un module de renouvellement qui suppose deux choses : que les baux expirent, et que le loyer augmente. Les deux hypothèses sont désormais fausses en Arabie Saoudite, et un système qui se trompe silencieusement là-dessus expose son client à des amendes.

Les baux se renouvellent automatiquement. À l'échelle du Royaume, un bail se reconduit sauf si une partie notifie par écrit son non-renouvellement au moins 60 jours avant l'échéance. Un flux de renouvellement qui démarre à échéance moins 30 jours est déjà trop tardif pour servir à quoi que ce soit. C'est la fenêtre de préavis, et non la date d'expiration, qui doit déclencher votre planificateur.

Le loyer à Riyad est gelé. Un gel de cinq ans sur les prix des locations résidentielles et commerciales dans la zone urbaine de Riyad est entré en vigueur le 25 septembre 2025 et court jusqu'au 24 septembre 2030. Le loyer en vigueur à cette date lie les baux nouveaux comme existants. Les clauses d'indexation présentes dans les contrats existant au 25 septembre 2025 restent exécutoires ; les contrats conclus après cette date ne peuvent pas prévoir d'augmentation pendant le gel. Le loyer de sous-location ne peut excéder celui du bail principal. Le conseil de la REGA peut étendre ces mesures à d'autres villes avec l'accord du Conseil des affaires économiques et du développement — coder « Riyad » en dur comme cas particulier est donc un piège de maintenance. Faites-en une table de politiques indexée par région, avec une plage de dates d'effet.

Les motifs de refus de renouvellement sont limitativement énumérés. À Riyad, un bailleur ne peut refuser le renouvellement que pour des motifs précis : défaut de paiement du locataire, défauts structurels de sécurité étayés par des rapports techniques, occupation par le bailleur lui-même ou par un parent au premier degré, ou d'autres cas déterminés par la REGA. Si votre produit propose un bouton « ne pas renouveler », il lui faut un code de motif, et ce code doit être stocké. C'est la preuve de votre client.

Les sanctions ne sont pas symboliques. Les infractions aux règles de gel et de renouvellement sont passibles d'amendes pouvant atteindre douze mois de loyer du bien, assorties d'obligations de régularisation et d'indemnisation des parties lésées, avec un délai de recours de 30 jours. Par ailleurs, une agence qui n'enregistre pas les contrats encourt, au titre de la réglementation des bureaux immobiliers, jusqu'à 25 000 SAR d'amende, une fermeture pouvant aller jusqu'à un an, ou le retrait de licence. S'y ajoute une prime au signalement : un informateur peut percevoir jusqu'à 20 % des amendes recouvrées. L'ancien locataire mécontent de votre client a donc une raison financière de dénoncer un renouvellement irrégulier.

Voici la forme que doit réellement prendre la règle côté planificateur :

interface RenewalPolicy {
  region: string;              // "riyadh_urban", "makkah", ...
  effectiveFrom: Date;
  effectiveTo: Date | null;
  escalationAllowed: boolean;  // false pendant une fenêtre de gel des loyers
  noticeDays: number;          // 60 à l'échelle du Royaume aujourd'hui
}
 
function renewalNoticeDeadline(endsOn: Date, policy: RenewalPolicy): Date {
  const d = new Date(endsOn);
  d.setDate(d.getDate() - policy.noticeDays);
  return d;   // alertez les opérations ici, pas à la date d'expiration
}

Notez ce qui ne figure pas dans cette fonction : un 60 codé en dur, et un 5 % codé en dur. La réglementation de ce secteur a changé deux fois en dix-huit mois. Tout ce que vous incorporez aujourd'hui dans le code deviendra demain une modification et une mise en production.

Trois registres, un seul loyer

C'est ici que se situe le vrai travail d'intégration, et c'est la partie que les démonstrations commerciales sautent.

Un seul mois de loyer sur une seule unité existe dans trois systèmes distincts qui ne se parlent pas :

Ejar détient le contrat : parties, durée, montant du loyer, identité juridique de la location.
La ZATCA détient la facture fiscale. Le loyer commercial est une opération soumise à la TVA, et la facture doit être validée ou déclarée via Fatoora avec les bonnes données acheteur et une adresse nationale valide. Notre guide de la facturation électronique ZATCA détaille ce pipeline.
La banque détient l'argent — un paiement SADAD, un virement, un encaissement mada — avec une référence qui ne ressemble à aucune des deux autres.

Rien ne relie automatiquement ces trois systèmes. La clé de jointure, c'est à vous de la fabriquer et de la défendre. Quand elle dérive, les symptômes sont familiers à quiconque a audité une société immobilière saoudienne : un contrat enregistré chez Ejar sans facture correspondante, une facture validée par la ZATCA sur un bail résilié le mois dernier, des encaissements sans facture à laquelle les imputer.

Un rapprochement nocturne n'est pas ici un agrément optionnel. C'est le produit :

type Drift =
  | { code: "contract_without_invoice"; ejarRef: string; period: string }
  | { code: "invoice_without_contract"; invoiceId: string }
  | { code: "invoice_on_terminated_lease"; invoiceId: string; ejarRef: string }
  | { code: "cash_unapplied"; paymentRef: string; amountHalalas: number }
  | { code: "amount_mismatch"; ejarRef: string; contractHalalas: number; invoicedHalalas: number };
 
function reconcile(
  contracts: RegisteredContract[],
  invoices: TaxInvoice[],
  payments: BankPayment[]
): Drift[] {
  const byRef = new Map(contracts.map((c) => [c.ejarRef, c]));
  const drifts: Drift[] = [];
 
  for (const inv of invoices) {
    const contract = inv.ejarRef ? byRef.get(inv.ejarRef) : undefined;
    if (!contract) {
      drifts.push({ code: "invoice_without_contract", invoiceId: inv.id });
      continue;
    }
    if (contract.terminatedOn && inv.issuedOn > contract.terminatedOn) {
      drifts.push({ code: "invoice_on_terminated_lease", invoiceId: inv.id, ejarRef: contract.ejarRef });
    }
    // Comparez en halalas. Jamais en flottants.
    if (inv.totalExVatHalalas !== contract.periodRentHalalas) {
      drifts.push({
        code: "amount_mismatch",
        ejarRef: contract.ejarRef,
        contractHalalas: contract.periodRentHalalas,
        invoicedHalalas: inv.totalExVatHalalas,
      });
    }
  }
 
  const applied = new Set(payments.filter((p) => p.invoiceId).map((p) => p.paymentRef));
  for (const p of payments) {
    if (!applied.has(p.paymentRef)) {
      drifts.push({ code: "cash_unapplied", paymentRef: p.paymentRef, amountHalalas: p.amountHalalas });
    }
  }
 
  return drifts;
}

Deux détails à reprendre. Tous les montants sont des entiers en halalas — le piège d'arrondi au facteur 100 dans les intégrations de paiement saoudiennes est réel, et les contrats de location portent des montants assez élevés pour qu'un centime flottant devienne un écart visible sur un relevé annuel. Et la fonction renvoie des enregistrements de dérive plutôt que de lever une exception : un rapprochement doit produire une file de travail pour un humain, pas faire échouer un batch à 3 h du matin.

Les frais d'enregistrement et de documentation constituent un piège connexe. Ils sont facturés par contrat et payés par le bailleur, et les montants publiés ont évolué. Ne les codez pas en dur dans votre logique de facturation : modélisez-les comme un barème daté que vous pouvez mettre à jour sans déploiement, et vérifiez les valeurs en vigueur sur les pages officielles d'Ejar avant chaque cycle.

Ce qu'il faut construire avant d'avoir les identifiants

La période d'attente n'est pas du temps mort. Tout ce qui suit produit de la valeur avec un humain qui exécute les étapes du portail, et rien n'est jeté à l'arrivée de l'API :

La machine à états. Brouillon, soumis, en attente des parties, enregistré, résilié — avec horodatages et journal d'événements en ajout seul. C'est la partie sur laquelle l'API viendra se brancher, inchangée.
La file d'opérateur. Au lieu d'un appel d'API, émettez une tâche portant exactement la charge utile qu'un humain doit coller dans le portail, et exigez qu'il consigne le numéro de contrat Ejar retourné. Vous constituez ainsi gratuitement le jeu de fixtures de votre futur adaptateur.
La détection de dérive. Le rapprochement avec les contrats exportés depuis Ejar fonctionne dès aujourd'hui, en CSV, sans aucune API. C'est aussi la démonstration la plus convaincante face à un prospect, parce qu'elle trouve de l'argent.
L'interface d'adaptateur. Définissez EjarGateway comme une interface, avec une implémentation manuelle maintenant et une implémentation réseau plus tard. Le reste du système n'apprendra jamais à laquelle il parle.
La plomberie d'identité. L'authentification Nafath et la vérification d'identité sont des prérequis dans toute la pile gouvernementale saoudienne — voir notre guide Yakeen, Nafath et Wathq. Construisez-la une fois, réutilisez-la pour chaque plateforme suivante.

Cet ordre a une propriété utile : si l'accord d'intégration prend plus de temps que prévu, ou s'il est refusé, le produit fonctionne quand même. Si vous construisez API-first et que les identifiants n'arrivent pas, vous n'avez rien.

Le vrai risque, c'est la non-conformité silencieuse

Personne sur ce marché n'est sanctionné pour un écran de renouvellement lent. On l'est pour un contrat jamais enregistré, une augmentation de loyer appliquée pendant une fenêtre de gel, un renouvellement refusé sans motif valable, ou une facture fiscale qui ne correspond pas au contrat enregistré. Chacun de ces cas est une défaillance de cohérence de données — qu'une couche de reporting détecte et qu'une application de saisie ne détecte pas.

C'est le déplacement à opérer dans le cadrage du projet. L'intégration Ejar est habituellement spécifiée comme une économie de saisie. Sa valeur réelle est celle d'un contrôle de conformité : ce qui indique à votre client, chaque matin, lequel de ses 500 baux est aujourd'hui désaligné avec le registre, l'administration fiscale ou la banque. Automatiser la frappe est la moitié bon marché. Prouver que les livres concordent est la moitié qui fait renouveler l'abonnement.

Vous construisez ou auditez un logiciel de gestion locative pour le marché saoudien ? Nous intervenons précisément sur cette couche — la surface d'intégration et de reporting au-dessus d'Ejar, de la ZATCA et des banques, y compris le rapprochement pour des systèmes déjà en production. Si vous voulez un diagnostic franc de l'endroit où vos données de baux dérivent aujourd'hui, contactez-nous et nous parcourrons ensemble vos flux de contrats, de factures et d'encaissements.