From 877947e82ab9a14797634399a211b9851d078db9 Mon Sep 17 00:00:00 2001 From: Johan Girod Date: Mon, 19 Sep 2022 18:28:00 +0200 Subject: [PATCH] =?UTF-8?q?Am=C3=A9liore=20la=20documentation=20de=20l'API?= =?UTF-8?q?=20et=20de=20la=20biblioth=C3=A8que?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 12 +- .../règles/entreprise/établissement.yaml | 2 + modele-social/règles/salarié/cotisations.yaml | 1 + site/source/components/PageHeader.tsx | 6 +- site/source/design-system/typography/index.ts | 5 + site/source/locales/rules-en.yaml | 7 +- site/source/locales/ui-en.yaml | 160 +++++++++------ site/source/locales/ui-fr.yaml | 182 +++++++++++------- site/source/pages/integration/API.tsx | 104 +++++----- site/source/pages/integration/Iframe.tsx | 6 +- site/source/pages/integration/Library.tsx | 119 ++++-------- site/source/pages/integration/Options.tsx | 2 +- .../_components/CasParticuliers.tsx | 150 +++++++++++++++ .../integration/_components/StepByStep.tsx | 48 +++++ .../integration/_images/API_illustration.svg | 1 + .../integration/{images => _images}/cci.png | Bin .../{ => _images}/illustration.png | Bin .../{ => _images}/illustration_library.svg | 0 .../{images => _images}/logo-betagouv.svg | 0 .../{images => _images}/min-tra.jpg | Bin .../{images => _images}/pole-emploi.png | Bin 21 files changed, 518 insertions(+), 287 deletions(-) create mode 100644 site/source/pages/integration/_components/CasParticuliers.tsx create mode 100644 site/source/pages/integration/_components/StepByStep.tsx create mode 100644 site/source/pages/integration/_images/API_illustration.svg rename site/source/pages/integration/{images => _images}/cci.png (100%) rename site/source/pages/integration/{ => _images}/illustration.png (100%) rename site/source/pages/integration/{ => _images}/illustration_library.svg (100%) rename site/source/pages/integration/{images => _images}/logo-betagouv.svg (100%) rename site/source/pages/integration/{images => _images}/min-tra.jpg (100%) rename site/source/pages/integration/{images => _images}/pole-emploi.png (100%) diff --git a/README.md b/README.md index 42239bdd3..c6febae11 100644 --- a/README.md +++ b/README.md @@ -10,21 +10,21 @@ Ce dépôt contient : [![Statut test](https://github.com/betagouv/mon-entreprise/actions/workflows/test.yaml/badge.svg?branch=master)](https://github.com/betagouv/mon-entreprise/actions/workflows/test.yaml?query=branch%3Amaster++) [![Gitter chat](https://badges.gitter.im/mon-entreprise/community.png)](https://gitter.im/mon-entreprise/community) -Site développé en partenariat avec l'Urssaf, qui a pour mission d'accompagner des créateurs d’entreprise dans le développement de leur activité. +Site développé en partenariat avec l’Urssaf, qui a pour mission d’accompagner des créateurs d’entreprise dans le développement de leur activité. -Il propose notamment des simulateurs de cotisations sociales très complets, basés sur le language déclaratif [publicodes](https://publi.codes). On peut ainsi calculer le coût d'une embauche, un salaire net après impôt, ses revenus d'auto-entrepreneur ou encore ceux d'un dirigeant de SASU ou d'indépendant +Il propose notamment des simulateurs de cotisations sociales très complets, basés sur le language déclaratif [publicodes](https://publi.codes). On peut ainsi calculer le coût d’une embauche, un salaire net après impôt, ses revenus d’auto-entrepreneur ou encore ceux d’un dirigeant de SASU ou d’indépendant > 🧮 [Voir la liste des simulateurs](https://mon-entreprise.urssaf.fr/simulateurs) -Les développeurs ont la possibilité d'intégrer ces simulateurs sur d'autres sites, ou de réutiliser les règles pour effectuer leur propre calculs. +Les développeurs peuvent intégrer ces simulateurs sur d’autres sites, ou de réutiliser les règles pour effectuer leur propre calculs. > 🧰 [Voir les outils à disposition des développeurs](https://mon-entreprise.urssaf.fr/int%C3%A9gration) -Tous les outils proposés sur mon-entreprise sont propulsés par [publicodes](https://publi.codes), un nouveau langage pour les algorithmes d'intérêt public. +Tous les outils proposés sur mon-entreprise sont propulsés par [publicodes](https://publi.codes), un nouveau langage pour les algorithmes d’intérêt public. ## Contribuer -Si vous souhaitez contribuer à l'un des deux projets, rendez-vous sur [CONTRIBUTING.md](./CONTRIBUTING.md). +Si vous souhaitez contribuer à l’un des deux projets, rendez-vous sur [CONTRIBUTING.md](./CONTRIBUTING.md). ## 🇬🇧 English users @@ -36,6 +36,6 @@ Most of the documentation (including issues and commit message) is written in fr The website will run well on modern browsers. Internet Explorer is not supported anymore (it should work but with visual glitches and performance issues). -This compatibility is tested thanks to [BrowserStack](http://browserstack.com/)'s free open source program. +This compatibility is tested thanks to [BrowserStack](http://browserstack.com/)’s free open source program. ![Logo de Browserstack, notre solution de tests manuels](https://i.imgur.com/dQwLjXA.png) diff --git a/modele-social/règles/entreprise/établissement.yaml b/modele-social/règles/entreprise/établissement.yaml index e8cb5f611..003f94543 100644 --- a/modele-social/règles/entreprise/établissement.yaml +++ b/modele-social/règles/entreprise/établissement.yaml @@ -5,6 +5,7 @@ applicable si: entreprise . SIREN établissement . localisation: + experimental: oui icônes: 🌍 description: | Lorsqu'une entreprise dispose de plusieurs établissements, certaines cotisations sont @@ -54,6 +55,7 @@ - département = 'La Réunion' établissement . versement mobilité: + experimental: oui unité: '%' par défaut: oui synchronisation: diff --git a/modele-social/règles/salarié/cotisations.yaml b/modele-social/règles/salarié/cotisations.yaml index 1330e94c3..fee152b90 100644 --- a/modele-social/règles/salarié/cotisations.yaml +++ b/modele-social/règles/salarié/cotisations.yaml @@ -563,6 +563,7 @@ salarié . cotisations . chômage: valeur: 4.05% salarié . cotisations . ATMP: + experimental: oui titre: Cotisation Accidents du Travail et Maladies Professionnelles description: Cotisation due au titre des Accidents du Travail et Maladies Professionnelles. cotisation: diff --git a/site/source/components/PageHeader.tsx b/site/source/components/PageHeader.tsx index 4814edd04..f78bcfdf9 100644 --- a/site/source/components/PageHeader.tsx +++ b/site/source/components/PageHeader.tsx @@ -38,7 +38,11 @@ export default function PageHeader({ align-items: flex-start; `} > - {titre &&

{titre}

} + {titre && ( + <> +

{titre}

+ + )}
{children}
diff --git a/site/source/design-system/typography/index.ts b/site/source/design-system/typography/index.ts index c241232f3..79ac02fb4 100644 --- a/site/source/design-system/typography/index.ts +++ b/site/source/design-system/typography/index.ts @@ -11,3 +11,8 @@ export const Strong = styled.strong` export const U = styled.u` text-decoration: underline; ` +export const Code = styled.code` + background-color: #eee; + padding: 0.25rem; + border-radius: 0.25rem; +` diff --git a/site/source/locales/rules-en.yaml b/site/source/locales/rules-en.yaml index 896806eda..8a8f0640d 100644 --- a/site/source/locales/rules-en.yaml +++ b/site/source/locales/rules-en.yaml @@ -3553,8 +3553,8 @@ dirigeant . rémunération . totale: question.fr: Quel montant total pensez-vous dégager pour votre rémunération ? résumé.en: '[automatic] Including dues and contributions' résumé.fr: Incluant les cotisations et contributions - titre.en: '[automatic] total' - titre.fr: totale + titre.en: '[automatic] Total compensation' + titre.fr: Rémunération totale déclaration charge sociales: description.en: '[automatic] These rules calculate the amounts of social charges @@ -4823,6 +4823,9 @@ entreprise . résultat fiscal . rémunération dirigeant déductible: déductibles d'impôt. titre.en: '[automatic] deductible executive compensation' titre.fr: rémunération dirigeant déductible +entreprise . salariés: + titre.en: '[automatic] employees' + titre.fr: salariés entreprise . salariés . effectif: titre.en: '[automatic] workforce' titre.fr: effectif diff --git a/site/source/locales/ui-en.yaml b/site/source/locales/ui-en.yaml index d5b34abed..9b3144445 100644 --- a/site/source/locales/ui-en.yaml +++ b/site/source/locales/ui-en.yaml @@ -1129,77 +1129,63 @@ pages: cta: See the help title: How to declare your income to the tax authorities? développeur: - api: "<0>Use our REST API <1><0>API in beta version<1>Some breaking - changes are likely to be made in the coming weeks.<2>Feel free to give - feedback on its use directly on Github.<2>If your site or service - requires to make calculations on salaries, for example to pass from gross - salary to net salary, good news: all calculations of contributions and - taxes of my-company are free and usable via our REST API.<3><0>Try the - API<4>How to use this API?<5>The my-company api is totally - open and without authentication, it is composed of 3 routes inspired by - the methods of the <1>Publicodes interpreter: <4>/evaluate, - <6>/rules and <9>/rules/:rule. Find more information on our - <12>Swagger UI.<14><6><0>What is - Publicodes?<1>Publicodes is a declarative language developed by - beta.gouv.fr and Urssaf to encode public interest algorithms. All our - calculation rules are implemented in this language.<2><0>Learn more - about publicodes<7>Example<8>Here is an example of how to - use the different routes, you can explore their code in the - <1>examplefolder<9><0>" + api: '<0><0>You can reuse the calculations of my-company on your site or service + very easily thanks to our open REST API and without + authentication.<1>Access the Swagger<1>How to perform a + calculation via the API?<2>To perform a calculation, you just have to + make a <1>POST on the <4>/evaluate route with the following + parameters:<3><0><0>expressions: the name of the rules whose value + you want to calculate<1><0>situation: the situation for the + calculation<4><0>See the example in the Swagger<5>How to + replicate a calculation of a simulator ?<6><0>To replicate a + calculation from a simulator in my-company in the library, here is the + procedure: <7><0><1><0>In the "Rule and situation" section, + you will find the name of the rule and the situation to use as parameters + for calling/evaluate.<1>You can also find the API request to copy + and paste as a <3>curl call or <5>fetchJavaScriptin the "Reuse + this calculation" section.<7><8><9>Example<10>Here is + an example of how to use the different routes, you can explore their code + in the <1>example folder<11><0>' bibliothèque: '<0><0>You can reuse the calculations of my-company on your site or service very easily thanks to the open-source JavaScript library available on npm.<1>How to use this library ?<2>Installation<3><0>npm install --save publicodes - modele-social<4><0>What does publicodes mean?<1>Publicodes is - a declarative language developed by beta.gouv.fr and the Urssaf to encode - algorithms of public interest. <2>Learn more about publicodes<2>To - run your own calculations, you need to install the package - <2><0>publicodes package containing the interpreter, as well as - the <6><0>modele-socialpackage, which contains the rules of the - my-company simulators.<5>Launch the calculation<6>All you have - to do is to set the engine with the rules of the `social-modele` package - and to call the `evaluate` function on the rule you want the value of. - Here is an example for the gross/net - calculation<7><0><8>Setting up the calculation<9>As you + modele-social<4>To run your own calculations, you need to install + the package <2><0>publicodes package containing the publicodes + interpreter, and the <6><0>modele-socialpackage, which contains + the rules of the my-company simulators.<5><0>What is publicodes + ?<1>Publicodes is a declarative language developed by beta.gouv.fr and + the Urssaf to encode algorithms of public interest. It is the language + that powers all the calculations of the mon-entreprise + simulators.<2><0>Learn more about publicodes<6>Launch the + calculation<7>To launch the calculation, you need to set up the engine + with the rules of the <1>social-model package and to call the + <4>evaluate function with the rule whose value you want to calculate. + Here is an example for the gross / net + calculation<8><0><9>Setting up the calculation<10>As you can see in the previous example, the recipe for a calculation is simple: - input variables (the gross salary), one or more output variables (the net - salary).<10>However, the calculation can be parameterized with all the - possibilities allowed in the simulators of my-company!<11>All + input variables (gross salary), one or more output variables (net + salary).<11>However, the calculation can be parameterized with all + the possibilities allowed in the simulators of my-company!<12>All available rules are listed and explained in the <2>online documentation. This documentation is auto-generated from the - publicodes rules files, and fed by the current simulation.<12>How to - replicate a calculation from a simulator?<13>To replicate a + publicodes rules files, and fed by the current simulation.<13>How to + replicate a calculation from a simulator?<14>To replicate a calculation from a simulator of my-company in the library, here are the - steps to follow: <14><0><0>Choose the simulator according to the - calculation we are interested in<1>For example the <4>employee - simulator to calculate a net from the gross.<1><0>Run a simulation - with the data you wish to reuse<1>For example, <4>a manager at - 3400 € gross with meal vouchers.<2>Go to<0>the documentation page - of the data to be calculated<1>For example by clicking on "Net - salary" in the simulator, or by searching for "Net salary" in the search - box on the top right.<3><0>Copy the customized code extract and - integrate it in your application<1>. You will find it by clicking - on the "Reuse this calculation" section.<3><4><0>(optional) Modify - the values of the situation to set the calculation according to your - needs<1> You can modify without hesitation the values of the - situation. They accept any <4>expression or publicodes - object.<15>Here is what the calculation gives with the - example quoted above:<16><0><17><0>The situation contains - the data of your simulation (executive with a salary of 3400 € gross), but - also the data relating to the parameterization of the - simulator.<18>Special case: the mobility payment - rate<19>Whereas in the <2>employee simulator, all you have to do - is enter the commune and the corresponding rate is automatically - determined. This behavior is not present in the library. This is - deliberate: to keep the library (and the site) light, we use two online - APIs. The<4>Geo - communes API to go from the commune name to the - commune code. Then the<7>Mobility API, developed and maintained by us, - which is not documented but its use is very simple and understandable - <10>in this React component that calls it, component that also calls - the common API.<20>Making economic graphs <1><21>It is also - possible to use the library for economic or political analysis - calculations. Here, we plot the price of labor and the net wage as a - function of the gross wage.<22>One can see the progressivity of the + steps to follow: <15><0><1><0>Copy the custom code snippet and + integrate it into your application<1>You can find it by clicking + on the "Reuse this calculation" section.<3><2><0>(optional) Modify + the values of the situation to set up the calculation according to your + needs<1> You can modify the values of the situation without + hesitation. These values accept any <4>expression or publicodes + object.<16>Here is what the calculation gives with the + example quoted above:<17><0><18><0>The situation contains + the data of your simulation (executive with salary at 3400 € gross), but + also the data related to the parameterization of the + simulator.<19><20>Making economic graphs <1><21>It + is also possible to use the library for economic or political analysis + calculations. Here, we plot the price of work and the net salary as a + function of the gross salary.<22>We can see the progressivity of the total wage, which is in percent lower for a minimum wage than for a high wage. In other words, high earners pay part of the social contributions of low earners.<23><0>' @@ -1222,6 +1208,54 @@ pages: code: description: "Here is the code to copy and paste on your site:" titre: Integration Code + components: + CasParticuliers: '<0>Learn more about...<1><0>The + <1>MissingVariables<1>In return of your call to <1>evaluate, + you will get a <3>missingVariables object. This object contains the + list of all the rules used for the calculation whose value is missing in + the input situation. It is a <6>default value that has been used + instead.<2>To further customize your simulation, you can enter their + value.<3><0>The number associated with them corresponds to the + importance of the rule for the calculation: the higher it is, the more + the rule was used by other rules during the + calculation.<2><0>Rules tagged as + <1>experimental<1>Our APIs follow a <2>semantic version + management. This means that all changes made are backwards + compatible, except for major version changes.<2>Rules tagged as + experimental do not obey this specification. This means that they can be + deleted, modified, moved, invisibly for the API user.<3><0>We + therefore advise you to be very careful when using these rules, and to + always check their existence before including them in your application + code.<4><0>How to know if a rule is experimental?<1>You can + know if you are using an experimental rule by looking at the + <1>warnings object provided in return of your call to + <3>evaluate<2>Experimental rules also contain a warning in the + "Reuse this calculation" section of the + documentation.<3><0>Reusing data from external + APIs<1>Some data in the my-company simulators come from external + APIs. You will have to change their value by yourself in the given input + situation.<2>The mobility payment<3><0><0>establishment . + mobility payment<4>In the <2>employee simulator, all you + have to do is enter the municipality and the corresponding mobility + payment rate is automatically determined.<5>You will have to specify + the rate yourself to redo the calculation. You can find it + again:<1><0>By entering your municipality in a simulator, then searching + for the "mobility payment" rule with the "search" button at the top + right<1>Using the <2>dedicated service on + urssaf.fr<6>The collective AT/MP + rate<7><0><0>employee . contributions . ATMP . collective + rate<8>This collective rate must be found manually. You can + use :<1><0><0>A csv export of the table of collective net rates + published in the Official Journal<1>The service <2>Account AT/MP + of net-entreprise' + StepByStep: <0><0>Choose the simulator according to the calculation we are + interested in<1>For example the <4>employee simulator to + calculate a net amount from the gross amount.<1><0>Run a simulation + with the data you wish to reuse<1>For example, <4>a manager at + 3400 € gross with meal vouchers.<2><0>Go to the documentation + page of the data to be calculated<1>For example by clicking on + "Net salary" in the simulator, or by searching for "Net salary" in the + search box at the top right. couleur: "What color? " home: choice: diff --git a/site/source/locales/ui-fr.yaml b/site/source/locales/ui-fr.yaml index dedadabe1..aa49615e5 100644 --- a/site/source/locales/ui-fr.yaml +++ b/site/source/locales/ui-fr.yaml @@ -888,84 +888,69 @@ pages: cta: Consulter l'aide title: Comment déclarer son revenu aux impôts ? développeur: - api: "<0>Utiliser notre API REST <1><0>API en version beta<1>Des - changements cassants sont succeptibles d'être apportés dans les prochaines - semaine.<2>N'hésitez pas à faire des retours sur son utilisation - directement sur Github.<2>Si votre site ou service requiert de - faire des calculs sur des salaires, par exemple passer du salaire brut au - salaire net, bonne nouvelle : tous les calculs de cotisations et impôts de - mon-entreprise sont libres et utilisable via notre API - REST.<3><0>Essayer l'API<4>Comment utiliser cette API - ?<5>L'api mon-entreprise est totalement ouverte et sans - authentification, elle se compose de 3 routes qui s'inspirent des méthodes - de l'interpréteur <1>Publicodes : <4>/evaluate, <6>/rules et - <9>/rules/:rule. Retrouvez plus d'informations sur notre <12>Swagger - UI.<14><6><0>Qu'est ce que Publicodes ?<1>Publicodes est - un language déclaratif développé par beta.gouv.fr et l'Urssaf pour encoder - des algorithmes d'intérêt public. Toutes nos règles de calculs sont - implémentées dans ce language.<2><0>En savoir plus sur - publicodes<7>Exemple<8>Voici un exemple d'utilisation des - différentes routes, vous pouvez explorer leur code dans le dossier - <1>example<9><0>" + api: "<0><0>Vous pouvez réutiliser les calculs de mon-entreprise sur votre site + ou service très facilement grâce à notre API REST ouverte et sans + authentification.<1>Accéder au Swagger<1>Comment effectuer un + calcul via l'API ?<2>Pour effectuer un calcul, il vous suffit de faire + un <1>POST sur la route <4>/evaluate avec les paramètres suivants + :<3><0><0>expressions : le nom des règles dont vous voulez + calculer la valeur<1><0>situation : la situation pour le + paramétrage du calcul<4><0>Voir l'exemple dans le + Swagger<5>Comment reproduire un calcul d'un simulateur + ?<6><0>Pour répliquer un calcul d'un simulateur de mon-entreprise dans + la bibliothèque, voici la marche à suivre : <7><0><1><0>Dans + la section « Règle et situation », vous trouverez le nom de la règle et la + situation à utiliser comme paramètres d'appel + à<1>/evaluate.<1>Vous pouvez également retrouver la requête + API à copier-coller sous forme d'appel <3>curl ou de + <5>fetchJavaScript dans la section « Réutiliser ce calcul + ».<7><8><9>Exemple<10>Voici un exemple d'utilisation + des différentes routes, vous pouvez explorer leur code dans le dossier + <1>example<11><0>" bibliothèque: "<0><0>Vous pouvez réutiliser les calculs de mon-entreprise sur votre site ou service très facilement grâce à la bibliothèque JavaScript open-source disponible sur npm.<1>Comment utiliser cette librairie ?<2>Installation<3><0>npm install --save publicodes - modele-social<4><0>Que signifie publicodes ?<1>Publicodes est - un language déclaratif développé par beta.gouv.fr et l'Urssaf pour encoder - des algorithmes d'intérêt public. <2>En savoir plus sur - publicodes<2>Pour lancer vos propre calculs, vous devons donc - installer le paquet <2><0>publicodes contenant l'intepreteur, - ainsi que le paquet <6><0>modele-social, qui contient les règles - des simulateurs mon-entreprise.<5>Lancer le calcul<6>Il ne - vous reste plus qu'à paramétrer le moteur avec les règles du paquet - `modele-social` et à appeler la fonction `evaluate` sur la règle que dont - vous souhaitez la valeur. Voici un exemple pour le calcul brut / - net<7><0><8>Paramétrer le calcul<9>Vous l'aurez constaté - dans l'exemple précédent, la recette d'un calcul est simple : des - variables d'entrée (le salaire brut), une ou plusieurs variables de - sorties (le salaire net).<10>Le calcul est cependant paramétrable avec - toutes les possibilités permises dans les simulateurs de mon-entreprise - !<11>Toutes les règles disponibles sont listées et expliquées sur la - <2>documentation en ligne. Cette documentation est auto-générée depuis - les fichiers de règles publicodes, et alimentée par la simulation en - cours.<12>Comment reproduire un calcul d'un simulateur ?<13>Pour - répliquer un calcul d'un simulateur de mon-entreprise dans la - bibliothèque, voici la marche à suivre : <14><0><0>Choisir le - simulateur en fonction du calcul qui nous intéresse<1>Par exemple - le <4>simulateur salarié pour calculer un net à partir du - brut.<1><0>Effectuer une simulation avec les données que l'on souhaite - réutiliser<1>Par exemple <4>un cadre à 3400 € brut avec des - titres-restaurants.<2><0>Aller sur la page de documentation de la - donnée à calculer<1>Par exemple en cliquant sur « Salaire net » - dans le simulateur, ou en recherchant « Salaire net » dans la recherche en - haut à droite.<3><0>Copiez l'extrait de code personalisé et - intégrez-le dans votre application<1>Vous le trouverez en cliquant - sur la section « Réutiliser ce calcul ».<3><4><0>(facultatif) - Modifiez les valeur de la situation pour paramétrer le calcul selon vos - besoin<1> Vous pouvez modifier sans hésiter les valeurs de la - situation. Ces dernières acceptent n'importe quelle <4>expression ou objet - publicodes.<15>Voici ce que donne le calcul avec l'exemple - cité ci-dessus :<16><0><17><0>La situation contient les + modele-social<4>Pour lancer vos propres calculs, vous devez + installer le paquet <2><0>publicodes contenant l'interpréteur + publicodes, ainsi que le paquet <6><0>modele-social, qui contient + les règles des simulateurs mon-entreprise.<5><0>Qu'est-ce que + publicodes ?<1>Publicodes est un langage déclaratif développé par + beta.gouv.fr et l'Urssaf pour encoder des algorithmes d'intérêt public. + C'est le langage qui propulse tous les calculs des simulateurs de + mon-entreprise.<2><0>En savoir plus sur + publicodes<6>Lancer le calcul<7>Pour lancer le calcul, il + vous faut paramétrer le moteur avec les règles du paquet + <1>modele-social et à appeler la fonction <4>evaluate avec la + règle dont vous souhaitez calculer la valeur. Voici un exemple pour le + calcul brut / net<8><0><9>Paramétrer le calcul<10>Vous + l'aurez constaté dans l'exemple précédent, la recette d'un calcul est + simple : des variables d'entrée (le salaire brut), une ou plusieurs + variables de sorties (le salaire net).<11>Le calcul est cependant + paramétrable avec toutes les possibilités permises dans les simulateurs de + mon-entreprise !<12>Toutes les règles disponibles sont listées et + expliquées sur la <2>documentation en ligne. Cette documentation est + auto-générée depuis les fichiers de règles publicodes, et alimentée par la + simulation en cours.<13>Comment reproduire un calcul d'un simulateur + ?<14>Pour répliquer un calcul d'un simulateur de mon-entreprise dans + la bibliothèque, voici la marche à suivre : <15><0><1><0>Copiez + l'extrait de code personnalisé et intégrez-le dans votre + application<1>Vous le trouverez en cliquant sur la section « + Réutiliser ce calcul ».<3><2><0>(facultatif) Modifiez les valeurs + de la situation pour paramétrer le calcul selon vos besoins<1> + Vous pouvez modifier sans hésiter les valeurs de la situation. Ces + dernières acceptent n'importe quelle <4>expression ou objet + publicodes.<16>Voici ce que donne le calcul avec l'exemple + cité ci-dessus :<17><0><18><0>La situation contient les données de votre simulation (cadre avec salaire à 3400 € brut), mais - également les données relative au paramétrage du - simulateur.<18>Cas particulier : le taux versement - mobilité<19>Alors que dans le simulateur <2>salarié, il suffit de - renseigner la commune et le taux correspondant est automatiquement - déterminé. Ce comportement n'est pas présent dans la librairie. C'est - voulu : pour garder la bibliothèque (et le site) légers, nous utilisons - deux API en ligne. L'<4>API Géo - communes pour passer du nom de la - commune au code commune. Puis l'<7>API versement mobilité, développé - et maintenu par nos soins, qui n'est pas documenté mais son utilisation - est très simple et compréhensible <10>dans ce composant React qui - l'appelle, composant qui fait aussi appel à l'API - commune.<20>Faire des graphiques économiques <1><21>Il est - aussi possible d'utiliser la bibliothèque pour des calculs d'analyse - économique ou politique. Ici, on trace le prix du travail et le salaire - net en fonction du brut.<22>On peut constater la progressivité du - salaire total, qui est en pourcent plus faible pour un SMIC que pour un - haut revenu. Autrement dit, les hauts salaires paient une partie des - cotisations sociales des bas salaires.<23><0>" + également les données relatives au paramétrage du + simulateur.<19><20>Faire des graphiques économiques + <1><21>Il est aussi possible d'utiliser la bibliothèque pour des + calculs d'analyse économique ou politique. Ici, on trace le prix du + travail et le salaire net en fonction du brut.<22>On peut constater + la progressivité du salaire total, qui est en pourcent plus faible pour un + SMIC que pour un haut revenu. Autrement dit, les hauts salaires paient une + partie des cotisations sociales des bas salaires.<23><0>" choice: github: body: Tous nos outils sont ouverts et développés publiquement sur GitHub. @@ -984,6 +969,57 @@ pages: code: description: "Voici le code à copier-coller sur votre site :" titre: Code d'intégration + components: + CasParticuliers: "<0>En savoir plus sur...<1><0>Les + <1>MissingVariables<1>En retour de votre appel à + <1>evaluate, vous obtiendrez un objet <3>missingVariables. Ce + dernier contient la liste de toutes les règles utilisées pour le calcul + dont la valeur est absente dans la situation en entrée. C'est une + <6>valeur par défaut qui a été utilisée à la place.<2>Pour + personnaliser encore plus votre simulation, vous pouvez renseigner leur + valeur.<3><0>Le nombre qui leur est associé correspond à + l'importance de la règle pour le calcul : plus il est élevé, plus la + règle a été utilisée par d'autres règles lors du + calcul.<2><0>Les règles taguées comme + <1>experimentale<1>Nos API suivent une <2>gestion sémantique de + version. Cela veut dire que toutes les modifications apportées sont + rétrocompatibles, sauf lors de changements de version majeure.<2>Les + règles taguées comme experimentales n'obéissent pas à cette + spécification. Cela veut dire qu'elles peuvent être supprimées, + modifiées, déplacées, de manière invisible pour l'utilisateur de + l'API.<3><0>Nous vous conseillons donc d'être très prudent dans + l'utilisation de ces règles, et de toujours bien vérifier leur existence + avant de les inclure dans votre code applicatif.<4><0>Comment + savoir si une règle est expérimentale ?<1>Vous pouvez savoir si vous + utilisez une règle expérimentale en consultant l'objet <1>warnings + fourni en retour de votre appel à <3>evaluate<2>Les règles + expérimentales contiennent également un avertissement dans la section « + Réutiliser ce calcul » de la documentation.<3><0>Réutiliser + une donnée provenant d'API externes<1>Certaines données des + simulateurs de mon-entreprise proviennent d'API externes. Il vous faudra + ainsi changer leur valeur par vous-même dans la situation donnée en + entrée.<2>Le versement mobilité<3><0><0>établissement . + versement mobilité<4>Dans le simulateur <2>salarié, il + suffit de renseigner la commune et le taux du versement mobilité + correspondant est automatiquement déterminé.<5>Il vous faudra + préciser le taux vous-même pour refaire le calcul. Vous pouvez le + retrouver :<1><0>En saisissant votre commune dans un simulateur, puis en + recherchant la règle « versement mobilité » avec le bouton « rechercher + » en haut à droite<1>Grâce au <2>service dédié sur + urssaf.fr<6>Le taux collectif AT/MP<7><0><0>salarié + . cotisations . ATMP . taux collectif<8>Ce taux collectif + doit être retrouvé manuellement. Vous pouvez utiliser :<1><0><0>Un + export csv du tableau des taux nets collectifs paru au Journal + Officiel<1>Le service <2>Compte AT/MP de + net-entreprise" + StepByStep: <0><0>Choisir le simulateur en fonction du calcul qui nous + intéresse<1>Par exemple le <4>simulateur salarié pour + calculer un net à partir du brut.<1><0>Effectuer une simulation avec + les données que l'on souhaite réutiliser<1>Par exemple <4>un + cadre à 3400 € brut avec des titres-restaurants.<2><0>Aller sur + la page de documentation de la donnée à calculer<1>Par exemple + en cliquant sur « Salaire net » dans le simulateur, ou en recherchant « + Salaire net » dans la recherche en haut à droite. couleur: "Quelle couleur ? " home: choice: diff --git a/site/source/pages/integration/API.tsx b/site/source/pages/integration/API.tsx index 949a402d1..1369bc19d 100644 --- a/site/source/pages/integration/API.tsx +++ b/site/source/pages/integration/API.tsx @@ -1,18 +1,15 @@ -import BetaBanner from '@/components/BetaBanner' +import PageHeader from '@/components/PageHeader' import { ScrollToTop } from '@/components/utils/Scroll' -import { Message } from '@/design-system' import { Button } from '@/design-system/buttons' -import { H1, H2, H3, H4 } from '@/design-system/typography/heading' +import { Code, Strong } from '@/design-system/typography' +import { H2, H3 } from '@/design-system/typography/heading' import { Link } from '@/design-system/typography/link' +import { Li, Ol, Ul } from '@/design-system/typography/list' import { Body, Intro } from '@/design-system/typography/paragraphs' import { Trans } from 'react-i18next' -import styled from 'styled-components' - -const InlineCode = styled.code` - background-color: #eee; - padding: 0.25rem; - border-radius: 0.25rem; -` +import { CasParticuliers } from './_components/CasParticuliers' +import StepByStep from './_components/StepByStep' +import illustration from './_images/API_illustration.svg' export default function API() { return ( @@ -20,60 +17,63 @@ export default function API() { -

