# Souscrire et gérer les contrats Garance par API

> Polysème est la solution d’exposition d’API et le moteur d’actes de gestion de Garance. Assurance vie, contrats de capitalisation, PER individuel, PER obligatoire, prévoyance : souscrivez puis gérez chaque contrat tout au long de sa vie, depuis votre propre système.

Commencer par le [démarrage rapide](/quickstart.md). Norme de référence : [Penelop V1.1 (API globale)](https://penelop.org/swagger-ui/dist/?urls.primaryName=API+Globale+-V1.1+production).

## Les principes

- **Machine to machine, sécurisé** : Une API REST en JSON, appelée par votre backend, sans interface imposée. OAuth2 client credentials, scopes par rôle : chaque distributeur ne voit que ses propres demandes et contrats.
- **Fondé sur la norme Penelop** : Les payloads suivent la norme d’échange de la place pour l’épargne assurance : un requestSummary qui décrit la demande, un requestDetail qui porte son contenu. Même structure pour la souscription et les actes de gestion.
- **Piloté par le référentiel** : Produits, offres, supports, compartiments et règles se lisent dans l’API Referential. Une nouvelle offre ou un nouveau support ne demande aucun changement de code de votre côté.

## Ce que couvre Polysème

Chaque acte de gestion se fait par API, avec votre propre parcours, ou par un POTO (Polysème One-Time Operation) : un lien éphémère à usage unique que le client ou son conseiller finalise sur une page Polysème. Voir [Opérations de vie du contrat](/operations.md).

- **Souscription** : Création de la demande, pièces justificatives, contrôles KYC/KYT, signature électronique et transmission à l’assureur.
- **Versement libre** : Versement ponctuel sur un contrat existant.
- **Versements programmés** : Mise en place, modification du montant ou de la répartition, suspension, reprise et arrêt.
- **Arbitrage** : Déplacement de l’épargne entre supports, dans le même contrat.
- **Changement de profil** : Nouveau profil de risque pour la gestion pilotée.
- **Changement de mode de gestion** : Passage de la gestion libre à la gestion pilotée, et inversement.
- **Gestion des poches** : Plusieurs poches par contrat (assurance vie et PER), chacune avec son mode de gestion et sa répartition.
- **Rachats** : Rachat partiel et rachat total.
- **Transferts entrants** (à venir, juin 2027) : Transfert vers un contrat Garance, demandé en autonomie par API, en individuel comme en collectif.
- **Rachats partiels programmés** (à venir, juin 2027) : Retrait d’une somme à intervalle régulier.

## Comprendre avant d’intégrer

- [Concepts clés](/concepts.md) : Distributeur, offre, demande, contrat : le vocabulaire de l’API en une page.
- [Produits Garance](/produits.md) : Assurance vie, capitalisation, PER, PERO, prévoyance : ce que chaque famille permet.
- [Souscrire un contrat](/souscription.md) : Le parcours complet, de l’offre au numéro de contrat.

## Les API

- [Referential](/openapi/openapi_referential.json) (14 endpoints) : Assureurs, distributeurs, produits, supports et offres auxquelles vous avez droit.
- [Subscription](/openapi/openapi_subscription.json) (11 endpoints) : Démarrer une souscription, déposer ses pièces et suivre son statut jusqu’à l’intégration chez l’assureur.
- [Contract](/openapi/openapi_contract.json) (24 endpoints) : Opérations sur les contrats en vie : versements libres et programmés, rachats, arbitrages, personnes.
- [POTO](/openapi/openapi_poto.json) (4 endpoints) : Polysème One-Time Operation : un lien éphémère à usage unique pour qu’un client finalise une opération en ligne.