Сторінка знаходиться в процесі розробки. Інформація на ній може бути застарілою.

https://e-health-ua.atlassian.net/wiki/spaces/EN/pages/17591304241 (remove the link block before publishing the document)

1 Properties of a REST API method document
2 Purpose
3 Logic
4 Configuration parameters
5 Dictionaries
6 Input parameters
- 6.1 Attributes
7 Request structure
8 Headers
9 Request data validation
- 9.1 Authorize
10 Processing
- 10.1 Verify code
- 10.2 Matched
- 10.3 Not matched
11 Response structure examples
12 HTTP status codes
13 Post-processing processes
14 Technical modules where the method is used

Properties of a REST API method document

Document type	Метод REST API
Document title	[DRAFT] REST API Complete OTP Verification [API-010-001-001-0350]
Guideline ID	GUI-0011
Author	@
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-010-001-001-0350
Microservices (namespace)	MPI
Component	Master Patient Index
Component ID	COM-010-001
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/otp-verification/complete-otp-verification
Resource	{{host}}/api/verifications/{{phone_number}}/actions/complete
Scope	otp:write
Protocol type	REST
Request type	PATCH
Sync/Async	Sync
Public/Private	Public

Purpose

This method is designed to verify that provided in the declaration request phone number is valid and is in service. Final stage

Logic

N/A

Configuration parameters

N/A

Dictionaries

N/A

Input parameters

	Input parameter	Mandatory	Type	Description	Example

	Input parameter	Mandatory	Type	Description	Example
1	phone_number		String	Required	phone_number	String	Required	+380508887700
2

Attributes

Attribute	Values	Type	Description	Example

Attribute	Values	Type	Description	Example
code		Number		3782

Request structure

See on API-specification

{
  "code": 3782
}

Headers

Request data validation

Authorize

Request to process the request using a token in the headers

Processing

To confirm the verification, you must enter the phone number and OTP (one-time code) in the system

If the code entered by the user is correct, the system will send a reply:

If the code entered by the user is correct, the system will send a reply:
`{` `"meta": {` `"code": 200,` `"url": "https://example.com/resource",` `"type": "object",` `"request_id": "req-adasdoijasdojsda"` `},` `"data": {` `"id": "7d23bebb-1cf3-4221-bf21-18aada444756",` `"status": "VERIFIED",` `"code_expired_at": "2017-07-10T12:20:16.300597Z",` `"active": true` `}` `}`

Where:

id- request id
code_expired_at= the time until which the code is valid in the system
Active- code activity status in the system
1. "TRUE" - if verification is possible:
  1. when creating a default query,
  2. if there were less than 4 attempts to use
  3. if the code has not expired (up to 300 seconds after creation)
2. "FALSE" - if verification is impossible:
  1. if code has been already used
  2. if more then 3 repayment attemptes has been made
  3. if the verification deadline has expired, including successful verification
Status- displays the verification status

`"status": "NEW"`	`"status": "VERIFIED"`	`"status": "UNVERIFIED"`	`"status": "EXPIRED"`	`"status": "CANCELED"`

`"status": "NEW"`	`"status": "VERIFIED"`	`"status": "UNVERIFIED"`	`"status": "EXPIRED"`	`"status": "CANCELED"`
when creating a query, by default	upon successful completion	upon unsuccessful verification (more than 3 attempts)	the code has expired коду	installed by the provider, in case the SMS cannot be delivered

If the code entered by the user is incorrect, then:

If this is one of the first three incorrect attempts, the system will respond:

If this is one of the first three incorrect attempts, the system will respond:
`{` `"error": {` `"message": "Invalid verification code",` `"type": "forbidden"` `},` `"meta": {` `"code": 403,` `"request_id": "xxx",` `"type": "object",` `"url": "http://api-svc.verification/verifications/{{phone_number}}/actions/complete"` `}` `}`

If this is the fourth (or more) failed attempt to enter the code, the system will respond:

If this is the fourth (or more) failed attempt to enter the code, the system will respond:
`{` `"error": {` `"message": "Maximum attempts exceed",` `"type": "forbidden"` `},` `"meta": {` `"code": 403,` `"request_id": "xxx",` `"type": "object",` `"url": "http://api-svc.verification/verifications/{{phone_number}}/actions/complete"` `}` `}`

If the correct code is entered after the expiration of the code (OTP_LIFETIME = 300 seconds) :

If the correct code is entered after the expiration of the code (OTP_LIFETIME = 300 seconds) :
`{` `"data": {` `"active": false,` `"code_expired_at": "2020-03-13T15:14:45.640890Z",` `"id": "6b5c534c-1664-4fdc-8128-96caaeb27089",` `"status": "expired"` `},` `"meta": {` `"code": 200,` `"request_id": "xxx",` `"type": "object",` `"url": "http://api-svc.verification/verifications/{{phone_number}}/actions/complete"` `}` `}`

If an incorrect code is entered after the expiration of the code :

If an incorrect code is entered after the expiration of the code :

If an incorrect code is entered after the expiration of the code :

If an incorrect code is entered after the expiration of the code :
{ "error": { "message": "Invalid verification code", "type": "forbidden" }, "meta": { "code": 403, "request_id": "xxx", "type": "object", "url": "http://api-svc.verification/verifications/{{phone_number}}/actions/complete" } }

Verify code

Search active code for phone number
Check code expiration period
Compare codes

Matched

Deactivate code
Add phone number to verified_phones

Not matched

Deactivate code
Invoke Send verification code
Return error

Response structure examples