Documentation pour développeurs

Intégrer le calculateur

L'option la plus simple — insérez notre calculateur dans votre page sous forme d'iframe. Nous offrons une version épurée (sans en-tête ni pied de page INTEGRIS) à l'adresse /calculatorskinny : elle s'intègre proprement dans n'importe quelle mise en page.

<iframe
  src="https://integris-mgt.com/calculatorskinny"
  width="100%"
  height="700"
  title="INTEGRIS PPP Calculator"
  loading="lazy"
  style="border: 0;"
></iframe>

Une hauteur d'environ 700 px convient à la plupart des mises en page. Le calculateur est adaptatif — accordez-lui toute la largeur dont vous disposez.

Variante RRI

Ajoutez ?plan=ipp pour afficher l'intégration aux couleurs du RRI. La légende indique « RRI » au lieu de « PPP® », le curseur d'âge est limité à 40 ans et plus, et le panneau de statistiques affiche « Votre avantage RRI ».

<iframe
  src="https://integris-mgt.com/calculatorskinny?plan=ipp"
  width="100%"
  height="700"
  title="INTEGRIS IPP Calculator"
  loading="lazy"
  style="border: 0;"
></iframe>

Masquer notre appel à l'action

Par défaut, le calculateur affiche sous le résultat un bouton INTEGRIS « Obtenir mon illustration personnalisée ». Si vous préférez intégrer votre propre appel à l'action, ajoutez ?cta=off pour le masquer — les curseurs, le graphique et les statistiques du résultat demeurent identiques.

<iframe
  src="https://integris-mgt.com/calculatorskinny?cta=off"
  width="100%"
  height="700"
  title="INTEGRIS PPP Calculator"
  loading="lazy"
  style="border: 0;"
></iframe>

Les paramètres se combinent — par exemple, ?plan=ipp&cta=off affiche l'intégration RRI sans l'appel à l'action INTEGRIS.

Créer votre propre interface avec notre API

Si vous souhaitez maîtriser entièrement l'apparence, appelez directement notre point de terminaison de projection et affichez les chiffres comme bon vous semble : votre propre bibliothèque de graphiques, un tableau, une mise en page sur mesure.

Point de terminaison

POST https://integris-mgt.com/api/calculators/pppvsrsp
Content-Type: application/json

Corps de la requête

Les quatre premiers champs sont obligatoires et doivent être numériques. rrspBalance est facultatif. Les valeurs hors intervalle sont silencieusement ramenées aux bornes plutôt que rejetées : l’API ne refuse donc jamais une requête d’apparence valide — reproduisez ces bornes dans votre propre interface si vous souhaitez offrir une expérience utilisateur soignée.

Si vous recueillez un âge plutôt qu’une année de naissance, transmettez age (18 à 71) au lieu de yearOfBirth : nous le convertissons en fonction de l’année d’évaluation. yearOfBirth demeure le champ canonique et celui à privilégier : un âge n’est exact que jusqu’au prochain anniversaire du participant, de sorte qu’un résultat mis en cache selon l’âge se périme silencieusement, contrairement à un résultat fondé sur l’année de naissance. Si vous transmettez les deux, yearOfBirth l’emporte. Les lignes sont indexées sur l’âge du participant à la date d’évaluation : sLabels[0] peut donc afficher un an de moins que l’age transmis — soit le comportement du curseur d’âge de notre propre calculateur.

Le transfert admissible

Le rachat de service passé exige un transfert admissible provenant du REER du participant. La réponse le communique sous qt, et rrspBalance le détermine; les trois cas se comportent donc différemment :

• Vous omettez rrspBalance — nous supposons que le participant détient exactement le montant du transfert admissible et établissons la projection sur cette base. La réponse reprend ce montant présumé dans rrspBalance et attribue la valeur true à rrspBalanceAssumed. Il s’agit de l’hypothèse par défaut documentée, et non d’un solde nul.
• Vous fournissez un solde égal ou supérieur à qt — les deux projections débutent à ce solde et rrspBalanceAssumed vaut false.
• Vous fournissez un solde inférieur à qt — la projection présume tout de même que le transfert intégral est effectué : l’avantage illustré pourrait donc être irréalisable. La réponse comporte alors un avertissement rrsp_below_qualifying_transfer :

{
  "qt": 556000,
  "rrspBalance": 100000,
  "rrspBalanceAssumed": false,
  "warnings": [
    {
      "code": "rrsp_below_qualifying_transfer",
      "message": "The qualifying transfer required to purchase the past service shown in this illustration (approximately $556,000) exceeds the RRSP balance you entered. …"
    }
  ]
}

Réponse

