Vue d'ensemble

Pourquoi cette API existe

L'objectif n'est pas d'exposer la complexite d'un provider paiement ou d'ASKIA. L'objectif est de donner au partenaire une API assurance simple:

• preparer une demande de contrat,
• creer une demande de contrat,
• rediriger vers un lien de paiement,
• recuperer le contrat emis ou l'erreur d'emission.

À qui s'adresse cette documentation

Cette documentation est destinée aux équipes d'intégration backend des partenaires distributeurs (banques, néobanques, marketplaces, courtiers, aggrégateurs tiers) qui souhaitent revendre des contrats d'assurance automobile émis par ASKIA via notre plateforme d'agrégation.

Ce que fait l'API Partenaire

En tant que partenaire vous pouvez :

• créer une demande de contrat et récupérer un lien de paiement,
• suivre le statut métier du contrat (en attente, actif, échec, remboursé),
• configurer votre webhook de réception d'événements,
• recevoir automatiquement le contrat émis (ou la cause d'échec) sur votre webhook.

Avant le premier test

1. Recuperer une cle sandbox et un compte partenaire de recette.
2. Configurer un endpoint webhook HTTPS ou un tunnel local.
3. Tester le flow complet depuis Reference API puis valider les cas issued et issuance_failed.

Vous ne pouvez pas :

• créer un contrat directement (émission auto réservée à l'administration),
• modifier un contrat déjà émis,
• contourner le paiement via la passerelle de paiement.

Règle d'or : le flow payment-first

La création d'un contrat est pilotée par le paiement. Autrement dit, aucun contrat n'est émis tant qu'un paiement n'est pas confirmé.

Endpoints essentiels

1. Demande de contrat

   Le partenaire appelle POST /api/v1/partner/contracts/auto/classic avec les données de souscription. L'agrégateur retourne une reference et un paymentUrl.

2. Paiement

   L'utilisateur final est redirigé vers payment_url et règle sa prime.

3. Webhook entrant paiement

   La passerelle notifie l'agrégateur sur POST /api/v1/webhooks/dexpay avec une signature x-webhook-signature (HMAC SHA256).

4. Émission ASKIA

   L'agrégateur déclenche l'émission du contrat côté ASKIA.

5. Webhook sortant partenaire

   L'agrégateur POST vers l'URL webhook du partenaire un événement insurance.contract.issued (succès) ou insurance.contract.issuance_failed (échec).

6. Suivi de statut

   Optionnel: GET /api/v1/partner/contracts/requests/:reference pour la réconciliation.

Architecture en un coup d'œil

sequenceDiagram
  participant P as Partenaire
  participant U as Utilisateur
  participant AGG as Agrégateur
  participant DX as Paiement
  participant AS as ASKIA

  P->>AGG: POST /partner/contracts/auto/classic
  AGG->>DX: Création session
  DX-->>AGG: payment_url, reference
  AGG-->>P: 201 { payment_url, reference }
  P->>U: Redirection vers payment_url
  U->>DX: Paiement
  DX->>AGG: POST /webhooks/dexpay (HMAC)
  AGG->>AS: Émission contrat
  AS-->>AGG: Contrat émis (ou erreur)
  AGG->>P: POST webhook partenaire (signé)
  P->>AGG: GET /partner/contracts/requests/:reference (optionnel)

Environnements

Les URL exactes sandbox/production sont communiquées pendant l'onboarding. Conservez une stricte séparation des clés et webhooks par environnement.

Parcours recommande

1. Lire Authentification.
2. Lire Flow assurance-first.
3. Tester POST /partner/contracts/auto/classic dans la Reference API.
4. Configurer le webhook partenaire.
5. Valider les cas issued et issuance_failed en sandbox.
6. Passer la Go-live checklist.

Prochaines étapes