Noqta
écrits/blog/2026/08
● Blog17 août 2026·6 min

API Tawakkalna Partners : Guide du développeur

Construisez sur les APIs Tawakkalna d'identité, de documents et de santé vérifiés pour atteindre 34M d'utilisateurs saoudiens. Setup, Flutter SDK et erreurs courantes.

Équipe Noqta
·EN · FR · AR

En juin 2026, quarante organisations — ministères, entreprises privées et associations — ont intégré 160 nouveaux services dans Tawakkalna en un seul mois. Ce chiffre n'est pas une annonce de jalon : c'est le rythme de déploiement actuel. L'application nationale saoudienne héberge désormais plus de 1 000 services gouvernementaux et compte plus de 34 millions d'utilisateurs enregistrés. Si vous développez un produit pour le marché saoudien sans considérer une intégration Tawakkalna, vous ignorez le plus grand canal de distribution d'identité vérifiée du pays.

Ce guide s'adresse aux développeurs qui veulent comprendre le fonctionnement du programme Partners, quel SDK utiliser, quelles données sont disponibles, et où la plupart des intégrations échouent avant le lancement.

Deux chemins d'intégration

La SDAIA (Autorité saoudienne des données et de l'IA) propose deux routes distinctes dans l'écosystème Tawakkalna :

Partner Portal (REST API) — pour les organisations qui souhaitent exposer leurs services hébergés à l'intérieur de l'application Tawakkalna. Votre service apparaît comme une carte aux côtés des services ministériels ; votre backend gère la logique, Tawakkalna gère la distribution.

Mini-App SDK (Flutter/Web) — pour les organisations qui souhaitent intégrer une expérience interactive complète dans Tawakkalna. Votre application tourne dans une WebView avec accès JavaScript-bridge à la session Tawakkalna vérifiée de l'utilisateur. Vous obtenez son identité, ses documents et ses données de santé sans construire votre propre couche d'authentification.

Les deux chemins ne sont pas mutuellement exclusifs. La plupart des intégrations matures utilisent le REST API pour l'échange de données et le SDK pour le flux utilisateur interactif.

Configuration du SDK Mini-App

Le SDK Flutter est publié sur pub.dev sous le nom tawakkalna_sdk_flutter. La version actuelle est 0.0.5-alpha.5. Il fonctionne comme un pont web-to-native : votre application Flutter compile en HTML/JS, tourne dans une WebView à l'intérieur de l'application Tawakkalna hôte, et appelle les méthodes Tawakkalna natives via une couche d'interop JavaScript.

pubspec.yaml

dependencies:
  tawakkalna_sdk_flutter: ^0.0.5-alpha.5

Ajoutez le fichier JS approprié à web/index.html selon l'environnement :

  • Développement : twkhelper_mock.js — retourne des données fictives réalistes sans nécessiter de session réelle
  • Production : twkhelper.js — connecté aux données vérifiées réelles, fonctionne uniquement dans l'application Tawakkalna

Initialisation de base :

final twk = TwkHelper();
final fullName = await twk.getUserFullName();

Si vous initialisez TwkHelper() hors du shell Tawakkalna — dans un build Flutter autonome par exemple — le pont de production lève une erreur immédiatement. Le mock retourne silencieusement des données fictives, ce qui constitue le seul moyen d'exécuter des tests locaux.

Données accessibles via le SDK

L'API V1 expose plus de 45 méthodes réparties en six catégories :

Identité et données personnelles

  • Numéro d'identité nationale, nom complet, genre, date de naissance, nationalité

Documents

  • Numéro de passeport et date d'expiration, numéro et expiration de l'Iqama (résidents)

Santé

  • Groupe sanguin, statut de handicap (utile pour les workflows d'accessibilité)

Famille

  • Liste des membres de la famille avec options de filtrage, informations sur le sponsor

Véhicules

  • Détails des véhicules immatriculés, infractions de circulation en cours

Localisation et appareil

  • Coordonnées GPS, adresse nationale, accès galerie/caméra, permissions de notifications

Authentification

Le SDK émet des tokens de session via twk.generateToken(). L'authentification biométrique est disponible via twk.authenticateBiometric() — elle déclenche l'invite biométrique intégrée de Tawakkalna, pas celle du système d'exploitation. La credential est liée à l'identité vérifiée Tawakkalna de l'utilisateur : c'est un signal de confiance plus élevé qu'un PIN d'appareil.

V2 ajoute cinq méthodes supplémentaires non encore entièrement documentées dans le portail public au moment de la rédaction.

Ce que les entreprises saoudiennes construisent

KYC client — Les fintechs et assureurs collectent des données d'identité vérifiées en moins d'une minute, sans scan manuel de documents. Aucune intégration séparée avec Yakeen ou Nafath n'est requise pour une vérification d'identité basique — la session Tawakkalna est l'ancre de confiance. Pour une vérification NIC plus approfondie, consultez le guide Yakeen, Nafath et Wathq.

Onboarding RH — Les équipes RH vérifient le statut Iqama, la date d'expiration et les données de parrainage au moment de la candidature. Combiné à Qiwa, cela élimine l'une des vérifications manuelles les plus courantes du pipeline. Voir le guide d'intégration Qiwa et conformité Nitaqat.

Vérification d'âge e-commerce — Les marketplaces vendant des catégories réglementées ou soumises à restriction d'âge utilisent les tokens d'identité Tawakkalna comme porte de vérification plutôt que de construire un flux de téléversement de documents séparé.

Gestion de flotte — Les logisticiens récupèrent l'immatriculation et les infractions de leurs chauffeurs en un seul appel, remplaçant une recherche Absher manuelle par employé. Sur la distinction entre les plateformes disponibles pour les établissements, voir Absher Business vs Muqeem.

Couche de vérification B2B — Pour les workflows qui doivent confirmer qu'un utilisateur agit pour le compte d'une entité enregistrée, un token Maroof peut être superposé à l'identité personnelle Tawakkalna. Le guide API Maroof et Wathq détaille la structure de cette vérification secondaire.

Trois erreurs qui retardent le go-live

1. Développer entièrement sur données fictives jusqu'à la recette

Le pont de développement retourne le même jeu de données fictives à chaque appel. Les développeurs testent le chemin nominal et ratent les cas limites : utilisateurs avec Iqama expirée, sans permissions accordées (caméra, localisation), sans adresse email vérifiée. Prévoyez au moins un sprint de recette utilisateur dans l'environnement sandbox Tawakkalna réel avant de soumettre la demande de partenariat.

2. Traiter l'authentification biométrique comme facteur principal unique

L'auth biométrique via le SDK confirme que l'utilisateur correspond au compte Tawakkalna. Elle ne revérifie pas contre la base d'identité nationale et ne valide pas la vivacité. Pour les transactions à risque élevé — demandes de crédit, signature de contrats, autorisation de paiements importants — une étape de vérification secondaire est nécessaire : généralement un OTP Nafath ou une vérification Maroof. Découvrir cet écart lors de la revue sécurité SDAIA ajoute six à huit semaines au calendrier d'approbation.

3. Ignorer l'approbation Partner Portal jusqu'après la construction

Le SDK peut être construit et testé de bout en bout sans accord de partenariat formel. Le déploiement en production requiert l'approbation SDAIA via le Partner Portal. Les équipes qui arrivent à cette étape après huit semaines de développement font régulièrement face à un cycle de révision de deux mois qui bloque le lancement après que des clients ont déjà vu une démo fonctionnelle.

Soumettez la demande de partenariat au moment même où vous écrivez votre première ligne de SDK.

Conditions d'enregistrement

Devenir partenaire Tawakkalna nécessite quatre éléments :

  1. Un registre commercial valide en Arabie Saoudite
  2. Une politique de traitement des données conforme aux directives de la National Cybersecurity Authority (NCA)
  3. Un contact technique avec accès vérifié au portail développeur SDAIA
  4. La soumission du résumé de service et du document d'architecture d'intégration pour examen

Les entités du secteur privé qui ont déjà franchi l'étape de vérification Maroof tendent à aller plus vite dans ce processus, car la validation d'entité a déjà été réalisée.

La vue d'ensemble

Tawakkalna n'est plus simplement l'application de pass sanitaire de l'ère pandémique. L'Arabie Saoudite l'utilise comme couche d'identité et de services nationale — un shell authentifié unique à travers lequel 34 millions d'utilisateurs interagissent avec les ministères gouvernementaux et les entreprises privées. Les 160 services ajoutés en juin 2026 seul montrent que le rythme n'a pas plafonné ; l'adoption du secteur privé s'accélère.

Le SERP des développeurs pour l'intégration Tawakkalna est pratiquement vide de guides indépendants. Le portail officiel existe mais ne porte aucun guide d'implémentation indépendant. Les équipes qui livrent une intégration fonctionnelle et documentent les leçons apprises publiquement construisent une autorité de catégorie avant que l'espace ne mûrisse.

Si vous planifiez un produit pour le marché saoudien nécessitant une identité vérifiée, un statut de santé ou une vérification documentaire, la décision d'architecture d'intégration doit être prise en début de projet — pas après avoir déjà construit une pile KYC parallèle à démanteler.

Prêt à cadrer votre intégration Tawakkalna ? Notre équipe a cartographié l'ensemble de la pile API gouvernementale saoudienne — de ZATCA à Qiwa à SDAIA. Contactez Noqta pour une revue technique sans argumentaire commercial de votre plan d'intégration avant la fin de la phase de conception.