La réponse compte toujours 53 lignes annuelles à partir de l’âge actuel du participant. La plupart des intégrateurs souhaitent tronquer à la fin naturelle du décaissement — la première ligne après le sommet où sPPP atteint 0 — pour que le graphique se termine proprement à la retraite au lieu de s’étirer sur une série de zéros. Retenez la fenêtre qui convient à votre mise en page.

{
  "sStatus": "success",
  "sLabels": ["45 years", "46 years", "47 years", "48 years", "...", "97 years"],
  "sPPP":   [600000,      648120,      699554,      754531,     // 53 entries
             /* … */],
  "sRRSP":  [600000,      631200,      664022,      698552,
             /* … */],
  "qt": 556000,
  "rrspBalance": 600000,
  "rrspBalanceAssumed": false,
  "warnings": []
}

• sLabels — 53 chaînes indiquant l'âge, à partir de l'âge saisi ("{n} years").
• sPPP — total projeté dans le régime de retraite à chacun de ces âges, en dollars.
• sRRSP — total projeté dans un REER équivalent à chacun de ces âges, à des fins de comparaison.
• qt — transfert admissible requis pour financer le rachat de service passé, en dollars. Vaut 0 lorsque yearsOfService est 0.
• rrspBalance — le solde réellement utilisé pour la projection, après application des bornes et de notre hypothèse par défaut.
• rrspBalanceAssumed — vaut true lorsque vous n’avez transmis aucun solde et que nous y avons substitué qt.
• warnings — tableau, vide la plupart du temps. Chaque entrée comporte un code stable et un message prêt à afficher.

Réponses d'erreur

• 400 — il manque un champ obligatoire dans le corps de la requête, ou l'une des valeurs n'est pas numérique. Les valeurs numériques hors intervalle ne renvoient pas de 400; elles sont ramenées aux bornes silencieusement.
• 405 — la méthode de la requête n'est pas POST.
• 500 — erreur du moteur de calcul. Ne devrait pas se produire en utilisation normale; écrivez-nous si vous en rencontrez une.

Exemple — curl

curl -X POST https://integris-mgt.com/api/calculators/pppvsrsp \
  -H "Content-Type: application/json" \
  -d '{"yearOfBirth":1981,"yearsOfService":20,"currentSalary":305000,"averagePastSalary":160000,"rrspBalance":600000}'

Exemple — JavaScript

const res = await fetch('https://integris-mgt.com/api/calculators/pppvsrsp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    yearOfBirth: 1981,        // 1955–2008, integer
    yearsOfService: 20,       // 0–50, integer
    currentSalary: 305000,    // 70000–500000, dollars (not $1000s)
    averagePastSalary: 160000,// 0–500000, dollars
    rrspBalance: 600000,      // optional, 0–2000000, dollars
  }),
});

const { sLabels, sPPP, sRRSP, qt, warnings } = await res.json();
// 53 yearly rows starting at the member's current age. Slice the window you
// want (e.g. the next 25 years of accumulation) and feed it into your chart.

// Always render these — see "The qualifying transfer" below.
for (const w of warnings) console.warn(w.code, w.message);

Limites de débit et mise en cache

Mettez en cache sans retenue.Les réponses sont entièrement déterministes — le même tuple d’entrée (yearOfBirth, yearsOfService, currentSalary, averagePastSalary, rrspBalance) renvoie toujours les mêmes 53 lignes. Si vous appelez l’API depuis la boucle d’appel d’outils d’un LLM, mettez en cache selon une empreinte de ces cinq valeurs; il n’est presque jamais nécessaire d’appeler deux fois pour les mêmes entrées.

Plafond indicatif : environ 10 requêtes/seconde par intégration.Aucun quota strict pour l'instant, mais limitez les rafales simultanées afin que les utilisateurs réels ne subissent pas un démarrage à froid pendant l'exécution de votre traitement par lots. Nous publierons une véritable réponse 429 si cela devient un problème.

Le démarrage à froid prend environ 13 secondes, contre environ 400 ms pour un appel à chaud. La fonction conserve son moteur de formules en mémoire entre les requêtes : le premier appel après une période d'inactivité ou après un déploiement peut donc accuser un léger délai. Considérez un premier appel lent comme normal, et non comme un échec.

Prévoyez une temporisation en cas d'erreur 5xx.Exponentielle, 3 nouvelles tentatives au maximum. Nous préchauffons la fonction durant les heures ouvrables en semaine, mais des erreurs transitoires demeurent possibles.

Aucun renseignement personnel.Les quatre entrées sont des nombres scalaires — n'envoyez jamais de noms, de courriels, de numéros de compte ni quoi que ce soit qui pourrait identifier une personne réelle.