Intégration Muqeem : l'API iqama que nul ne documente

Chaque matin, un responsable RH dans une entreprise saoudienne de taille moyenne ouvre trois écrans : le SIRH interne, le portail Muqeem, et un tableur contenant les dates d'expiration des iqamas. C'est le tableur qui fait office de source de vérité. Quand il se trompe, l'entreprise l'apprend le jour où un salarié se présente à l'aéroport avec un visa de sortie-retour qui n'a jamais été émis.

Ce n'est pas un problème de rigueur administrative, mais un problème d'architecture : l'état d'un salarié est réparti sur trois systèmes gouvernementaux dont aucun ne communique automatiquement avec le vôtre — et l'un d'eux, Muqeem, n'expose tout simplement pas d'API en libre-service.

Cet article explique ce que signifie réellement « l'intégration Muqeem » sur le plan technique, pourquoi la plupart de ce qui se vend sous ce nom relève de la revente d'accès plutôt que de l'intégration, et comment construire la couche dont vous avez véritablement besoin.

Ce qu'est Muqeem, et en quoi ce n'est ni Qiwa ni Mudad

Muqeem est opérée par Elm Company en coopération avec la Direction générale des passeports (Jawazat). Son périmètre couvre tout ce qui touche aux passeports et à la résidence des travailleurs expatriés :

• Émission, renouvellement et transfert des iqamas
• Visas de sortie-retour : émission, annulation, prolongation, réimpression
• Visas de sortie définitive
• Mise à jour des données de passeport et prolongation de validité
• Rapports de statut de résident et vérification des visas

L'erreur fréquente consiste à traiter Muqeem, Qiwa et Mudad comme trois portails interchangeables. Ils ne le sont pas : chacun relève d'une autorité différente et d'un périmètre distinct.

Cette distinction n'est pas une question de classification. C'est un ordre d'exécution, et c'est là que réside le problème d'ingénierie.

La chaîne de dépendances qui casse la plupart des intégrations

Les transactions Muqeem ne sont pas indépendantes. Un ordre strict s'applique, et l'ignorer est la première cause de rejet :

Permis de travail valide (Qiwa)
        ↓
   Renouvellement iqama (Muqeem)
        ↓
Visa de sortie-retour (Muqeem)
        ↓
Validité du passeport couvrant la période

Renouveler l'iqama d'un salarié expatrié exige un permis de travail valide délivré par Qiwa. Les frais de permis se règlent via Qiwa, les frais de résidence via Muqeem par code facturier SADAD. Deux systèmes, deux circuits de paiement distincts, un seul état qui doit concorder.

Conséquence pratique : votre système ne peut pas traiter « renouveler l'iqama » comme un appel unique. Il doit vérifier la première condition avant de tenter la seconde, faute de quoi vous payez une transaction rejetée tout en laissant vos propres enregistrements affirmer un succès qui n'a jamais eu lieu.

C'est exactement le schéma décrit dans l'intégration Qiwa pour les SIRH, prérequis à tout chantier Muqeem.

La vérité qui dérange : il n'existe pas d'API publique

Cherchez « Muqeem API » et vous trouverez des dizaines de résultats : modules Odoo, intégrations Jisr, ZenHR ou Menaitech, sociétés vendant une « connexion instantanée ». Ce que vous ne trouverez pas, c'est une documentation officielle et publique des points d'entrée.

La raison : Muqeem n'expose pas d'API en libre-service. L'accès programmatique passe par les canaux d'intégration officiels d'Elm — la plateforme Rabet ou un forfait intégrateur équivalent — et suppose :

