Bonnes pratiques

Ce qui distingue une intégration qui fonctionne d'une intégration solide : sécurité, reprise après incident, paiement, et expérience de votre client.

Sécurité

• La clé reste sur votre serveur. Votre application mobile ou votre site appellent votre serveur, qui appelle l'API. Une clé placée dans une application peut être extraite par n'importe qui.
• Variables d'environnement pour la clé, le secret de signature et le secret de notifications. Jamais dans votre dépôt de code ni dans vos journaux.
• Restreignez les adresses IP en production : demandez à COVERAF de n'accepter que celles de vos serveurs.
• Changez de clé sans coupure : demandez une nouvelle clé, déployez-la, puis faites révoquer l'ancienne. Au moindre doute de fuite, prévenez immédiatement contact@optimus-ci.com.
• Vérifiez chaque notification (signature et horodatage) avant de la traiter.

Fiabilité

• Une Idempotency-Key par opération, générée avant la boucle d'essais (voir Idempotence).
• Délai d'attente de 30 secondes par appel. L'émission d'un contrat prend quelques secondes.
• Enregistrez les identifiants renvoyés (dev_..., sou_..., numéro de contrat) dès leur réception, et votre propre référence dans reference_partenaire : vous retrouvez ainsi chaque vente des deux côtés.
• Journalisez le requete_id de chaque appel en erreur : c'est ce que le support vous demandera.

Paiement

• Ne considérez jamais une vente comme conclue avant que l'API l'ait confirmée : statut: payee et contrat.numero présent.
• Mode A : déclarez l'encaissement seulement une fois l'argent reçu, avec le montant exact et une référence unique.
• Mode B : affichez à votre client qu'il doit valider sur son téléphone, et prévoyez l'échec. Après un échec, proposez de réessayer, éventuellement avec un autre opérateur.
• Notifications et consultation : utilisez les notifications, et gardez la consultation de la souscription en secours si une notification tarde.

Notifications

app.post('/webhooks/coveraf', express.raw({ type: 'application/json' }), async (req, res) => {
  const corps = req.body.toString('utf8') // corps BRUT, avant toute relecture du JSON
  if (!signatureValide(corps, req.get('X-Coveraf-Timestamp'), req.get('X-Coveraf-Signature'))) {
    return res.status(401).end()
  }
  const evenement = JSON.parse(corps)
  res.status(200).end() // répondre vite (moins de 10 secondes)...

  if (await dejaTraite(evenement.id)) return // ...puis ignorer les doublons
  await mettreEnFile(evenement) // et traiter à part
})

• Répondez 2xx en moins de 10 secondes, puis traitez l'événement à part.
• Dédoublonnez avec id : un événement peut arriver plusieurs fois.
• L'ordre n'est pas garanti : en cas de doute, relisez l'état avec GET /v1/souscriptions/{id}.

Expérience de votre client

• Affichez prime.totale : c'est le montant payé, taxes comprises.
• Présentez les Conditions Générales avant le paiement (obligation légale), puis remettez les Conditions Particulières et, pour un voyage, l'attestation de chaque voyageur.
• Affichez les erreurs de saisie champ par champ grâce à erreur.details, en reformulant les messages pour votre client.
• Prévenez de l'expiration : un prix est garanti 15 jours. Au-delà, demandez un nouveau devis sans faire tout ressaisir.
• Masquez une offre dont disponible vaut false dans GET /v1/produits.