diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8c222a5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing Guidelines + +*All forms of contribution (i.e. raising issues and preparing pull requests) to the SFTI community is very welcome and highly appreciated!* + +### Contents +- [First-time Contribution](#first-time-contribution) +- [How To Contribute](#how-to-contribute) +- [SFTI Guidelines and Coding Style](#sfti-guidelines-and-coding-style) + + +> **This guide serves to set clear expectations for everyone involved within SFTI's pension stream so that we can improve the API specifications together while also creating a welcoming space for everyone to participate. Following these guidelines will help preserve high-quality SFTI specifications and enable smooth and fast integrations supported by the whole SFTI community.** + +# First-time contribution +If you are not yet part of the SFTI community but interested in contributing to the improvement and further development of the SFTI API's, then please follow the process described below. + +**1. Request a GitHub account** +Send an email to [info@common-api.ch](mailto:info@common-api.ch) and explain your interest to contribute to SFTI API's. SFTI will get in touch with the requestor to clarify next steps. + +**2. Onboarding to SFTI and GitHub** +Your request will be checked normally within 5 working days. If your request is approved, you will get the information on how to collaborate in GitHub. + +**3. Complete GitHub onboarding** +After completing the onboarding process, you can access GitHub and start contributing. + +**4. Start contributing** +Now you are ready to contribute. Please check the process [how to contribute](#how-to-contribute) in the next section. + +# How to contribute +If you are already part of the SFTI community and interested in contributing to the improvement and further development of the pension API's, then please follow the process described below. + +**1. Raise an issue** +At GitHub raise an [issue](https://github.com/swissfintechinnovations/ca-pension/issues), describe the initial situation and elaborate on the added value of the proposed change/improvement. + +**2. Present issue / change request** +After a first review by the API stream leads you will be be invited to present and pitch the proposed change/improvement in the next working group meeting of the SFTI community. + +**3. Create a pull request** +If the working group participants agree to your proposal a pull [request](https://github.com/swissfintechinnovations/ca-pension/pulls) will be created. Depending on the agreement with the stream leads, the pull request is created by you or the stream leads. + +**4. Approval of pull request** +The pull request will then be presented and discussed in one of the next working group meetings. The participants then decide if the pull request can be approved and implemented (by merging it to the main branch) in one of the next releases. + +![contrib](https://github.com/swissfintechinnovations/ca-payment/assets/116151702/4cad55d8-aed0-42cb-a2b6-b956d217fd0f) + +# SFTI guidelines and coding style +At the [SFTI Wiki](https://github.com/swissfintechinnovations/.github/wiki) you can find more information about SFTI's API design principles, collaboration and implementation guidelines. If you contribute on API specifications, please pay special attention to SFTI's [style guide](https://github.com/swissfintechinnovations/.github/wiki/Style-Guide-Common-APIs) and [naming conventions](https://github.com/swissfintechinnovations/.github/wiki/Naming-Conventions). Make sure you are familiar with both guidelines before submitting your pull request, as there are special [GitHub Actions](https://github.com/swissfintechinnovations/.github/wiki/Github-Actions) implemented to check these rules automatically. Pull requests that do not pass all checks cannot be merged in to the main branch. diff --git a/pensionAPI.yaml b/pensionAPI.yaml index e9702b9..f81cb28 100644 --- a/pensionAPI.yaml +++ b/pensionAPI.yaml @@ -540,20 +540,18 @@ paths: '404': $ref: '#/components/responses/standard404' - /statements/{pensionStatementId}/statement-for-qr-code: + /statements/{pensionStatementId}/compact-statements: get: - summary: Get the pension statement QR code json for the specified id + summary: Get the compact pension statement for the specified id description: | Provides the pension statement for the specified id as a compact json - in the insured person's preferred language. This json has the same content - and structure as defined in the PensionStatementBasic schema. Its sole purpose - is to provide a compact json so it can be fit into a QR code. This endpoint - should not be used otherwise and will be deprecated once the QR code is no - longer needed. + in the insured person's preferred language. Its sole purpose is to provide + a compact json for use cases with tight data volume limits such as e.g. + a QR code. This endpoint should not be used otherwise. If the pension fund is unable to provide a json for the request id, the error code 400 should be returned. - operationId: getPensionStatementQrCodeJson + operationId: getPensionStatementCompact tags: - statement parameters: @@ -569,285 +567,7 @@ paths: content: application/json: schema: - type: object - description: Basic, reduced pension statement consisting of only the most important information in compact form for QR code. - required: - - pi - - e - - pp - - rd - - pst - - ppl - - ora - - era - - sd - - rc - - rb - - f - - rpm - - hoaw - properties: - psi: - $ref: '#/components/schemas/PensionStatementId' - pi: - $ref: '#/components/schemas/PersonId' - e: - type: object - description: Details of the insured person's employer. - required: - - en - properties: - ei: - $ref: '#/components/schemas/EmployerId' - en: - $ref: '#/components/schemas/EmployerName' - in: - $ref: '#/components/schemas/Industry' - pp: - type: object - description: Pension provider (foundation) administering the policy. - required: - - ppn - properties: - ppi: - $ref: '#/components/schemas/ProviderId' - ppn: - $ref: '#/components/schemas/ProviderName' - ppa: - type: object - description: Postal address of the pension provider. - properties: - st: - $ref: '#/components/schemas/Street' - pbo: - $ref: '#/components/schemas/PoBox' - to: - $ref: '#/components/schemas/Town' - pc: - $ref: '#/components/schemas/PostalCode' - cc: - $ref: '#/components/schemas/CountryCode' - pu: - $ref: '#/components/schemas/PortalUrl' - pn: - $ref: '#/components/schemas/PortalName' - psn: - $ref: '#/components/schemas/PensionStatementNo' - rd: - $ref: '#/components/schemas/Date' - description: Reference date of pension statement. - pst: - $ref: '#/components/schemas/PensionStatementType' - ed: - $ref: '#/components/schemas/Date' - description: Entry date into the pension fund. - ppl: - type: array - description: List of related pension plans. - items: - type: object - required: - - pln - properties: - pli: - $ref: '#/components/schemas/PlanId' - pln: - $ref: '#/components/schemas/PlanName' - ospn: - $ref: '#/components/schemas/OptionalSavingsPlanName' - ora: - type: integer - format: int32 - description: Age (in month since birth) for ordinary retirement. - examples: - - 780 - era: - type: integer - format: int32 - description: Age (in month since birth) for earliest possible retirement. - examples: - - 696 - sd: - type: object - description: Details of salary relevant for insurance. - required: - - ds - - ism - - isre - - isri - - el - properties: - ds: - $ref: '#/components/schemas/DeclaredSalary' - bo: - $ref: '#/components/schemas/Bonus' - as: - $ref: '#/components/schemas/AdditionalSalary' - osc: - $ref: '#/components/schemas/OtherSalaryComponent' - ism: - $ref: '#/components/schemas/InsuredSalaryMandatory' - isre: - $ref: '#/components/schemas/InsuredSalaryRetirement' - isri: - $ref: '#/components/schemas/InsuredSalaryRisk' - el: - $ref: '#/components/schemas/EmploymentLevel' - rc: - type: object - description: Retirement capital balances for the past and projections for the future. - required: - - brd - - bmr - - prb - properties: - tc: - $ref: '#/components/schemas/TransferredCapital' - tcm: - $ref: '#/components/schemas/TransferredCapitalMandatory' - brd: - $ref: '#/components/schemas/BalanceReferenceDate' - bmr: - $ref: '#/components/schemas/BalanceMandatoryReferenceDate' - bec: - $ref: '#/components/schemas/BalanceEndCurrentYear' - bmc: - $ref: '#/components/schemas/BalanceMandatoryEndCurrentYear' - prb: - type: array - description: > - Projected retirement benefits for a series of retirement ages. - The list contains projections for each integer retirement age from 58 to the - regular retirement age. For persons of 58 or older, the list is restricted - to retirement ages higher than their current age. - items: - type: object - required: - - ra - - cb - - cbm - - p - properties: - ra: - $ref: '#/components/schemas/RetirementAge' - cb: - $ref: '#/components/schemas/CapitalBalance' - cbm: - $ref: '#/components/schemas/CapitalBalanceMandatory' - cbni: - $ref: '#/components/schemas/CapitalBalanceNoInterest' - cbnim: - $ref: '#/components/schemas/CapitalBalanceNoInterestMandatory' - p: - $ref: '#/components/schemas/Pension' - crm: - $ref: '#/components/schemas/ConversionRateMandatory' - crs: - $ref: '#/components/schemas/ConversionRateSupplementary' - cre: - $ref: '#/components/schemas/ConversionRateEnveloping' - ir: - type: object - description: A set of interest rates. - properties: - irms: - $ref: '#/components/schemas/InterestRate' - description: Saving interest rate for mandatory coverage (in percent). - examples: - - 6.800 - irss: - $ref: '#/components/schemas/InterestRate' - description: Saving interest rate for supplementary coverage (in percent). - examples: - - 5.500 - ires: - $ref: '#/components/schemas/InterestRate' - description: Saving enveloping interest rate for combined mandatory and supplementary coverage (in percent). - examples: - - 6.300 - irme: - $ref: '#/components/schemas/InterestRate' - description: Interest rate for mandatory coverage (in percent), used specifically in purchase calculations. - examples: - - 6.800 - irse: - $ref: '#/components/schemas/InterestRate' - description: Interest rate for supplementary coverage (in percent), used specifically in purchase calculations. - examples: - - 5.500 - iree: - $ref: '#/components/schemas/InterestRate' - description: > - Enveloping interest rate for combined mandatory and supplementary coverage (in percent), - used specifically in purchase calculations. - examples: - - 6.300 - irmp: - $ref: '#/components/schemas/InterestRate' - description: > - Projection rate for mandatory coverage (in percent), - used specifically for calculating projected future values. - examples: - - 6.800 - irsp: - $ref: '#/components/schemas/InterestRate' - description: > - Projection rate for supplementary coverage (in percent), - used specifically for calculating projected future values. - examples: - - 5.500 - irep: - $ref: '#/components/schemas/InterestRate' - description: > - Projection enveloping interest rate for combined mandatory and supplementary coverage (in percent), - used specifically for calculating projected future values. - examples: - - 6.300 - rb: - type: object - description: Benefits in case of death or disability to work. - required: - - pd - - cpd - - ppd - - opd - - mlswpb - properties: - pd: - $ref: '#/components/schemas/PensionDisability' - cpd: - $ref: '#/components/schemas/ChildPensionDisability' - ppd: - $ref: '#/components/schemas/PartnerPensionDeath' - opd: - $ref: '#/components/schemas/OrphanPensionDeath' - lswpb: - $ref: '#/components/schemas/LumpSumWithoutPensionBenefits' - mlswpb: - $ref: '#/components/schemas/MinimalLumpSumWithPensionBenefits' - f: - type: object - description: Contributions for financing the policy. - required: - - fcsip - - fcse - properties: - fcsip: - $ref: '#/components/schemas/ContributionSavingsInsuredPerson' - fcse: - $ref: '#/components/schemas/ContributionSavingsEmployer' - fcrip: - $ref: '#/components/schemas/ContributionRiskInsuredPerson' - fcre: - $ref: '#/components/schemas/ContributionRiskEmployer' - fcaip: - $ref: '#/components/schemas/ContributionAdministrationInsuredPerson' - fcae: - $ref: '#/components/schemas/ContributionAdministrationEmployer' - rpm: - $ref: '#/components/schemas/RegularPurchaseMaxAmount' - hoaw: - $ref: '#/components/schemas/HomeOwnershipAvailableForWithdrawal' + $ref: '#/components/schemas/PensionStatementCompact' '401': $ref: '#/components/responses/standard401' '404': @@ -1404,8 +1124,9 @@ components: PensionStatementBasic: type: object - description: Basic, reduced pension statement consisting of only the most important information. + description: Pension statement consisting of the basic pension statement information. required: + - timeStamp - personId - employer - pensionProvider @@ -1423,6 +1144,9 @@ components: properties: pensionStatementId: $ref: '#/components/schemas/PensionStatementId' + timeStamp: + $ref: '#/components/schemas/DateTime' + description: Date and time of generation of the PensionStatement personId: $ref: '#/components/schemas/PersonId' employer: @@ -1469,6 +1193,150 @@ components: homeOwnershipAvailableForWithdrawal: $ref: '#/components/schemas/HomeOwnershipAvailableForWithdrawal' + PensionStatementCompact: + type: object + description: Reduced pension statement consisting of only the most important pension statement information in compact form. + required: + - ts + - pi + - e + - pp + - rd + - pst + - ppl + - ora + - era + - sd + - rc + - rb + - rpm + - hoaw + properties: + ts: + $ref: '#/components/schemas/DateTime' + description: Date and time of generation of the PensionStatement + pi: + $ref: '#/components/schemas/PersonId' + e: + type: object + description: Details of the insured person's employer. + required: + - en + properties: + en: + $ref: '#/components/schemas/EmployerName' + pp: + type: object + description: Pension provider (foundation) administering the policy. + required: + - ppn + properties: + ppn: + $ref: '#/components/schemas/ProviderName' + rd: + $ref: '#/components/schemas/Date' + description: Reference date of pension statement. + pst: + $ref: '#/components/schemas/PensionStatementType' + ppl: + type: object + description: > + The pension plan defines various conditions for the occupational pension provision + of the insured employees, incl. the contributions and insured benefits. + required: + - pln + properties: + pln: + $ref: '#/components/schemas/PlanName' + ora: + type: integer + format: int32 + description: Age (in month since birth) for ordinary retirement. + examples: + - 780 + era: + type: integer + format: int32 + description: Age (in month since birth) for earliest possible retirement. + examples: + - 696 + sd: + type: object + description: Details of salary relevant for insurance. + required: + - ds + - ism + - isre + - isri + - el + properties: + ds: + $ref: '#/components/schemas/DeclaredSalary' + ism: + $ref: '#/components/schemas/InsuredSalaryMandatory' + isre: + $ref: '#/components/schemas/InsuredSalaryRetirement' + isri: + $ref: '#/components/schemas/InsuredSalaryRisk' + el: + $ref: '#/components/schemas/EmploymentLevel' + rc: + type: object + description: Retirement capital balances for the past and projections for the future. + required: + - brd + - bmr + - prb + properties: + brd: + $ref: '#/components/schemas/BalanceReferenceDate' + bmr: + $ref: '#/components/schemas/BalanceMandatoryReferenceDate' + prb: + type: array + description: > + Projected retirement benefits for a series of retirement ages. + The list contains projections for each integer retirement age from 58 to the + regular retirement age. For persons of 58 or older, the list is restricted + to retirement ages higher than their current age. + items: + type: object + required: + - ra + - cb + - p + properties: + ra: + $ref: '#/components/schemas/RetirementAge' + cb: + $ref: '#/components/schemas/CapitalBalance' + p: + $ref: '#/components/schemas/Pension' + rb: + type: object + description: Benefits in case of death or disability to work. + required: + - pd + - cpd + - ppd + - opd + - mlswpb + properties: + pd: + $ref: '#/components/schemas/PensionDisability' + cpd: + $ref: '#/components/schemas/ChildPensionDisability' + ppd: + $ref: '#/components/schemas/PartnerPensionDeath' + opd: + $ref: '#/components/schemas/OrphanPensionDeath' + mlswpb: + $ref: '#/components/schemas/MinimalLumpSumWithPensionBenefits' + rpm: + $ref: '#/components/schemas/RegularPurchaseMaxAmount' + hoaw: + $ref: '#/components/schemas/HomeOwnershipAvailableForWithdrawal' + Policy: type: object description: Details of policy. @@ -2944,6 +2812,13 @@ components: examples: - 2018-04-13 + DateTime: + type: string + description: Common date-time format. + format: date-time + examples: + - 2018-04-13T11:11:11Z + securitySchemes: bearerAuthentication: type: http