Utiliser notre API REST

- -

API en version beta

+ - Des changements cassants sont succeptibles d'être apportés dans les - prochaines semaine. + Vous pouvez réutiliser les calculs de mon-entreprise sur votre site + ou service très facilement grâce à notre API REST ouverte et sans + authentification. - - N'hésitez pas à faire des retours sur son utilisation directement - sur Github. - - - - Si votre site ou service requiert de faire des calculs sur des - salaires, par exemple passer du salaire brut au salaire net, bonne - nouvelle : tous les calculs de cotisations et impôts de mon-entreprise - sont libres et utilisable via notre API REST. - - - -

Comment utiliser cette API ?

- + +

Comment effectuer un calcul via l'API ?

- L'api mon-entreprise est totalement ouverte et sans authentification, - elle se compose de 3 routes qui s'inspirent des méthodes de - l'interpréteur Publicodes :{' '} - /evaluate, /rules et{' '} - /rules/:rule. Retrouvez plus d'informations - sur notre{' '} - Swagger UI. -
+ Pour effectuer un calcul, il vous suffit de faire un POST{' '} + sur la route /evaluate avec les paramètres suivants : + +
    +
  • + expressions : le nom des règles dont vous voulez + calculer la valeur +
    • +
  • + situation : la situation pour le paramétrage du calcul +
    • +
