Sandbox & recette

Differences sandbox / production, scenarios de test et verifications avant go-live.

Sandbox vs Production

Aspect	Sandbox	Production
Base URL	`https://sandbox.api.insurance-agg.example`	`https://api.insurance-agg.example`
Clés API	`pk_test_...`	`pk_live_...`
Passerelle de paiement	Mode test (aucun débit réel)	Mode live (débit réel)
ASKIA	Émission simulée (contrats factices)	Émission réelle
Webhooks sortants	Envoyés vers l'URL configurée en sandbox	Envoyés vers l'URL prod
Rate limits	60 req/min	Défini par contrat partenaire
Données	Peuvent être purgées à tout moment	Rétention selon politique légale

Ne jamais mélanger clés et URLs. Une clé pk_test_ appelée sur le domaine production (ou l'inverse) retourne 401 Unauthorized.

Obtenir un accès sandbox

Demander à l'équipe intégration : une clé pk_test_ et un compte partenaire sandbox.
Configurer votre endpoint webhook en sandbox (peut être un tunnel ngrok ou équivalent pour le développement local).
Enregistrer l'URL avec PATCH /api/v1/partners/me/webhook.

Scénarios de test à couvrir

Happy path
Création de session → paiement simulé OK → réception webhook insurance.contract.issued.
Paiement annulé
Création de session → clic "annuler" sur la passerelle → pas de webhook → vérifier via GET /partner/contracts/requests/:reference que le contractStatus = PAYMENT_FAILED.
Paiement expiré
Création de session → attendre TTL → status = expired.
Émission échouée
Utiliser un payload ou un cas sandbox fourni par le support declenchant une erreur ASKIA simulee → reception insurance.contract.issuance_failed.
Signature invalide (négatif)
Envoyer un faux POST vers votre endpoint avec signature incorrecte → votre handler doit retourner 401 et ne pas traiter.
Retry webhook
Renvoyer 500 depuis votre endpoint sur la première livraison → vérifier que l'agrégateur rejoue selon le backoff.
Idempotence
Rejouer 3 fois le même webhook → votre base n'a qu'une seule entrée.

Jeux de données sandbox

Plutot que de dependre d identifiants magiques cote partenaire, la sandbox doit servir a valider des scenarios :

Scenario	Attendu
Moto `<= 125` avec `scatCode=010`	Demande acceptee puis paiement testable.
Moto `> 125` avec `scatCode=011` et `pfs > 125`	Demande acceptee puis emission possible.
Moto `> 125` avec `scatCode=011` mais `pfs <= 125`	Rejet metier `422 validation_failed`.
Webhook partenaire invalide	Retry ou echec de livraison cote partenaire.
Emission simulee en echec	`insurance.contract.issuance_failed` ou `ISSUANCE_FAILED`.

Si l equipe support vous fournit des valeurs sandbox specifiques pour declencher un cas particulier, traitez-les comme des donnees de recette, pas comme une contrainte d integration durable.

Simuler un webhook entrant paiement (debug interne)

Cette section est principalement utile côté agrégateur. Pour un partenaire, il n'est généralement pas nécessaire de simuler ce webhook: le paiement sandbox déclenche naturellement la chaîne complète.

Si besoin (par exemple pour rejouer manuellement une session), l'admin peut POSTer vers POST /api/v1/webhooks/dexpay avec le header x-webhook-signature calculé via HMAC SHA256 et le secret sandbox.

Outils recommandés côté partenaire

Tunnel local : ngrok http 3000, cloudflared tunnel, localtunnel.
Inspecteur webhook : RequestBin, Webhook.site, Hookdeck (pour debug).
Client HTTP : curl, Postman, Insomnia.
Vérification signature : tests unitaires dédiés (voir exemples Node.js / Python dans Webhooks sortants).

Passage en production

Checklist avant go-live :

Signature webhook vérifiée systématiquement (test négatif inclus).
Endpoint webhook HTTPS avec certificat valide (pas auto-signé).
Timeout < 5s, traitement déporté en async.
Idempotence sur x-insurance-reference.
Alerting câblé sur insurance.contract.issuance_failed.
Logs conservés 30 jours minimum, avec x-request-id.
Clé production obtenue, clé sandbox retirée des configs prod.
Tests de charge si volume attendu > 10 req/s.

Voir aussi Go-live checklist.