Modèles de données

Les objets que l'API renvoie, champ par champ. Les exemples sont des réponses réelles de la sandbox.

Conventions

Montants : nombres entiers en FCFA (XOF), sans décimales.
Dates : AAAA-MM-JJ. Instants : ISO 8601 en UTC.
Un champ sans valeur vaut null : il n'est pas omis.
De nouveaux champs peuvent apparaître : votre code doit les ignorer, pas les refuser.

Offre

GET /v1/produits, GET /v1/produits/{code}

Champ	Type	Toujours présent	Description
`code`	texte	oui	Code de l'offre, à envoyer dans offre lors d'un devis.
`produit`	texte	oui	Famille : sante, habitation, commerce, vie, voyage, accidents.
`libelle`	texte	oui	Nom commercial, à afficher.
`description`	texte	oui	Résumé de la couverture.
`duree`	texte	oui	Durée de couverture (ou durées possibles pour un voyage).
`documents`	liste de textes	oui	Types de documents remis (voir Constantes).
`disponible`	booléen	oui	false : offre momentanément retirée de la vente.
`garanties`	objet	oui	Garanties, capitaux et limites d'âge, propres à chaque offre (voir la page du produit).
`exemple_devis`	objet	non	Consultation d'une seule offre : un corps de POST /v1/devis prêt à l'emploi.

Exemple

{
  "code": "securvie_500k",
  "produit": "vie",
  "libelle": "SecurVie 500 000 FCFA",
  "description": "Assurance temporaire décès : capital versé aux bénéficiaires en cas de décès de l'assuré.",
  "duree": "12 mois",
  "documents": [
    "conditions_generales",
    "conditions_particulieres"
  ],
  "disponible": true,
  "garanties": {
    "capital_deces": 500000,
    "age_max": 65
  },
  "exemple_devis": {
    "offre": "securvie_500k",
    "donnees": {
      "assure": {
        "date_naissance": "1985-06-15"
      }
    }
  }
}

Devis

POST /v1/devis, GET /v1/devis/{id}

Champ	Type	Toujours présent	Description
`id`	texte	oui	Identifiant : dev_ suivi de 24 caractères.
`objet`	« devis »	oui
`environnement`	« test » \| « live »	oui
`offre`	texte	oui	Code de l'offre.
`produit`	texte	oui	Famille de produit.
`prime`	Prime	oui	Le prix (voir Prime ci-dessous).
`duree_mois`	entier	oui	Durée de couverture en mois.
`detail`	objet \| null	oui	Habitation et commerce : capitaux assurés et garanties retenues. null pour les autres produits.
`donnees`	objet	oui	Les informations de tarification reçues, après normalisation.
`reference_partenaire`	texte \| null	oui	Votre référence.
`expire_le`	instant ISO 8601 (UTC)	oui	Fin de validité du prix (15 jours). Au-delà, une souscription est refusée.
`expire`	booléen	oui	true si expire_le est passé.
`cree_le`	instant ISO 8601 (UTC)	oui

Exemple

{
  "id": "dev_68e56446d4b5c6875911f178",
  "objet": "devis",
  "environnement": "test",
  "offre": "securvie_500k",
  "produit": "vie",
  "prime": {
    "nette": 11000,
    "accessoires": 0,
    "taxes": 1980,
    "totale": 12980,
    "devise": "XOF"
  },
  "duree_mois": 12,
  "detail": null,
  "donnees": {
    "assure": {
      "date_naissance": "1985-06-15"
    }
  },
  "reference_partenaire": "CMD-2026-0042",
  "expire_le": "2026-11-19T17:35:33.439+00:00",
  "expire": false,
  "cree_le": "2026-11-04T17:35:33.447204+00:00"
}

Prime

dans Devis et Contrat

Champ	Type	Toujours présent	Description
`nette`	entier, FCFA	oui	Prime hors taxes.
`accessoires`	entier, FCFA	oui	Frais accessoires.
`taxes`	entier, FCFA	oui	Taxes.
`totale`	entier, FCFA	oui	Montant payé par le client. C'est le montant à afficher.
`devise`	« XOF »	oui	Franc CFA (BCEAO).

Exemple

{
  "nette": 11000,
  "accessoires": 0,
  "taxes": 1980,
  "totale": 12980,
  "devise": "XOF"
}

Souscripteur

envoyé dans POST /v1/souscriptions

Le client final, celui qui souscrit et paie. Commun à tous les produits. Les réponses n'en renvoient qu'une partie (nom, prénom, téléphone, et email pour un contrat).

Champ	Type	Obligatoire	Description
`nom`	texte	oui	Nom du client final (120 caractères max).
`prenom`	texte	oui	Prénom(s).
`telephone`	texte	oui	8 à 15 chiffres, indicatif « + » accepté. Ex. +2250701020304.
`email`	texte	non	Adresse email valide.
`adresse`	texte	non	Adresse postale ou quartier (200 caractères max).
`date_naissance`	date AAAA-MM-JJ	non	Recommandé pour Habitation, Commerce et Accidents (imprimée sur les Conditions Particulières).

