Maroof + Wathq : Vérifier l'immatriculation commerciale saoudienne via API

Lorsque vous construisez une marketplace, une passerelle de paiement ou une plateforme B2B en Arabie Saoudite, vous vous heurtez à une obligation réglementaire que la plupart des documentations ignorent : vous devez vérifier que chaque marchand possède un enregistrement commercial (سجل تجاري) valide et — pour les activités e-commerce — qu'il est authentifié sur منصة الأعمال (anciennement Maroof / معروف). Le badge Maroof indique aux consommateurs saoudiens qu'une boutique est licenciée, et les processeurs de paiement l'exigent désormais avant d'embarquer des vendeurs.

Le problème : la vérification officielle en Arabie Saoudite est répartie entre deux systèmes :

Le Registre Commercial (السجل التجاري) — géré par le ministère du Commerce
منصة معروف → منصة الأعمال — la couche d'authentification e-commerce (migrée en mars 2023)

Aucun de ces deux systèmes n'expose directement une API REST publique. La voie programmatique passe par واثق (Wathq) — la passerelle officielle de données commerciales saoudiennes sur developer.wathq.sa.

Ce guide vous montre comment intégrer Wathq pour construire un flux de vérification en temps réel en TypeScript.

Qu'est-ce que Maroof, et qu'a changé en 2023 ?

Maroof (معروف) a été lancée comme plateforme du ministère du Commerce pour certifier les boutiques en ligne saoudiennes. Tout magasin affichant le badge Maroof disposait d'un enregistrement commercial valide et était autorisé à exercer une activité de commerce électronique.

En mars 2023, le Ministère a migré l'authentification des e-boutiques vers منصة الأعمال (business.sa), la plateforme unifiée du Saudi Business Center. Le badge Maroof reste affiché sur les boutiques préalablement certifiées, mais les nouvelles immatriculations et renouvellements transitent désormais par business.sa. Côté utilisateur, rien n'a changé. Côté développeur qui construit une vérification dans une plateforme, le chemin est maintenant :

Numéro CR → API Wathq → statut actif + activité e-commerce confirmée

Wathq : La passerelle officielle des données commerciales

Wathq opère dans l'écosystème gouvernemental saoudien et fournit un point d'accès unique et authentifié à plusieurs sources de données gouvernementales. L'API Registre Commercial — version 6.7.0 au moment de la rédaction — est le service pertinent pour la vérification des marchands.

Accès à la plateforme :

Créez un compte sur developer.wathq.sa
Abonnez-vous à l'API Registre Commercial (environnement sandbox disponible)
Obtenez vos identifiants Bearer token
Passez en production après les tests en sandbox

Endpoints principaux :

Endpoint	Fonction
`GET /info/{id}`	Données de base : nom, statut, type d'activité, dates
`GET /fullinfo/{id}`	Données complètes : propriétaires, capital, succursales
`GET /owners/{id}`	Détail des actionnaires et parts sociales
`GET /related/{id}/{idType}`	Tous les enregistrements liés à un identifiant national

Le paramètre id accepte :

Un numéro CR à 10 chiffres (format : 10xxxxxxxx)
Un numéro national unifié à 10 chiffres (format : 700xxxxxxx) — obligatoire pour les enregistrements actifs et en attente

Intégration TypeScript

Vérification de base du registre commercial

const WATHQ_BASE = process.env.WATHQ_BASE_URL!;
const WATHQ_TOKEN = process.env.WATHQ_API_TOKEN!;
 
interface CRInfo {
  crNumber: string;
  crName: string;
  status: string; // 'Active' | 'Expired' | 'Cancelled'
  activities: string[];
  issuanceDate: string;
  expiryDate: string;
}
 
async function verifyCR(id: string, lang: 'ar' | 'en' = 'ar'): Promise<CRInfo> {
  const res = await fetch(`${WATHQ_BASE}/info/${id}?language=${lang}`, {
    headers: {
      Authorization: `Bearer ${WATHQ_TOKEN}`,
      'Content-Type': 'application/json',
    },
  });
 
  if (res.status === 404) throw new Error('CR_NOT_FOUND');
  if (res.status === 401) throw new Error('WATHQ_AUTH_FAILED');
  if (res.status === 429) throw new Error('WATHQ_QUOTA_EXCEEDED');
  if (!res.ok) throw new Error(`WATHQ_ERROR_${res.status}`);
 
  return res.json();
}

Flux complet d'embarquement marchand

interface OnboardingResult {
  valid: boolean;
  crStatus: string;
  errorCode?: string;
}
 
