Conventions

Format JSON, dates, pagination par en-têtes, filtres de liste, enveloppe ActionResponse et identifiants métier.

Format JSON

Champs en anglais, camelCase (companyBrokerId, effectiveDate).
Les champs null sont omis des réponses : testez l'absence d'une clé, pas sa nullité.
Montants en FCFA, nombres décimaux (au plus deux décimales), jamais en centimes.
Identifiants : UUID sous forme de chaîne.
Codes métier véhicule issus du référentiel eAtCI : types TV01–TV13, catégories 01–12, genres GV01–GV12, énergies SEDI/SEEL/SEES/SEHY, usages UV01–UV10. Dans les corps de requête on envoie toutefois l'identifiant du référentiel (brandId, usageId…), pas le code.
Une exception historique : l'apporteur se nomme referreId dans le JSON (et referrerId dans le domaine).

Dates

Contexte	Format	Exemple
Dates de contrat en entrée (`effectiveDate` de `POST /provider/contracts`, `PATCH …/duration`)	`yyyy-MM-dd HH:mm:ss`	`2026-11-07 00:00:01`
Dates civiles (naissance, 1ʳᵉ mise en circulation, permis)	`yyyy-MM-dd`	`2019-03-20`
Dates-heures en sortie	ISO 8601 sans fuseau	`2026-10-06T08:38:39`
`periodStart` d'une cotation d'avenant	ISO 8601	`2026-12-01T00:00:00+00:00`
Bornes et valeurs de filtre des états	ISO 8601 (`yyyy-MM-dd` accepté pour un DATETIME)	`2026-10-01T00:00:00`

Toutes les heures sont exprimées dans le fuseau Africa/Abidjan (UTC+0).

Pagination

Les listes renvoient le tableau en corps et les métadonnées en en-têtes :

En-tête	Type	Sens
`X-Page`	int	page courante, à partir de 0
`X-Size`	int	taille de page
`X-Total`	long	nombre total d'éléments
`X-Total-Pages`	int	nombre de pages

Paramètres : page (défaut 0) et size (défaut 10, 20 pour les états, 50 pour les motifs, 100 pour les types d'avenant).

curl -si "$API/provider/contracts?page=0&size=20" -H "Authorization: Bearer $TOKEN" | grep -i '^x-'

X-Page: 0
X-Size: 20
X-Total: 1432
X-Total-Pages: 72

Exception : les listes de modèles d'état et d'exécutions d'état renvoient la pagination dans le corps (content, page, size, totalElements, totalPages, first, last).

Les listes acceptent des filtres sous la forme filter[champ]=valeur. Le champ peut traverser une relation avec un point (filter[contract.id]). Les champs texte font une recherche contient, insensible à la casse ; les autres une égalité. Les filtres non reconnus sont ignorés.

Liste	Filtres acceptés
`GET /provider/contracts`, `/proposals`	`proposalNumber`, `policyNumber` (contient), `contractType`, `status`, `broker.id`, `company.id`, `subscriber.id`, `referrer.id`, `endorsement.id`
`GET /provider/endorsements`, `/contracts/{id}/endorsements`	`reference`, `contract.policyNumber`, `contract.proposalNumber` (contient), `contract.id`, `status`, `endorsementType.id`, `endorsementType.endorsementCode`, `premiumImpact`
`GET …/payments`	`paymentReference`, `externalTransactionId` (contient), `paymentMethod`, `status`, `contract.id`, `contract.policyNumber`, `contractEndorsement.id`
`GET /provider/lnk-broker-companies`	`query` (recherche globale), `companyCode`, `brokerCode`, `broker.id`, `company.id`, `companyBrokerCode`, `partnershipStatus`
`GET /provider/insureds`	`lastName`, `firstNames`, `companyName`, `email`, `mobilePhone`, `clientNumber` (contient), `personType`, `nationalIdNumber`, `drivingLicenseNumber`
`GET /provider/vehicles/models`	`brand.id`, `modelCode`, `modelLabel` (contient)
`GET /provider/vehicles/brands`	`brandLabel` (contient)
`GET /provider/reasons`	`typeId`, `label` (contient), `isActive`

GET /provider/subscribers utilise un paramètre query unique (nom, pièce, téléphone…).

Enveloppe ActionResponse

Certaines opérations renvoient une enveloppe plutôt que l'objet nu : création de souscripteur, d'assuré, de véhicule, cotation d'avenant, renvoi et annulation de lien de paiement.

{
  "success": true,
  "message": "Souscripteur créé",
  "status": "Completed",
  "id": "dae6bf98-00e3-4bb3-9f5c-2e6bef6f882e",
  "data": { "id": "dae6bf98-00e3-4bb3-9f5c-2e6bef6f882e", "personType": "PHYSIQUE", "...": "..." }
}

Champ	Type	Description
`success`	boolean	`true` si l'opération a réussi
`message`	string	Message métier
`data`	objet ou tableau	Charge utile
`id`	string	Identifiant lié (parfois)
`status`	string	`Completed`, `Failed`…

Identifiants à connaître

Champ	Source	Rôle
`companyBrokerId`	`GET /provider/lnk-broker-companies` → `id`	Partenariat ; la compagnie du lien devient l'assureur
`subscriberId`	`POST`/`GET /provider/subscribers` → `id`	Souscripteur du contrat
`insuredId`	`POST`/`GET /provider/insureds` → `id`	Assuré, posé sur chaque véhicule du contrat
`referreId`	`POST`/`GET /provider/referrers` → `id`	Apporteur (optionnel)
`durationCode`	`GET /provider/durations` → `durationCode`	Durée de couverture (ex. `12_MOIS`)
`vehicleIds`	`POST`/`GET /provider/vehicles` → `id`	Véhicules déjà en base, au moins un
`endorsementId` (type)	`GET /provider/endorsement-types` → `id`	Type d'avenant à coter
`contractId`	`POST /provider/contracts` → `id`	Proposition puis contrat
`endorsementId` (acte)	avenant → `id`	Avenant à payer, consulter, documenter

Statuts HTTP

Code	Quand
`200`	Lecture, mise à jour, action
`201`	Création (proposition, souscripteur, modèle d'état, génération d'état…)
`204`	Suppression ou favori sans contenu
`400`	Corps invalide ou règle métier non respectée
`401` / `403`	Jeton absent ou rôle insuffisant
`404`	Ressource introuvable ou hors périmètre
`502` / `503`	Service de la plateforme (authentification, paiement, documents) momentanément en erreur

Format JSON

Dates

Filtres de liste

Enveloppe ActionResponse

Identifiants à connaître

Statuts HTTP

On this page