Exemple

{
  "nom": "KONE",
  "prenom": "Awa",
  "telephone": "+2250701020304",
  "email": "awa.kone@example.com",
  "adresse": "Cocody, Abidjan",
  "date_naissance": "1990-04-12"
}

Souscription

POST /v1/souscriptions, GET /v1/souscriptions/{id}, paiement

Champ	Type	Toujours présent	Description
`id`	texte	oui	Identifiant : sou_ suivi de 24 caractères.
`objet`	« souscription »	oui
`environnement`	« test » \| « live »	oui
`statut`	« en_attente_paiement » \| « payee » \| « expiree »	oui	Voir Constantes.
`devis_id`	texte	oui	Le devis d'origine.
`montant_a_payer`	{ montant, devise }	oui	Montant exact à encaisser (prime totale du devis).
`mode_paiement`	« encaissement_partenaire » \| « jeko »	oui	Mode A (vous encaissez) ou mode B (COVERAF encaisse en Mobile Money).
`date_effet_prevue`	date AAAA-MM-JJ	oui	Début de couverture demandé.
`souscripteur`	{ nom, prenom, telephone }	oui
`reference_partenaire`	texte \| null	oui
`paiement`	Paiement \| null	oui	Mode B : la dernière tentative de paiement Mobile Money. null en mode A.
`contrat`	{ numero, adresse } \| null	oui	Rempli dès que le contrat est émis.
`expire_le`	instant ISO 8601 (UTC)	oui	Même date que le devis.
`payee_le`	instant ISO 8601 (UTC) \| null	oui
`cree_le`	instant ISO 8601 (UTC)	oui

Exemple

{
  "id": "sou_f6ac5791c1dd467dd238607f",
  "objet": "souscription",
  "environnement": "test",
  "statut": "payee",
  "devis_id": "dev_44cfca8ed08b74ff676b9474",
  "montant_a_payer": {
    "montant": 12980,
    "devise": "XOF"
  },
  "mode_paiement": "jeko",
  "date_effet_prevue": "2026-11-04",
  "souscripteur": {
    "nom": "KONE",
    "prenom": "Awa",
    "telephone": "+2250701020304"
  },
  "reference_partenaire": "CMD-2026-0042",
  "paiement": {
    "id": "pay_e6bf7dd3fd60f74b08c1fef9",
    "statut": "reussi",
    "operateur": "orange",
    "montant": 12980,
    "lien_paiement": null,
    "motif_echec": null,
    "cree_le": "2026-11-04T17:35:45.931257+00:00"
  },
  "contrat": {
    "numero": "TEST-CVR-API-MW2EE3CW-0845CBC0B0",
    "adresse": "/v1/contrats/TEST-CVR-API-MW2EE3CW-0845CBC0B0"
  },
  "expire_le": "2026-11-19T17:35:42.74+00:00",
  "payee_le": "2026-11-04T17:35:49.232+00:00",
  "cree_le": "2026-11-04T17:35:43.359143+00:00"
}

Paiement (mode B)

champ paiement d'une souscription

Champ	Type	Toujours présent	Description
`id`	texte	oui	Identifiant : pay_ suivi de 24 caractères.
`statut`	« en_attente » \| « reussi » \| « echoue »	oui
`operateur`	texte	oui	Opérateur Mobile Money (voir Constantes).
`montant`	entier, FCFA	oui
`lien_paiement`	adresse \| null	oui	Page de paiement à ouvrir pour le client, tant que le paiement est en attente.
`motif_echec`	texte \| null	oui	Si statut = echoue (voir Constantes).
`cree_le`	instant ISO 8601 (UTC)	oui

Exemple

{
  "id": "pay_e6bf7dd3fd60f74b08c1fef9",
  "statut": "en_attente",
  "operateur": "orange",
  "montant": 12980,
  "lien_paiement": "http://localhost:3005/sandbox/paiement/pay_e6bf7dd3fd60f74b08c1fef9",
  "motif_echec": null,
  "cree_le": "2026-11-04T17:35:45.931257+00:00"
}

Contrat

GET /v1/contrats/{numero}

Champ	Type	Toujours présent	Description
`numero`	texte	oui	CVR-API-... en production, TEST-CVR-API-... en sandbox.
`objet`	« contrat »	oui
`environnement`	« test » \| « live »	oui
`statut`	« actif » \| « expire » \| « suspendu » \| « annule »	oui	Actif dès son émission.
`offre`	texte	oui
`produit`	texte	oui
`devis_id`	texte	oui
`souscription_id`	texte	oui
`reference_partenaire`	texte \| null	oui
`prime`	Prime	oui
`date_effet`	date AAAA-MM-JJ	oui	Début de couverture : la date demandée, ou le jour du paiement s'il est plus tardif.
`date_echeance`	date AAAA-MM-JJ	oui	Fin de couverture.
`duree_mois`	entier	oui
`souscripteur`	{ nom, prenom, telephone, email }	oui
`assures`	liste	non	Consultation d'un contrat : personnes couvertes (santé : role, nom, prenoms, sexe, date_naissance ; voyage : les voyageurs). Liste vide pour les autres produits. Absent de la liste des contrats.
`paiement`	{ montant, moyen, paye_le } \| null	oui	Consultation d'un contrat : le paiement. null dans la liste des contrats.
`documents`	liste de Document	oui	Documents du contrat.
`cree_le`	instant ISO 8601 (UTC)	oui

