Onboarding client B2B

Objectif métier

Un onboarding_case porte une tentative d'onboarding de bout en bout. Il conserve le type de sujet, les données initiales, les contrôles effectués, le processus associé et la décision finale. Il peut démarrer avant que la party ou le party_contact n'existe dans Ormuz.

Le processus transforme progressivement les informations déclaratives en objets métier exploitables. Il peut rechercher une société existante, créer ou enrichir une party, identifier ses contacts, collecter des justificatifs, appeler des partenaires et demander une revue humaine.

Onboarding société ou individuel

Si la party ou le contact existe déjà, fournissez son ID à la création. Sinon, utilisez initial_data pour préremplir le parcours ; le process décidera quand rechercher, créer et rattacher les objets persistés.

Prérequis

Un parcours utilisateur n'est nécessaire que si le processus attend une action utilisateur. Un onboarding alimenté par API, synchronisation ou services externes peut s'exécuter sans redirection ; votre système attend alors l'événement de décision final.

Parcours cible

Ouvrir le dossier

Appelez POST /v1/onboarding-cases depuis votre backend. Les données de initial_data.party et initial_data.party_contact suivent les champs publics de création correspondants, mais n'entraînent pas immédiatement la création de ces objets.

POST /v1/onboarding-cases
Content-Type: application/json

{
  "merchant_id": "mer_abc123",
  "subject_type": "company",
  "return_url": "https://app.example/onboarding/complete",
  "source_reference": "CRM-ACCOUNT-1042",
  "initial_data": {
    "party": {
      "legal_name": "ACME France SAS",
      "registration_number": "123456789",
      "registration_country": "FR",
      "is_buyer": true
    },
    "party_contact": {
      "first_name": "Ada",
      "last_name": "Lovelace",
      "email": "ada@example.com"
    }
  }
}

{
  "id": "obc_abc123",
  "object": "onboarding_case",
  "subject_type": "company",
  "status": "open",
  "decision_status": "pending",
  "merchant_id": "mer_abc123",
  "party_id": null,
  "party_contact_id": null,
  "source_reference": "CRM-ACCOUNT-1042",
  "process_instance_id": "pci_abc123",
  "url": "https://hosted.example/access/...",
  "checks": []
}

La réponse contient l'ID obc_*, l'instance de processus et une URL de parcours utilisateur contextualisée. N'utilisez cette URL que si le processus comporte une action utilisateur ; sinon, laissez le parcours s'exécuter côté serveur. Conservez l'ID du dossier avec votre référence CRM, ERP ou e-commerce.

Collecter les données et produire les contrôles

Les données déjà connues préremplissent le contexte du process. Les étapes suivantes ne doivent demander à l'utilisateur que les informations manquantes ou celles qui nécessitent une confirmation explicite.

Un compliance_check porte d'abord sur son sujet. Il peut en plus être rattaché au dossier d'onboarding et au processus qui l'a produit, mais ces contextes sont optionnels. Son résultat peut être pending, passed, failed, error ou manual_review. Le détail du dossier expose les checks qui lui sont rattachés. Un résultat de provider n’est pas automatiquement une décision finale d’onboarding : la politique du processus reste responsable de l’interprétation de ce contrôle.

Décider, demander une revue ou rejeter

Un contrôle en manual_review émet d'abord compliance_check.review_required. S'il est rattaché à ce dossier, Ormuz émet ensuite onboarding_case.review_required comme conséquence sur l'onboarding. Votre processus peut alors attendre une décision opérateur, demander des informations complémentaires ou poursuivre avec un niveau de contrôle renforcé.

Le node finalize_onboarding_case rattache la party et le contact résolus ou créés, puis applique la décision finale. Il évite qu'un dossier soit approuvé sans objets métier utilisables en aval.

Cycle de vie du dossier

Le dossier sépare deux axes. status décrit son cycle de vie ; decision_statusdécrit la décision d’onboarding. Une collecte en cours ou une revue humaine ne crée donc pas un statut intermédiaire supplémentaire : le dossier reste open tant que la décision n’est pas terminale.

completed et cancelled sont terminaux pour ce dossier. Un nouveau besoin d'onboarding ouvre un nouveau dossier plutôt que de réécrire la décision d’un dossier clôturé.

Événements et suivi

Après une redirection depuis le parcours utilisateur, relisez toujours le dossier côté serveur. Pour un parcours automatisé, attendez directement onboarding_case.approved, onboarding_case.rejected,onboarding_case.cancelled ou un événement de revue, puis récupérez le dossier et ses checks.

Avant d'ouvrir un nouveau dossier pour une party connue, la recherche des onboardings approuvés permet de réutiliser une décision antérieure selon votre politique de validité.

Checklist d'intégration

• Choisir company ou individual selon le sujet réellement onboardé.
• Configurer au moins un launcher onboarding actif et sélectionner explicitement le process_definition_id lorsqu'il y en a plusieurs.
• Transmettre les objets existants ou préremplir uniquement les données déjà connues.
• Utiliser une référence source ou une clé de déduplication stable.
• Ne demander un parcours utilisateur que lorsque le processus attend une action utilisateur.
• Tracer chaque contrôle important avec son sujet, le provider éventuel et son résultat.
• Définir explicitement les résultats qui imposent une revue ou bloquent l'approbation.
• Rattacher une party, et un contact pour un onboarding individuel, avant approbation.
• Traiter les événements de décision de façon idempotente et relire le dossier avant activation.