diff --git a/code/API_definitions/README.MD b/code/API_definitions/README.MD deleted file mode 100644 index e9cd5a5..0000000 --- a/code/API_definitions/README.MD +++ /dev/null @@ -1 +0,0 @@ -Here you can add your definition file(s). Delete this README.MD file after the first file is added. diff --git a/code/API_definitions/kyc-fill-in.yaml b/code/API_definitions/kyc-fill-in.yaml index 9dbbb51..940333f 100644 --- a/code/API_definitions/kyc-fill-in.yaml +++ b/code/API_definitions/kyc-fill-in.yaml @@ -40,14 +40,15 @@ info: * An endpoint to request information related to an end user against the account data bound to their phone number. - ## Authorization and authentication + + # Authorization and authentication The "Camara Security and Interoperability Profile" provides details of how an API consumer requests an access token. Please refer to Identity and Consent Management (https://github.com/camaraproject/IdentityAndConsentManagement/) for the released version of the profile. The specific authorization flows to be used will be agreed upon during the onboarding process, happening between the API consumer and the API provider, taking into account the declared purpose for accessing the API, whilst also being subject to the prevailing legal framework dictated by local legislation. In cases where personal data is processed by the API and users can exercise their rights through mechanisms such as opt-in and/or opt-out, the use of three-legged access tokens is mandatory. This ensures that the API remains in compliance with privacy regulations, upholding the principles of transparency and user-centric privacy-by-design. - + # Identifying the phone number from the access token @@ -63,12 +64,21 @@ info: - If the subject can be identified from the access token and the optional `phoneNumber` field is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same phone number is identified by these two methods, as the server is unable to make this comparison. - ### Additional CAMARA error responses - The list of error codes in this API specification is not exhaustive. Therefore the API specification may not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. + + # Additional CAMARA error responses + + The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`. Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version. As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API. + + + + # Request body strictness + + This API rejects requests with JSON request bodies that contain properties not declared in this specification, at any nesting level. Unknown properties result in a `400 INVALID_ARGUMENT` response. + license: name: Apache 2.0 @@ -99,6 +109,8 @@ paths: tags: - Fill-in summary: Providing information related to a customer identity stored the account data bound to the customer's phone number. + description: | + Provides information related to a customer identity stored the account data bound to the customer's phone number. operationId: KYC_Fill-in @@ -157,7 +169,7 @@ paths: - kyc-fill-in:nationality parameters: - - $ref: '#/components/parameters/x-correlator' + - $ref: '../common/CAMARA_common.yaml#/components/parameters/x-correlator' requestBody: required: true @@ -176,7 +188,7 @@ paths: description: OK headers: x-correlator: - $ref: "#/components/headers/X-Correlator" + $ref: "../common/CAMARA_common.yaml#/components/headers/x-correlator" content: application/json: @@ -212,143 +224,159 @@ paths: nationality: ES "400": - $ref: '#/components/responses/Generic400' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic400' "401": - $ref: '#/components/responses/Generic401' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic401' "403": - $ref: '#/components/responses/Generic403' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic403' "404": - $ref: '#/components/responses/Generic404' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic404' "422": - $ref: '#/components/responses/Generic422' + $ref: '../common/CAMARA_common.yaml#/components/responses/Generic422' components: securitySchemes: openId: + description: OpenID Connect authentication type: openIdConnect openIdConnectUrl: https://example.com/.well-known/openid-configuration - headers: - X-Correlator: - description: Correlation id for the different services - required: false - schema: - $ref: "#/components/schemas/XCorrelator" - - parameters: - x-correlator: - name: x-correlator - in: header - description: Correlation id for the different services - schema: - $ref: "#/components/schemas/XCorrelator" - schemas: + + Iso3166Alpha2: + type: string + format: iso3166-1-alpha-2 + description: Two-letter ISO 3166-1 alpha-2 country code + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + example: "DE" + KYC_FillinRequest: type: object + description: KYC Fill-In request body properties: phoneNumber: - type: string - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" + $ref: "../common/CAMARA_common.yaml#/components/schemas/PhoneNumber" KYC_FillinResponse: type: object + description: KYC Fill-In response body properties: phoneNumber: - type: string - description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. - pattern: '^\+[1-9][0-9]{4,14}$' - example: "+123456789" + $ref: "../common/CAMARA_common.yaml#/components/schemas/PhoneNumber" idDocument: type: string + maxLength: 50 description: Id number associated to the id_document of the customer stored on the Operator's system. idDocumentType: type: string + maxLength: 50 enum: [passport, national_id_card, residence_permit, diplomatic_id, driver_licence, social_security_id, other] description: Type of the official identity document provided. idDocumentExpiryDate: type: string format: date + maxLength: 10 description: Expiration date of the identity document (ISO 8601). name: type: string + maxLength: 256 description: Complete name of the customer stored on the Operator's system. It is usually composed of first/given name and last/family/sur- name in a country. Depending on the country, the order of first/give name and last/family/sur- name varies, and middle name could be included. It can use givenName, middleNames, familyName and/or familyNameAtBirth. For example, in ESP, name+familyName; in NLD, it can be name+middleNames+familyName or name+middleNames+familyNameAtBirth, etc. givenName: type: string + maxLength: 100 description: First/given name or compound first/given name of the customer on the Operator's system. familyName: type: string + maxLength: 150 description: Last name, family name, or surname of the customer stored on the Operator's system. nameKanaHankaku: type: string + maxLength: 256 description: Complete name of the customer in Hankaku-Kana format (reading of name) for Japan, stored on the Operator's system. nameKanaZenkaku: type: string + maxLength: 256 description: Complete name of the customer in Zenkaku-Kana format (reading of name) for Japan, stored on the Operator's system. middleNames: type: string + maxLength: 100 description: Middle name/s of the customer stored on the Operator's system. familyNameAtBirth: type: string + maxLength: 150 description: Last/family/sur- name at birth of the customer stored on the Operator's system. address: type: string + maxLength: 256 description: Complete address of the customer stored on the Operator's system. For some countries, it is built following the usual concatenation of parameters in a country, but for other countries, this is not the case. For some countries, it can use streetName, streetNumber and/or houseNumberExtension. For example, in ESP, streetName+streetNumber; in NLD, it can be streetName+streetNumber or streetName+streetNumber+houseNumberExtension. streetName: type: string + maxLength: 150 description: Name of the street of the customer's address on the Operator's system. It should not include the type of the street. streetNumber: type: string + maxLength: 20 description: The street number of the customer's address on the Operator's system. Number identifying a specific property on the 'streetName'. postalCode: type: string + maxLength: 20 description: The postal code or Zip code of the customer's address, stored on the Operator's system. region: type: string + maxLength: 100 description: Region/prefecture of the customer's address, stored on the Operator's system. locality: type: string + maxLength: 100 description: Locality of the customer's address, stored on the Operator's system. country: type: string - description: Country of the customer's address stored on the Operator's system. Format ISO 3166-1 alpha-2. + description: Country of the customer's address. Format ISO 3166-1 alpha-2. + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + example: "JP" houseNumberExtension: type: string + maxLength: 20 description: House number extension of the customer stored on the Operator's system. Specific identifier of the house needed depending on the property type. For example, number of apartment in an apartment building. birthdate: type: string format: date + maxLength: 10 description: Birthdate of the customer, in ISO 8601 calendar date format (YYYY-MM-DD), stored on the Operator's system. email: type: string format: email + maxLength: 254 description: Email address of the customer in the RFC specified format (local-part@domain), stored on the Operator's system. gender: type: string + maxLength: 6 description: Gender of the customer stored on the Operator's system (Male/Female/Other). enum: - MALE @@ -357,180 +385,21 @@ components: cityOfBirth: type: string + maxLength: 100 description: City where the customer was born. countryOfBirth: type: string description: Country where the customer was born. Format ISO 3166-1 alpha-2. + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + example: "JP" nationality: type: string description: ISO 3166-1 alpha-2 code of the customer’s nationality. In the case a customer has more than one nationality, it is supposed to be the nationality related to the ID document provided in the match request. - - ErrorInfo: - type: object - required: - - status - - code - - message - properties: - status: - type: integer - description: HTTP response status code - code: - type: string - description: A human-readable code to describe the error - message: - type: string - description: A human-readable description of what the event represents - - XCorrelator: - type: string - pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ - example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" - - responses: - Generic400: - description: Bad Request - headers: - x-correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 400 - code: - enum: - - INVALID_ARGUMENT - examples: - GENERIC_400_INVALID_ARGUMENT: - description: Invalid Argument. Generic Syntax Exception - value: - status: 400 - code: INVALID_ARGUMENT - message: Client specified an invalid argument, request body or query param. - - Generic401: - description: Unauthorized - headers: - x-correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 401 - code: - enum: - - UNAUTHENTICATED - examples: - GENERIC_401_UNAUTHENTICATED: - description: Request cannot be authenticated and a new authentication is required - value: - status: 401 - code: UNAUTHENTICATED - message: Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required. - - Generic403: - description: Forbidden - headers: - x-correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 403 - code: - enum: - - PERMISSION_DENIED - - examples: - GENERIC_403_PERMISSION_DENIED: - description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security - value: - status: 403 - code: PERMISSION_DENIED - message: Client does not have sufficient permissions to perform this action. - - Generic404: - description: Not found - headers: - x-correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 404 - code: - enum: - - IDENTIFIER_NOT_FOUND - examples: - GENERIC_404_IDENTIFIER_NOT_FOUND: - description: The phone number is not associated with a CSP customer account - value: - status: 404 - code: IDENTIFIER_NOT_FOUND - message: The phone number provided is not associated with a customer account - - Generic422: - description: Unprocessable Content - headers: - x-correlator: - $ref: "#/components/headers/X-Correlator" - content: - application/json: - schema: - allOf: - - $ref: "#/components/schemas/ErrorInfo" - - type: object - properties: - status: - enum: - - 422 - code: - enum: - - SERVICE_NOT_APPLICABLE - - MISSING_IDENTIFIER - - UNNECESSARY_IDENTIFIER - examples: - GENERIC_422_SERVICE_NOT_APPLICABLE: - description: Service is not applicable for the provided phone number - value: - status: 422 - code: SERVICE_NOT_APPLICABLE - message: The service is not applicable for the provided phone number - GENERIC_422_MISSING_IDENTIFIER: - description: No phone number has been provided either explicitly or associated with the access token - value: - status: 422 - code: MISSING_IDENTIFIER - message: No phone number has been provided - GENERIC_422_UNNECESSARY_IDENTIFIER: - description: An explicit phone number has been provided when one is already associated with the access token - value: - status: 422 - code: UNNECESSARY_IDENTIFIER - message: An explicit phone number has been provided when one is already associated with the access token + pattern: ^[A-Z]{2}$ + minLength: 2 + maxLength: 2 + example: "JP" diff --git a/documentation/API_documentation/kyc-fill-in-API-Readiness-Checklist.md b/documentation/API_documentation/kyc-fill-in-API-Readiness-Checklist.md deleted file mode 100644 index ab68c13..0000000 --- a/documentation/API_documentation/kyc-fill-in-API-Readiness-Checklist.md +++ /dev/null @@ -1,29 +0,0 @@ -# API Readiness Checklist - -Checklist for kyc-fill-in 0.4.1 in release r1.3 - -| Nr | API release assets | alpha | release-candidate | initial
public | stable
public | Status | Reference information | -|----|----------------------------------------------|:-----:|:-----------------:|:-------:|:------:|:----:|:----:| -| 1 | API definition | M | M | M | M | Y | [link](/code/API_definitions/kyc-fill-in.yaml) | -| 2 | Design guidelines from Commonalities applied | O | M | M | M | Y | [r3.4](https://github.com/camaraproject/Commonalities/releases/tag/r3.4) | -| 3 | Guidelines from ICM applied | O | M | M | M | Y | [r3.3](https://github.com/camaraproject/IdentityAndConsentManagement/releases/tag/r3.3) | -| 4 | API versioning convention applied | M | M | M | M | Y | | -| 5 | API documentation | M | M | M | M | Y | Embedded documentation into API spec - [link](/code/API_definitions/kyc-fill-in.yaml) | -| 6 | User stories | O | O | O | M | Y | [link](/documentation/API_documentation/KnowYourCustomer_User_Story.md) | -| 7 | Basic API test cases & documentation | O | M | M | M | Y | [link](/code/Test_definitions/kyc-fill-in.feature) | -| 8 | Enhanced API test cases & documentation | O | O | O | M | N | | -| 9 | Test result statement | O | O | O | M | N | | -| 10 | API release numbering convention applied | M | M | M | M | Y | r1.3 | -| 11 | Change log updated | M | M | M | M | Y | [link](/CHANGELOG.md) | -| 12 | Previous public release was certified | O | O | O | M | N | | -| 13 | API description (for marketing) | O | O | M | M | Y | [wiki link](https://lf-camaraproject.atlassian.net/wiki/x/d4AzC) | - -To fill the checklist: -- in the line above the table, replace the api-name, api-version and the rx.y by their actual values for the current API version and release. -- in the Status column, put "Y" (yes) if the release asset is available or fulfilled in the current release, a "N" (no) or a "tbd". Example use of "tbd" is in case an alpha or release-candidate API version does not yet provide all mandatory assets for the release. -- in the Reference information column, provide the relative links (from the API repository home folder) to the release asset once available, the applicable release numbers (not versions) of Commonalities and ICM, and any other relevant links or information. -- For the point 12: The Reference information comment shall reference a note (e.g. "see (1)") under the checklist table to be added that states the certified company(s) as can be found on the following link: [GSMA Open Gateway Portal](https://open-gateway.gsma.com/). - -Note: the checklists of a public API version and of its preceding release-candidate API version can be the same. - -The documentation for the content of the checklist is here: see API Readiness Checklist section in the [API Release Process](https://lf-camaraproject.atlassian.net/wiki/x/jine).