Parcours de souscription
Les cinq phases du cycle prestataire, de l'authentification aux avenants, et la séquence d'appels recommandée.
Vue d'ensemble
| Phase | Objectif | Endpoints |
|---|---|---|
| A. Authentification | Obtenir et renouveler le jeton | POST /provider/token, POST /provider/token/refresh |
| B. Prérequis | Réunir les identifiants du contrat | GET /provider/lnk-broker-companies, GET /provider/durations, POST/GET /provider/subscribers, /insureds, /referrers, GET/POST /provider/vehicles/* |
| C. Proposition | Créer la proposition DRAFT, tarifée, avec son avenant affaire nouvelle QUOTE | POST /provider/contracts, GET /provider/contracts/{id}, /proposals |
| D. Tarification et paiement | Recalculer si besoin, générer le lien de paiement, suivre l'encaissement | POST …/tarification/{id}/calculate, POST …/{id}/pay, GET …/{id}/payments/status |
| E. Avenants | Gérer le contrat émis : changement d'immatriculation, incorporation, suspension, résiliation… | GET /provider/endorsement-types, /reasons, PATCH /provider/endorsements/{contractId}, POST …/payment/init |
Après paiement confirmé, l'émission (numéro de police, attestation, documents, écritures) est réalisée automatiquement par la plateforme. Vous n'avez rien à appeler : consultez le contrat et ses documents.
Séquence
Ce que fait le serveur à la création
POST /provider/contracts enchaîne, de façon synchrone :
- vérification de chaque
vehicleId(existence, visibilité,numberOfSeatsrenseigné) ; - création du contrat
DRAFT, typeMONOouFLEETselon le nombre de véhicules ; - rattachement du souscripteur, de l'assuré (posé sur chaque véhicule) et de l'apporteur ;
- dérivation de l'assureur et du courtier depuis
companyBrokerId; - tarification et création (ou resynchronisation) de l'avenant affaire nouvelle en
QUOTE; - retour du contrat avec
primeRc,primeDr,primeNette,accessoire,taxe,cedeao,fga,primeTtc.
Règles de modification d'une proposition
Tant que la proposition est en DRAFT et qu'aucun lien de paiement n'est en attente, vous pouvez :
| Action | Endpoint | Effet |
|---|---|---|
| Changer la durée ou la date d'effet | PATCH /provider/contracts/{contractId}/duration | Recalcule échéance et primes |
| Rattacher un véhicule | POST …/{contractId}/link/vehicles/{vehicleId} | Recalcule la prime, bascule en FLEET si ≥ 2 |
| Retirer un véhicule | POST …/{contractId}/unlink/vehicles/{vehicleId} | Au moins un véhicule doit rester |
| Changer le souscripteur | PATCH …/{contractId}/subscriber/{subscriberId} | |
| Changer l'assuré | PATCH …/{contractId}/insured/{insuredId} | Appliqué à tous les véhicules |
| Changer l'apporteur | PATCH …/{contractId}/referrer/{referrerId} | |
| Recalculer | POST …/tarification/{contractId}/calculate | Resynchronise l'avenant QUOTE |
Si un lien de paiement est en cours, ces appels répondent 400 PROPOSAL_LOCKED_FOR_PAYMENT :
annulez-le d'abord avec POST /provider/endorsements/{contractId}/payment/cancel. Après paiement,
la proposition n'est plus modifiable (CONTRACT_NOT_MODIFIABLE) : passez par un avenant.
Idempotence et doublons
L'API n'a pas de clé d'idempotence. Protégez vos appels d'écriture contre le double envoi (anti
double-clic, verrou côté client) : deux POST /provider/contracts identiques créent deux propositions,
et deux POST …/pay rapprochés peuvent produire deux liens de paiement.