Exemple

{
  "numero": "TEST-CVR-API-MW2EDTG6-F92441FC41",
  "objet": "contrat",
  "environnement": "test",
  "statut": "actif",
  "offre": "securvie_500k",
  "produit": "vie",
  "devis_id": "dev_68e56446d4b5c6875911f178",
  "souscription_id": "sou_8a1ab1eb752f13c8f09bb0b6",
  "reference_partenaire": "CMD-2026-0042",
  "prime": {
    "nette": 11000,
    "accessoires": 0,
    "taxes": 1980,
    "totale": 12980,
    "devise": "XOF"
  },
  "date_effet": "2026-11-04",
  "date_echeance": "2027-11-03",
  "duree_mois": 12,
  "souscripteur": {
    "nom": "KONE",
    "prenom": "Awa",
    "telephone": "+2250701020304",
    "email": "awa.kone@example.com"
  },
  "assures": [],
  "paiement": {
    "montant": 12980,
    "moyen": "Orange Money (encaissé par le partenaire)",
    "paye_le": "2026-11-04T17:35:36.2+00:00"
  },
  "documents": [
    {
      "type": "conditions_generales",
      "disponible": true,
      "adresse": "/v1/contrats/TEST-CVR-API-MW2EDTG6-F92441FC41/documents/conditions_generales"
    },
    {
      "type": "conditions_particulieres",
      "disponible": true,
      "adresse": "/v1/contrats/TEST-CVR-API-MW2EDTG6-F92441FC41/documents/conditions_particulieres"
    }
  ],
  "cree_le": "2026-11-04T17:35:36.575052+00:00"
}

Document

champ documents d'un contrat

Champ	Type	Toujours présent	Description
`type`	texte	oui	conditions_generales, conditions_particulieres ou attestation.
`disponible`	booléen	oui	Les Conditions Générales le sont toujours ; les autres tant que le contrat est actif.
`adresse`	chemin	oui	À appeler avec GET pour obtenir le PDF.

Exemple

{
  "type": "conditions_particulieres",
  "disponible": true,
  "adresse": "/v1/contrats/TEST-CVR-API-MW2EDTG6-F92441FC41/documents/conditions_particulieres"
}

Liste

GET /v1/contrats

Champ	Type	Toujours présent	Description
`objet`	« liste »	oui
`donnees`	liste	oui	Les éléments de la page, du plus récent au plus ancien.
`suite`	instant ISO 8601 (UTC) \| null	oui	À passer dans ?avant= pour la page suivante. null : dernière page.

Exemple

{
  "objet": "liste",
  "donnees": [
    "…"
  ],
  "suite": "2026-11-04T16:44:34.688451+00:00"
}

Événement (notification)

envoyé à votre serveur

Champ	Type	Toujours présent	Description
`id`	texte	oui	Identifiant : evt_ suivi de 24 caractères. Servez-vous-en pour ignorer les doublons.
`objet`	« evenement »	oui
`type`	texte	oui	Voir Constantes.
`environnement`	« test » \| « live »	oui
`cree_le`	instant ISO 8601 (UTC)	oui
`donnees`	objet	oui	Contenu propre au type (voir Notifications).

Exemple

{
  "id": "evt_5f1c2a9be04d77a3c1d2e8f0",
  "objet": "evenement",
  "type": "contrat.emis",
  "environnement": "test",
  "cree_le": "2026-11-04T17:35:56.305Z",
  "donnees": {
    "souscription_id": "sou_f6ac5791c1dd467dd238607f",
    "contrat_numero": "TEST-CVR-API-MW2EE3CW-0845CBC0B0"
  }
}

Erreur

toute réponse 4xx ou 5xx

Champ	Type	Toujours présent	Description
`erreur.code`	texte	oui	Code stable : appuyez votre code dessus (voir Codes d'erreur).
`erreur.message`	texte	oui	Explication en français, peut évoluer.
`erreur.documentation`	adresse	non	Lien vers la description du code.
`erreur.details`	liste de { champ, message }	non	Erreur de saisie : chaque champ fautif.
`requete_id`	texte	oui	Référence de l'appel, à donner au support.

Exemple

{
  "erreur": {
    "code": "validation",
    "message": "Certaines données sont manquantes ou incorrectes. Voir erreur.details.",
    "documentation": "https://docs.coveraf.com/erreurs#validation",
    "details": [
      {
        "champ": "assures[0].date_naissance",
        "message": "Date invalide, format attendu AAAA-MM-JJ."
      },
      {
        "champ": "assures[0].sexe",
        "message": "Valeur inconnue « H ». Valeurs possibles : M, F."
      }
    ]
  },
  "requete_id": "req_909aa466a35b048c634bdc80"
}