+ + + Voir l'exemple dans le Swagger + - -

Qu'est ce que Publicodes ?

+

Comment reproduire un calcul d'un simulateur ?

+ - Publicodes est un language déclaratif développé par beta.gouv.fr et - l'Urssaf pour encoder des algorithmes d'intérêt public. Toutes nos - règles de calculs sont implémentées dans ce language. + Pour répliquer un calcul d'un simulateur de mon-entreprise dans la + bibliothèque, voici la marche à suivre :{' '} - - - En savoir plus sur publicodes - - - - + +
    + +
  1. + + Dans la section « Règle et situation », vous trouverez le nom de + la règle et la situation à utiliser comme paramètres d'appel à + /evaluate. + +
    + Vous pouvez également retrouver la requête API à copier-coller sous + forme d'appel curl ou de fetch + JavaScript dans la section « Réutiliser ce calcul ». +
    +
    2. +
+

Exemple

Voici un exemple d'utilisation des différentes routes, vous pouvez - explorer leur code dans le dossier example + explorer leur code dans le dossier example
'iframePath' in obj && obj.iframePath && !('private' in obj && obj.private) diff --git a/site/source/pages/integration/Library.tsx b/site/source/pages/integration/Library.tsx index 275547da0..438f03f50 100644 --- a/site/source/pages/integration/Library.tsx +++ b/site/source/pages/integration/Library.tsx @@ -2,14 +2,15 @@ import PageHeader from '@/components/PageHeader' import Emoji from '@/components/utils/Emoji' import { ScrollToTop } from '@/components/utils/Scroll' import { Message } from '@/design-system' -import { Strong } from '@/design-system/typography' +import { Code, Strong } from '@/design-system/typography' import { H2, H3, H4 } from '@/design-system/typography/heading' import { Link } from '@/design-system/typography/link' import { Li, Ol } from '@/design-system/typography/list' import { Body, Intro } from '@/design-system/typography/paragraphs' -import { useSitePaths } from '@/sitePaths' import { Trans } from 'react-i18next' -import illustration from './illustration_library.svg' +import { CasParticuliers } from './_components/CasParticuliers' +import StepByStep from './_components/StepByStep' +import illustration from './_images/illustration_library.svg' export default function Library() { return ( @@ -31,35 +32,39 @@ export default function Library() {

Installation

-					npm install --save publicodes modele-social
+					npm install --save publicodes modele-social
+ + Pour lancer vos propres calculs, vous devez installer le paquet{' '} + + publicodes + {' '} + contenant l'interpréteur publicodes, ainsi que le paquet{' '} + + modele-social + + , qui contient les règles des simulateurs mon-entreprise. + -

Que signifie publicodes ?

+

Qu'est-ce que publicodes ?

+ + Publicodes est un langage déclaratif développé par beta.gouv.fr et + l'Urssaf pour encoder des algorithmes d'intérêt public. C'est le + langage qui propulse tous les calculs des simulateurs de + mon-entreprise. + - Publicodes est un language déclaratif développé par beta.gouv.fr et - l'Urssaf pour encoder des algorithmes d'intérêt public.{' '} En savoir plus sur publicodes - - Pour lancer vos propre calculs, vous devons donc installer le paquet{' '} - - publicodes - {' '} - contenant l'intepreteur, ainsi que le paquet{' '} - - modele-social - - , qui contient les règles des simulateurs mon-entreprise. -

Lancer le calcul

- Il ne vous reste plus qu'à paramétrer le moteur avec les règles du - paquet `modele-social` et à appeler la fonction `evaluate` sur la - règle que dont vous souhaitez la valeur. Voici un exemple pour le - calcul brut / net + Pour lancer le calcul, il vous faut paramétrer le moteur avec les + règles du paquet modele-social et à appeler la fonction{' '} + evaluate avec la règle dont vous souhaitez calculer la + valeur. Voici un exemple pour le calcul brut / net
    +
  1. - Choisir le simulateur en fonction du calcul qui nous intéresse - -
    - Par exemple le{' '} - - simulateur salarié - {' '} - pour calculer un net à partir du brut. -
    2. -
  2. - - Effectuer une simulation avec les données que l'on souhaite - réutiliser - -
    - Par exemple{' '} - - un cadre à 3400 € brut avec des titres-restaurants - - . -
    3. -
  3. - - Aller sur la page de documentation de la donnée à calculer - -
    - Par exemple en cliquant sur « Salaire net » dans le simulateur, ou - en recherchant « Salaire net » dans la recherche en haut à droite. -
    4. -
  4. - - Copiez l'extrait de code personalisé et intégrez-le dans votre + Copiez l'extrait de code personnalisé et intégrez-le dans votre application
    @@ -147,8 +116,8 @@ export default function Library() {
  5. - (facultatif) Modifiez les valeur de la situation pour paramétrer - le calcul selon vos besoin + (facultatif) Modifiez les valeurs de la situation pour paramétrer + le calcul selon vos besoins
    Vous pouvez modifier sans hésiter les valeurs de la situation. Ces dernières acceptent n'importe quelle{' '} @@ -171,33 +140,11 @@ export default function Library() { La situation contient les données de votre simulation (cadre avec - salaire à 3400 € brut), mais également les données relative au + salaire à 3400 € brut), mais également les données relatives au paramétrage du simulateur. -

    Cas particulier : le taux versement mobilité

    - - - Alors que dans le simulateur{' '} - - salarié - - , il suffit de renseigner la commune et le taux correspondant est - automatiquement déterminé. Ce comportement n'est pas présent dans la - librairie. C'est voulu : pour garder la bibliothèque (et le site) - légers, nous utilisons deux API en ligne. L' - - API Géo - communes - {' '} - pour passer du nom de la commune au code commune. Puis l' - API versement mobilité, développé et maintenu par - nos soins, qui n'est pas documenté mais son utilisation est très - simple et compréhensible{' '} - - dans ce composant React qui l'appelle - - , composant qui fait aussi appel à l'API commune. - +

    Faire des graphiques économiques diff --git a/site/source/pages/integration/Options.tsx b/site/source/pages/integration/Options.tsx index 613a2a2cd..23f76a1cd 100644 --- a/site/source/pages/integration/Options.tsx +++ b/site/source/pages/integration/Options.tsx @@ -7,7 +7,7 @@ import { Body, Intro } from '@/design-system/typography/paragraphs' import { useSitePaths } from '@/sitePaths' import { Trans, useTranslation } from 'react-i18next' import Meta from '../../components/utils/Meta' -import illustration from './illustration.png' +import illustration from './_images/illustration.png' export default function Options() { const { absoluteSitePaths } = useSitePaths() diff --git a/site/source/pages/integration/_components/CasParticuliers.tsx b/site/source/pages/integration/_components/CasParticuliers.tsx new file mode 100644 index 000000000..fce9ff302 --- /dev/null +++ b/site/source/pages/integration/_components/CasParticuliers.tsx @@ -0,0 +1,150 @@ +import RuleLink from '@/components/RuleLink' +import { Message } from '@/design-system' +import { Code, Strong } from '@/design-system/typography' +import { H2, H3, H4, H5 } from '@/design-system/typography/heading' +import { Link } from '@/design-system/typography/link' +import { Li, Ul } from '@/design-system/typography/list' +import { Body } from '@/design-system/typography/paragraphs' +import { useSitePaths } from '@/sitePaths' +import { Trans } from 'react-i18next' + +export function CasParticuliers() { + return ( + +

    En savoir plus sur...

    + +
    +

    + Les MissingVariables +

    + + En retour de votre appel à evaluate, vous obtiendrez un + objet missingVariables. Ce dernier contient la liste de + toutes les règles utilisées pour le calcul dont la valeur est absente + dans la situation en entrée. C'est une{' '} + valeur par défaut qui a été utilisée à la place. + + + Pour personnaliser encore plus votre simulation, vous pouvez + renseigner leur valeur. + + + + Le nombre qui leur est associé correspond à l'importance de la règle + pour le calcul : plus il est élevé, plus la règle a été utilisée par + d'autres règles lors du calcul. + + +
    + +
    +

    + Les règles taguées comme experimentale +

    + + Nos API suivent une{' '} + + gestion sémantique de version + + . Cela veut dire que toutes les modifications apportées sont + rétrocompatibles, sauf lors de changements de version majeure. + + + Les règles taguées comme experimentales n'obéissent pas à cette + spécification. Cela veut dire qu'elles peuvent être supprimées, + modifiées, déplacées, de manière invisible pour l'utilisateur de + l'API. + + + + Nous vous conseillons donc d'être très prudent dans l'utilisation de + ces règles, et de toujours bien vérifier leur existence avant de les + inclure dans votre code applicatif. + + + + +
    Comment savoir si une règle est expérimentale ?
    + + Vous pouvez savoir si vous utilisez une règle expérimentale en + consultant l'objet warnings fourni en retour de votre + appel à evaluate + + + Les règles expérimentales contiennent également un avertissement + dans la section « Réutiliser ce calcul » de la documentation. + +     +
    + +
    +

    Réutiliser une donnée provenant d'API externes

    + + Certaines données des simulateurs de mon-entreprise proviennent d'API + externes. Il vous faudra ainsi changer leur valeur par vous-même dans + la situation donnée en entrée. + +

    Le versement mobilité

    + + + + établissement . versement mobilité + + + + + Dans le simulateur{' '} + + salarié + + , il suffit de renseigner la commune et le taux du versement mobilité + correspondant est automatiquement déterminé. + + + Il vous faudra préciser le taux vous-même pour refaire le calcul. Vous + pouvez le retrouver : +
      +
    • + En saisissant votre commune dans un simulateur, puis en + recherchant la règle « versement mobilité » avec le bouton « + rechercher » en haut à droite +
      • +
    • + Grâce au{' '} + + service dédié sur urssaf.fr + +
      • +
    + +

    Le taux collectif AT/MP

    + + + + salarié . cotisations . ATMP . taux collectif + + + + + Ce taux collectif doit être retrouvé manuellement. Vous pouvez + utiliser : +
      +
    • + + Un export csv + {' '} + du tableau des taux nets collectifs paru au Journal Officiel +
      • +
    • + Le service{' '} + + Compte AT/MP + {' '} + de net-entreprise +
      • +
    + +
    +     + ) +} diff --git a/site/source/pages/integration/_components/StepByStep.tsx b/site/source/pages/integration/_components/StepByStep.tsx new file mode 100644 index 000000000..aa57c50ca --- /dev/null +++ b/site/source/pages/integration/_components/StepByStep.tsx @@ -0,0 +1,48 @@ +import { Strong } from '@/design-system/typography' +import { Link } from '@/design-system/typography/link' +import { Li } from '@/design-system/typography/list' +import { useSitePaths } from '@/sitePaths' +import { Trans } from 'react-i18next' + +export default function StepByStep() { + return ( + +
  6. + + Choisir le simulateur en fonction du calcul qui nous intéresse + +
    + Par exemple le{' '} + + simulateur salarié + {' '} + pour calculer un net à partir du brut. +
    7. +
  7. + + Effectuer une simulation avec les données que l'on souhaite réutiliser + +
    + Par exemple{' '} + + un cadre à 3400 € brut avec des titres-restaurants + + . +
    8. +
  8. + + Aller sur la page de documentation de la donnée à calculer + +
    + Par exemple en cliquant sur « Salaire net » dans le simulateur, ou en + recherchant « Salaire net » dans la recherche en haut à droite. +
    9. +     + ) +} diff --git a/site/source/pages/integration/_images/API_illustration.svg b/site/source/pages/integration/_images/API_illustration.svg new file mode 100644 index 000000000..d2e68549f --- /dev/null +++ b/site/source/pages/integration/_images/API_illustration.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/site/source/pages/integration/images/cci.png b/site/source/pages/integration/_images/cci.png similarity index 100% rename from site/source/pages/integration/images/cci.png rename to site/source/pages/integration/_images/cci.png diff --git a/site/source/pages/integration/illustration.png b/site/source/pages/integration/_images/illustration.png similarity index 100% rename from site/source/pages/integration/illustration.png rename to site/source/pages/integration/_images/illustration.png diff --git a/site/source/pages/integration/illustration_library.svg b/site/source/pages/integration/_images/illustration_library.svg similarity index 100% rename from site/source/pages/integration/illustration_library.svg rename to site/source/pages/integration/_images/illustration_library.svg diff --git a/site/source/pages/integration/images/logo-betagouv.svg b/site/source/pages/integration/_images/logo-betagouv.svg similarity index 100% rename from site/source/pages/integration/images/logo-betagouv.svg rename to site/source/pages/integration/_images/logo-betagouv.svg diff --git a/site/source/pages/integration/images/min-tra.jpg b/site/source/pages/integration/_images/min-tra.jpg similarity index 100% rename from site/source/pages/integration/images/min-tra.jpg rename to site/source/pages/integration/_images/min-tra.jpg diff --git a/site/source/pages/integration/images/pole-emploi.png b/site/source/pages/integration/_images/pole-emploi.png similarity index 100% rename from site/source/pages/integration/images/pole-emploi.png rename to site/source/pages/integration/_images/pole-emploi.png