async function onboardSaudiMerchant(
  crNumber: string,
  nationalId: string
): Promise<OnboardingResult> {
  // Étape 1 : Vérifier que le CR est actif
  const info = await verifyCR(crNumber);
  if (info.status !== 'Active') {
    return { valid: false, crStatus: info.status, errorCode: 'CR_NOT_ACTIVE' };
  }
 
  // Étape 2 : Confirmer la présence d'une activité e-commerce
  const hasEcommerceActivity = info.activities.some(
    (a) =>
      a.includes('تجارة إلكترونية') ||
      a.toLowerCase().includes('electronic commerce')
  );
  if (!hasEcommerceActivity) {
    return { valid: false, crStatus: info.status, errorCode: 'NO_ECOMMERCE_ACTIVITY' };
  }
 
  // Étape 3 : Vérifier que le propriétaire déclaré correspond au CR
  const ownersRes = await fetch(
    `${WATHQ_BASE}/owners/${crNumber}?language=ar`,
    { headers: { Authorization: `Bearer ${WATHQ_TOKEN}` } }
  );
  const ownersData = await ownersRes.json();
  const ownerMatch = ownersData.owners?.some(
    (o: { nationalId: string }) => o.nationalId === nationalId
  );
 
  if (!ownerMatch) {
    return { valid: false, crStatus: info.status, errorCode: 'OWNER_MISMATCH' };
  }
 
  return { valid: true, crStatus: info.status };
}

Quatre erreurs fréquentes et comment les éviter

1. La règle du numéro 700

Les enregistrements actifs et en attente ne peuvent être interrogés qu'avec le numéro national unifié à 10 chiffres commençant par 700. Passer un ancien numéro CR pour ces enregistrements retourne l'erreur 400.1.5. Collectez toujours les deux identifiants lors de l'inscription du marchand.

2. CR expirés avec badge Maroof encore visible

Le badge Maroof persiste sur les vitrines en ligne même après l'expiration du registre commercial. Ne faites jamais confiance au badge visuel seul. Interrogez Wathq à chaque embarquement et planifiez une re-vérification automatique tous les 30 jours.

3. Épuisement du quota (429)

Wathq impose des quotas d'appels selon le plan souscrit. Pour un embarquement de marchands à fort volume, mettez en cache les réponses Wathq dans Redis avec une clé basée sur le numéro CR et un TTL de 24 heures. La plupart des changements de statut CR interviennent sur un cycle mensuel.

4. Code d'activité inadapté

Un CR peut être actif mais enregistré pour une activité physique — services de réparation, par exemple — sans aucune classification e-commerce. Utilisez GET /fullinfo/{id} lors de l'embarquement pour lire la liste complète des activités et rejeter les CR qui n'ont pas de code d'activité commerce électronique ou commerce de détail.

Afficher le statut Maroof sur votre interface

L'authentification منصة الأعمال (successeur de Maroof) est une étape que le marchand réalise lui-même sur business.sa — il n'existe pas d'API pour la vérifier ou la déclencher programmatiquement en temps réel. Le schéma adopté par les intégrateurs de paiement saoudiens (HyperPay, Moyasar, STCPay) est :

Collecter le numéro CR et le numéro national unifié du marchand
Vérifier via Wathq que le CR est actif et comporte une activité e-commerce
Demander au marchand de téléverser son certificat منصة الأعمال (PDF émis par business.sa)
Afficher votre propre badge "Vendeur Vérifié" une fois les deux contrôles validés

Cette vérification CR fonctionne rarement seule

Dans les plateformes saoudiennes en production, la vérification du registre commercial est un nœud dans une chaîne de conformité plus large. Le même marchand aura également besoin de :

Vérification WPS — conformité de la protection des salaires si des employés sont concernés. Voir le guide de réconciliation WPS.
Statut Qiwa / Nitaqat — éligibilité au recrutement et niveau de saoudisation. Voir le guide d'intégration Qiwa.
Facturation ZATCA Phase 2 — pour toute transaction B2B. Voir le guide Fatoorah ZATCA.
Paie Mudad — si votre plateforme traite des paiements de salaires. Voir le guide API Mudad.

Ensemble, ces systèmes forment l'épine dorsale de la conformité dans toute marketplace B2B ou plateforme RH saoudienne.

Vous construisez un flux de vérification de marchands saoudiens et vous vous heurtez à des cas que la documentation ne couvre pas ? L'équipe Noqta a intégré Wathq, Qiwa, Mudad et ZATCA pour des plateformes marketplace dans le Golfe. Contactez-nous — nous cadrons votre couche de vérification en un seul appel.