1. Un abonnement établissement actif de type complet (un forfait « opérations » seul ne suffit pas pour l'intégration)
2. L'autorisation d'intégration activée sur le compte de l'établissement
3. Des identifiants émis au nom de l'établissement, et non du prestataire
4. Un coût supplémentaire sur l'abonnement — les sources fournisseurs évoquent une fourchette de 12 à 20 % au-dessus de la valeur de l'abonnement pour activer la liaison
5. Un modèle à points : chaque transaction consomme du crédit sur le forfait de l'établissement

Le troisième point est le plus important commercialement, et le plus souvent passé sous silence. Les identifiants appartiennent à l'établissement. Lorsqu'un prestataire vous vend « l'intégration Muqeem », il construit généralement un connecteur au-dessus de votre propre abonnement. C'est un service légitime, mais cela signifie que la connexion n'est pas une fonctionnalité propriétaire de son produit : elle vous appartient et reste transférable.

Si un fournisseur affirme que l'intégration Muqeem passe exclusivement par son produit, demandez au nom de qui les identifiants seront émis. La réponse révèle si vous achetez une intégration ou si vous louez un accès.

Où les intégrations échouent réellement

Au fil de plusieurs projets d'intégration aux plateformes gouvernementales saoudiennes, les défaillances se répètent sous quatre formes — dont aucune ne relève de la qualité du code.

1. La dérive silencieuse de l'état

Votre SIRH stocke la date d'expiration de l'iqama dans un champ. Jawazat est la source de vérité. Si une iqama est renouvelée manuellement via le portail, si un visa est annulé ou un parrainage transféré, votre champ devient faux et rien ne vous en avertit.

Le remède n'est pas une logique de synchronisation plus fine, mais une réconciliation périodique : récupérez le rapport de statut des résidents, comparez-le à l'état local, et consignez chaque écart sous forme d'alerte au lieu de l'écraser en silence.

type MuqeemState = {
  iqamaNumber: string;
  iqamaExpiry: string;      // Hégirien à la source — convertir une fois à la frontière
  passportExpiry: string;
  exitReentryStatus: 'none' | 'active' | 'expired';
};
 
// Ne pas écraser l'état local. Faire remonter les écarts.
function reconcile(local: MuqeemState, remote: MuqeemState) {
  const drift = (Object.keys(remote) as Array<keyof MuqeemState>)
    .filter((k) => local[k] !== remote[k])
    .map((field) => ({ field, local: local[field], remote: remote[field] }));
 
  return drift.length
    ? { status: 'drift' as const, drift, authority: 'muqeem' }
    : { status: 'in_sync' as const };
}

2. Le calendrier hégirien

Les dates d'iqama sont hégiriennes. Votre système est presque certainement grégorien. Convertir à chaque affichage garantit des erreurs d'un jour — et une erreur d'un jour sur une date d'expiration d'iqama se traduit par une amende.

La règle : convertir une seule fois, à la frontière du système, et stocker les deux. Affichez l'hégirien, puisque c'est la langue de l'utilisateur et de l'administration, et calculez en grégorien.

3. L'épuisement des points en cours d'opération

Les forfaits de points s'épuisent. Lorsque c'est le cas, les transactions échouent — mais pas nécessairement d'une manière que votre système distingue d'un échec de validation. Si votre connecteur réessaie automatiquement à chaque erreur, vous remplissez vos journaux pour rien, ou vous déclenchez une transaction en double dès le rechargement du solde.

Séparez les erreurs de solde, de validation et de réseau. La première appelle une alerte humaine, la deuxième ne doit jamais être réessayée, et seule la troisième justifie une nouvelle tentative.

4. L'absence d'idempotence

Émettre deux fois un visa de sortie-retour n'est pas un défaut cosmétique : ce sont des frais payés en double et un état à annuler manuellement. Toute opération qui modifie l'état chez Jawazat doit porter une clé d'unicité de votre côté, enregistrée avant l'appel et non après.

// Enregistrer l'intention avant l'appel, pas après la réponse.
async function issueExitReentry(employeeId: string, days: number) {
  const key = `exit-reentry:${employeeId}:${days}:${businessDate()}`;
 
  if (await ledger.has(key)) {
    return ledger.get(key); // Déjà exécuté — ne pas rappeler
  }
 
  await ledger.reserve(key);          // Survit à une coupure réseau
  const result = await gateway.call('exit-reentry/issue', { employeeId, days });
  await ledger.settle(key, result);
 
  return result;
}

C'est la coupure réseau survenant après l'envoi de la requête et avant la réception de la réponse qui produit les doublons. Réserver au préalable rend ce cas détectable plutôt que coûteux.

L'architecture que nous recommandons

L'approche courante — pousser la logique Muqeem dans le SIRH ou dans un module Odoo — paraît plus rapide et revient plus cher. Le moindre changement de règle gouvernementale se transforme en montée de version de tout le système.

L'alternative est une couche intermédiaire légère dont vous êtes propriétaire :

SIRH / Odoo / votre plateforme interne
              ↓  (interface interne stable)
      Couche de conformité (vous la possédez)
              ↓
   Passerelle Elm / Rabet  →  Muqeem  →  Jawazat

Ce que vous y gagnez : des contrôles de dépendances centralisés, un journal de transactions indépendant du cycle de publication de votre fournisseur, la possibilité de remplacer le système frontal sans reconstruire la conformité, et une piste d'audit qui résiste au contrôle.

C'est l'argument que nous défendions dans le piège de l'ERP : intégrer plutôt que remplacer, et c'est la même couche qui dessert l'intégration Mudad pour la paie. Construisez-la une fois, branchez-y trois plateformes.

Une remarque sur les données personnelles

Les données de résidence et de passeport sont des données personnelles au sens de la PDPL saoudienne. Numéros d'iqama, images de passeports et dates de visa ne sont pas des champs ordinaires.

Concrètement : limitez le stockage local au strict nécessaire au processus, conservez la trace de qui a fait quoi et quand, et soyez particulièrement attentif à l'emplacement d'exécution de la couche intermédiaire si elle réside sur un cloud hors du Royaume. Nous avons détaillé ces contraintes dans le transfert transfrontalier de données sous la PDPL.

Liste de contrôle avant de démarrer

• Abonnement établissement de type complet avec intégration activée
• Identifiants émis au nom de l'établissement, non du prestataire
• Coût d'activation et modèle de consommation des points documentés par écrit
• Permis de travail Qiwa valides avant toute tentative de renouvellement d'iqama
• Conversion hégirien/grégorien effectuée une seule fois, à la frontière du système
• Clés d'idempotence sur chaque opération modifiant l'état, enregistrées avant l'appel
• Classification des erreurs distinguant solde, validation et réseau
• Réconciliation périodique alertant sur les écarts au lieu de les écraser

Conclusion

« L'intégration Muqeem » n'est pas un projet d'API. C'est un projet de réconciliation d'état entre trois systèmes gouvernementaux et le vôtre, sous les contraintes d'une plateforme sans interface publique qui vous facture à la transaction.

Les établissements qui réussissent n'achètent pas un meilleur connecteur. Ils traitent la conformité comme une couche qu'ils possèdent : comprendre les dépendances, empêcher les doublons, et faire remonter la dérive au lieu de la masquer.

Si vous gérez des travailleurs expatriés sur tableur, ou si vous portez un connecteur Muqeem qui échoue en silence, commencez par cartographier où vit l'état aujourd'hui et où il dérive. Le résultat est généralement plus modeste que redouté et plus clair qu'attendu.

Nous auditons régulièrement les intégrations aux plateformes gouvernementales saoudiennes — Qiwa, Mudad, Muqeem, NPHIES et ZATCA. Pour un avis indépendant sur votre architecture avant de vous engager auprès d'un fournisseur ou de lancer un développement, contactez-nous pour une revue diagnostique de votre processus de résidence : où se trouve la source de vérité, où elle dérive, et ce qui mérite réellement d'être automatisé.