Complete OTP Verification

Purpose

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

Specification

Link	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/otp-verification/complete-otp-verification
Resource	/api/verifications/{{phone_number}}/actions/complete
Scope	otp:write
Components	OTP Verification service
Using Dictionaries	API paragraph not found
Using Microservices	API paragraph not found
Protocol type	REST
Request type	PATCH
Sync/Async	Sync

Logic

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:
`{` `"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"`
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:
`{` `"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:
`{` `"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) :
`{` `"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 :
{ "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

Preconditions

API paragraph not found

Global and configuration parameters

API paragraph not found

Input parameters

Input parameter

Values

Type

Description

Example

phone_number

(required)

String

+380508887700

Attributes

Attribute	Values	Type	Description	Example
code		Number		3782

Filters

None

Request structure

See on Apiary

Example

Request example

curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer c2778f3064753ea70de870a53795f5c9" \
     --data-binary "{
  \"code\": 3782
}" \
'http://ehealth.com/api/verifications/{phone_number}/actions/complete'

Authorize

Request to process the request using a token in the headers

Headers

Example

Header example

Content-Type: application/json
Authorization: Bearer c2778f3064753ea70de870a53795f5c9

Validate request (JSON schema)

API paragraph not found

Validation data request

API paragraph not found

Processing

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

See on Apiary

Example:

Response example

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "req-adasdoijasdojsda"
  },
  "data": {
    "id": "7d23bebb-1cf3-4221-bf21-18aada444756",
    "status": "NEW",
    "code_expired_at": "2017-07-10T12:20:16.300597Z",
    "active": true
  }
}

Post-processing processes

API paragraph not found

HTTP status codes

HTTP status code	Message	What caused the error
200

Backward compatibility

API paragraph not found