Flow assurance-first

Le partenaire crée une demande de contrat, reçoit un lien de paiement, puis suit l'émission automatique.

Principe

Le partenaire intègre une API métier assurance:

créer une demande de contrat,
rediriger le client vers le lien de paiement,
attendre l'émission automatique après paiement confirmé.

Le détail technique du provider de paiement reste géré par la plateforme.

Le partenaire ne cree pas directement une police. Il cree une demande de contrat qui deviendra un contrat actif uniquement apres paiement confirme puis emission ASKIA reussie.

Creation

1 appel

POST /partner/contracts/auto/classic

Reconciliation

1 reference

Une cle stable pour relire le statut a tout moment.

Webhook

2 evenements

Succes d emission ou echec apres paiement confirme.

Vue d'ensemble

Créer la demande
Appeler POST /api/v1/partner/contracts/auto/classic. Réponse: reference, contractStatus = PENDING_PAYMENT, payment.paymentUrl.
Payer
Rediriger l'utilisateur final vers payment.paymentUrl.
Émission auto
Après paiement confirmé, la plateforme émet le contrat ASKIA automatiquement.
Recevoir webhook
Recevoir insurance.contract.issued ou insurance.contract.issuance_failed.
Réconciliation
Optionnel: lire l'état avec GET /api/v1/partner/contracts/requests/:reference.

Donnees a conserver cote partenaire

reference pour tous les appels de reconciliation
payment.paymentUrl pour ouvrir ou presenter le paiement
payment.expiresAt pour gerer une eventuelle expiration cote UX
dernier contractStatus connu pour eviter les incoherences front/back-office

Endpoints de ce flow

POST/api/v1/partner/contracts/auto/classic

Point d entree principal pour demarrer le parcours partenaire.

GET/api/v1/partner/contracts/requests/{reference}

Endpoint de relecture si le partenaire veut verifier l etat ou corriger un webhook manque.

PATCH/api/v1/partners/me/webhook

Etape obligatoire avant go-live pour recevoir les statuts d emission.

Exemple rapide

1. Créer une demande de contrat

curl -X POST "https://api.insurance-agg.example/api/v1/partner/contracts/auto/classic" \
  -H "x-api-key: pk_live_9f8a...redacted" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 29ac64f1-2c7c-4b7f-a0ee-7fc404d4d056" \
  -d '{
    "returnUrl": "https://partner.example.com/payment/success",
    "cancelUrl": "https://partner.example.com/payment/cancel",
    "itemName": "Assurance moto BMW 1250 - 1 mois",
    "countryISO": "SN",
    "customer": {
      "name": "Awa Diop",
      "email": "awa.diop@example.sn",
      "phone": "+221771234567"
    },
    "contract": {
      "cliCode": "8400C000012",
      "cat": "550",
      "scatCode": "011",
      "carrCode": "10",
      "nrg": "E00001",
      "pfs": 1250,
      "nbP": 2,
      "dure": 1,
      "effet": "24/04/2026",
      "numImmat": "AA1250BM",
      "mqCode": "M00065",
      "modele": "R1250GS"
    }
  }'

Réponse:

{
  "message": "Demande de contrat créée. Paiement requis avant émission.",
  "data": {
    "reference": "AUTO_CLASSIC_1713950000000_ab12cd34ef56",
    "contractStatus": "PENDING_PAYMENT",
    "payment": {
      "paymentUrl": "https://pay....",
      "expiresAt": "2026-04-24T15:30:00Z",
      "amount": 6537,
      "currency": "XOF"
    }
  }
}

2. Vérifier l'état de la demande

curl -X GET "https://api.insurance-agg.example/api/v1/partner/contracts/requests/AUTO_CLASSIC_1713950000000_ab12cd34ef56" \
  -H "x-api-key: pk_live_9f8a...redacted"

Que faire selon le statut

`contractStatus`	Action recommandee
`PENDING_PAYMENT`	Attendre le paiement ou proposer de rouvrir le lien avant expiration.
`PAYMENT_FAILED`	Afficher un echec/annulation de paiement et permettre un nouveau parcours.
`ISSUANCE_IN_PROGRESS`	Afficher un etat "traitement en cours".
`ACTIVE`	Recuperer les liens documentaires et cloturer le parcours.
`ISSUANCE_FAILED`	Declencher support et informer le client qu un traitement est en cours.
`REFUNDED`	Afficher un statut final rembourse si applicable.

Statuts métier

`contractStatus`	Signification
`PENDING_PAYMENT`	Paiement en attente.
`PAYMENT_FAILED`	Paiement annulé/en échec.
`ISSUANCE_IN_PROGRESS`	Paiement validé, émission en cours.
`ACTIVE`	Contrat émis avec succès.
`ISSUANCE_FAILED`	Paiement validé, émission échouée.
`REFUNDED`	Paiement remboursé.

ISSUANCE_FAILED signifie que le client a payé mais le contrat n'est pas encore émis. Traiter ce cas comme prioritaire côté support.