Transit international

Vue d'ensemble

Le transit international permet à un acheteur (app Tranoo) d'organiser l'expédition d'un véhicule acheté vers un pays de destination, en choisissant un transitaire inscrit sur Tranoo Pro.

Le parcours est modélisé par la collection TransitMission et exposé via les préfixes API :

• /api/transit-missions
• /api/transit (alias de compatibilité)

:::info Hors périmètre L'ancien modèle PropositionTransit et ses routes sont désactivés dans app.js. Ne pas les utiliser comme référence. :::

Acteurs

Acteur	Application	Rôle
Acheteur	Tranoo	Démarre le parcours, choisit le transitaire, valide le transfert
Transitaire	Tranoo Pro	Reçoit les missions, accepte ou refuse, clôture la mission
Admin	Dashboard	Valide les comptes transitaires (/api/transitaires/verification)

Modèle de données

TransitMission.js

Champ	Description
article	Référence Article
acheteur	Référence User (rôle acheteur)
transitaire	Référence User (rôle transitaire), nullable
statut	Voir cycle de vie ci-dessous
modeLivraison	transit ou consommation
paysDestination	Pays cible (requis avant sélection transitaire)
detailsSupplementaires	Notes libres
articleTitre	Titre dénormalisé pour affichage
dateSelectionTransitaire	Date de choix du transitaire
dateTransfer	Date de transfert après vérification
dateTraite	Date de clôture par le transitaire
verificationApproved	true après transfert validé

Index : unique (article, acheteur) — un seul parcours par article et par acheteur.

Modèles associés

Modèle	Rôle
TransitaireReview.js	Avis clients sur transitaires (/api/transitaire-reviews)
TransitaireSubscriptionPricing.js	Tarifs abonnement transitaire (admin)
Subscription.js	Abonnement actif requis pour certaines actions transitaire

La vérification du compte transitaire est stockée sur User.transitaireVerification (pas un modèle séparé).

Cycle de vie d'une mission

stateDiagram-v2
    [*] --> parcours: POST /start
    parcours --> en_cours: POST /select-transitaire
    en_cours --> parcours: PATCH /rejeter-attribution (transitaire)
    en_cours --> transferer: POST /transferer (acheteur)
    transferer --> traite: PATCH /marquer-traite (transitaire)
    parcours --> annule: annulation achat
    en_cours --> annule: annulation achat

Statut	Signification
parcours	Parcours démarré, destination renseignée, transitaire non encore choisi (ou refusé)
en_cours	Transitaire sélectionné, en attente de validation / transfert
transferer	Véhicule transféré au transitaire après vérification
traite	Mission clôturée par le transitaire
annule	Achat annulé — parcours bloqué

Endpoints API

Préfixe : /api/transit-missions (et /api/transit)

Méthode	Route	Auth	Description
POST	/start	Acheteur	Démarre ou met à jour un parcours
POST	/select-transitaire	Acheteur	Assigne un transitaire (articleId, transitaireId)
POST	/transferer	Acheteur	Passe la mission en transferer
GET	/mes-parcours	Acheteur	Liste des parcours de l'acheteur
GET	/parcours/:articleId	Acheteur	Détail d'un parcours
GET	/mes-missions	Transitaire	Missions assignées au transitaire
GET	/acceptes	Transitaire	Compatibilité ancienne route Flutter
PATCH	/:id/marquer-traite	Transitaire	Clôture une mission transferer
PATCH	/:id/rejeter-attribution	Transitaire	Refuse une mission en_cours
PATCH	/:id/details	Acheteur	Met à jour destination / détails

Règles métier clés

• Pays de destination obligatoire avant select-transitaire
• Un transitaire actif (en_cours ou transferer) bloque un nouveau choix (code: TRANSITAIRE_ACTIF)
• Seul le transitaire assigné peut rejeter-attribution ou marquer-traite
• marquer-traite exige le statut transferer

Vérification des comptes transitaires

Préfixe : /api/transitaires/verification

Méthode	Route	Auth	Description
GET	/status	Transitaire	Statut de vérification du compte connecté
POST	/submit	Transitaire	Soumet le dossier (carte recto/verso, entreprise)
GET	/admin/demandes	Admin	Liste des demandes en attente
GET	/admin/demandes/:userId	Admin	Détail d'une demande
PATCH	/admin/demandes/:userId/approve	Admin	Approuve le dossier
PATCH	/admin/demandes/:userId/reject	Admin	Rejette avec motif

Statuts de vérification (User.transitaireVerification.statut)

Statut	Description
none	Aucune soumission
pending	Dossier en cours d'examen
approved	Compte validé (recto + verso requis)
rejected	Dossier refusé (rejectionMotif)

Les réponses API utilisent des codes d'erreur stables (TRANSITAIRE_VERIF_PENDING, etc.) et des messages localisés via Accept-Language. Voir Internationalisation.

Notifications et temps réel

Push (FCM)

Événements notifiés via notificationController :

Type	Déclencheur
transit_selection	Acheteur choisit un transitaire
transit_transfer	Mission passée en transferer
transit_rejected	Transitaire refuse la mission

Socket.io

Le contrôleur émet transit-mission-update au transitaire connecté lors des changements de statut :

global.io.to(socketId).emit('transit-mission-update', {
  missionId: String(mission._id),
  statut: mission.statut,
});

Chat

La messagerie acheteur ↔ transitaire passe par /api/chat (Socket.io + REST). Voir WhatsApp & notifications.

Intégration mobile

App	Écrans / flux
Tranoo	Parcours achat → choix destination → sélection transitaire → transfert
Tranoo Pro	Liste missions transitaire, acceptation/refus, clôture

Abonnement transitaire

Les transitaires peuvent avoir un abonnement actif (Subscription) géré comme les vendeurs. Les tarifs admin sont configurés via /api/admin/transitaire-subscription-pricing.

Fichiers source

Fichier	Rôle
src/controllers/transitMissionController.js	Logique missions
src/controllers/transitaireVerificationController.js	Vérification comptes
src/controllers/transitaireReviewController.js	Avis
src/routes/transitMission.js	Routes missions
src/routes/transitaireVerification.js	Routes vérification
src/models/TransitMission.js	Schéma MongoDB

OpenAPI : fichier paths/11-transitaires-transit-stats.js. Voir API Swagger.

Voir aussi

• Vue d'ensemble
• Base de données — modèles Transit
• Architecture Mobile — Tranoo Pro transitaires
• Paiements FeexPay — abonnements transitaire